-If you want write access, please ask for it at [#xonotic on FreeNode](https://webchat.freenode.net/), we'll gladly give it to you. There is no way to allow anonymous editing on GitLab.
+Getting access
+--------------
-The official version is on [GitLab](https://gitlab.com/xonotic/xonotic/wikis/home) but we also sync it to [GitHub](https://github.com/xonotic/xonotic/wiki). Please, follow this guide when editing to make sure the wiki works properly on both.
+If you want write access, please tell us your GitLab username on [#xonotic on FreeNode](https://webchat.freenode.net/) or request access on the [main Xonotic project](https://gitlab.com/xonotic/xonotic), we'll gladly give it to you (unfortunately, there is no way to allow anonymous editing on GitLab).
-Filenames
----------
+After that, you can edit the wiki online (there is an Edit button when logged in) or clone it to your machine using git (`git clone git@gitlab.com:xonotic/xonotic.wiki.git`).
-Use dashes in page names, not underscores - dashes get converted to spaces in page titles so we have a nice title on every page
-Interestingly, spaces seem to work fine in filenames for both GitHub and GitLab but I am sure they'd break *something somewhere* so let's stick to dashes.
+Guidelines
+----------
-Subdirectories
---------------
+- Try to keep things short and to the point
+- Don't duplicate information - everything should have a single up-to-date source of truth, other places should link to it
+- Avoid creating lists of stuff (e.g. cvars, command line flags, maps, ...) that people will need to keep up to date manually, it doesn't work. Instead link to where you got the information (e.g. [CACS](https://www.xonotic.org/tools/cacs/)) or teach people how to get it themselves (e.g. `apropos`).
+- Improve things instead of starting from scratch, if the previous author didn't finish, you're not likely to do better if you start from nothing
-Ok to use for images and other assets
-Don't use for pages (the `.md` files) - GitHub doesn't support them properly (it flattens everything - this can cause collisions, plus there is no way to link from subdir to another subdir that works on both GitLab and GitHub)
+GitHub mirror
+-------------
- - Put all `.md` files in root
+The official version of this wiki is on [GitLab](https://gitlab.com/xonotic/xonotic/wikis/home) but we also sync the wiki to [GitHub](https://github.com/xonotic/xonotic/wiki). Please, follow this guide when editing to make sure everything works properly on both.
-Links to pages
--------------
-Use standard markdown links: `[Text](link)` (e.g. `[Back to index](Home)` to get [Back to index](Home))
+### Links to other pages
- - Don't prefix `link` with either `../link` or `/link` - both break on GitHub. Using `./link` seems to work ok but is unnecessary since we have to put everything in root anyway.
+Use standard markdown links: `[Text](link)` (e.g. `[Back to main page](Home)` to get [Back to main page](Home))
+
+- Don't prefix `link` with either `../link` or `/link` - both break on GitHub. Using `./link` seems to work ok but is unnecessary since we have to put everything in root anyway.
+- Use dashes, not spaces: `[Translation guidelines](Translation-guidelines)` for [Translation guidelines](Translation-guidelines). They're interchangeable on GL but spaces will break on GH.
Links don't seem to be case sensitive but it's probably best to use proper capitalization just in case it breaks in some edge case somewhere.
+
+
+### New files
+
+For pages, capitalize at least the first letter of the filename (GitHub doesn't capitalize titles automatically, GitLab will do what it wants anyway).
+
+Use dashes in page names, not underscores, not spaces - dashes get converted to spaces in page titles so we have a nice title on every page. Using GL's editor will pretend to create pages with spaces but the filenames in fact have dashes so use dashes in links, otherwise the GH mirror will look broken. Some pages might have underscores in names for historical reasons - they already have many outside links (from forums, etc.) pointing to them.
+
+It's ok (and preferred) to put images and other assets into subdirectories but we have to **put pages in root** because GitHub doesn't support subdirs properly (it flattens everything - this can cause collisions, plus there is no way to link from subdir to another subdir that works on both GitLab and GitHub).
+
+
+### Automated checking
+
+Neither GL not GH support red links (highlighting broken links) so there's a script in [`assets/check-and-fix.py`](assets/check-and-fix.py) that finds broken links and unreachable files. To use it, clone the wiki and run the script in its root. It can also automatically move or rename files that don't follow the above guidelines if you run it with `--fix`.
projects / xonotic / xonotic.wiki.git / blobdiff