Contributing with the docs

Summing up

1. Log into your github account (or create an account if you don't have one).
2. Edit a page (or create a new one) on the RAwiki. You must use the Markdown markup language. Just check the Markdown caveats below.
3. Sooner or later a maintainer will generate the pages for RAdocs.

RAWiki and RADocs

The RetroAchievements Documentation is divided into two parts:

1. RetroAchievements wiki
2. RetroAchievements docs

The wiki is where these documents are created and edited. Anyone (with a github account) is able to edit the wiki's content. Then, if you have something to share, please edit the wiki!

The RetroAchievements docs website has (almost) the same content as the wiki, but with a more pleasant look. The content of this website is generated by its maintainers using the wiki's content as input.

When a change is made in the wiki this change is NOT instantaneously reflected in the docs. The conversion is performed by a maintainer from time to time.

Markdown caveats

Markdown is a lightweight and extremely easy to learn markup language with plain text formatting syntax. In order to contribute in our project you must know at least the basics of markdown. Here is a good one-page reference: http://commonmark.org/help/, and here you can try a 10 minutes tutorial.

Moreover, this wiki needs to be written in a certain format in order to convert cleanly to the pretty static pages. It's because we use mkdocs) and it uses python markdown and github uses github flavoured markdown, so there are some minor issues of formatting that will need to be addressed.

Headings

The headings (defined by #) should follow a natural progression of the hierarchy of the page contents. But you CANNOT have two title headings (those with only one # symbol). Otherwise they won't show up on the table of contents on the right side of the page

E.G.

# Title
## Main heading one
### Sub Heading one
### Sub heading two
## Main heading two

etc.

Links

Links should follow this syntax

[Link](path to link)

Note: If it is a link to another wiki page it should be a relative path:

[Tips and Tricks](Tips-and-Tricks)

Do NOT use complete a full URL when linking to another wiki page, like this (yeah, this is an example of you should NOT do):

[Tips and Tricks](https://github.com/RetroAchievements/docs/wiki/Tips-and-Tricks)

Images

Links to images should follow the same syntax as the example below:

![Image](http://url/a.png) 

Note:: In order to host images for this documentation project, you can post them in this issue thread here and use the github image hosting hack.

Tables

A simple table looks like this:

First Header | Second Header | Third Header
------------ | ------------- | ------------
Content Cell | Content Cell  | Content Cell
Content Cell | Content Cell  | Content Cell
Content Cell | Content Cell  | Content Cell

It should render like this:

First Header	Second Header	Third Header
Content Cell	Content Cell	Content Cell
Content Cell	Content Cell	Content Cell
Content Cell	Content Cell	Content Cell

You can specify alignment for each column by adding colons to separator lines:

First Header | Second Header | Third Header
:----------- |:-------------:| -----------:
Left         | Center        | Right
Left         | Center        | Right
Left         | Center        | Right

Results:

First Header	Second Header	Third Header
Left	Center	Right
Left	Center	Right
Left	Center	Right

Changelog

Last 10 changes on this page:

• [2019-12-29 12:15] meleu: merging "How RA Documentation Works" page here
• [2019-02-14 10:53] meleu: fix broken link
• [2018-04-25 07:12] meleu: new link for radocs
• [2018-04-04 15:55] meleu: Updated Contributing with the docs (markdown)
• [2018-04-04 15:53] meleu: Updated Contributing with the docs (markdown)
• [2018-04-03 15:20] meleu: Updated Contributing with the docs (markdown)
• [2018-04-03 15:02] meleu: Updated Contributing with the docs (markdown)
• [2018-04-02 18:52] meleu: Updated Editing the Wiki (markdown)