How to convert a documentation page to markdown
References for the markdown syntax
Official traditional markdown syntax: http://daringfireball.net/projects/markdown/syntax
Github flavored markdown that extends the traditional markup: https://help.github.com/articles/github-flavored-markdown
Note: The only difference between the github flavored and the traditional markdown is the usage of the underscore: https://help.github.com/articles/github-flavored-markdown#multiple-underscores-in-words
Use UpperCamelCase convention, for example: FrameworkConcepts.md.
How to convert
Copy, paste a documentation content to an editor and reformat it with the markdown syntax. In the case that the documentation page has a table of contents, ignore the table of contents.
Leave links intact but rename to the UpperCamelCase.md convention.
Things to pay attention at conversion:
- Header levels
When editing table content with markdown, only simple markdown syntax in one single line can be nested in the table.
- The highlighted words such as option names in the document
Use single backticks in markdown syntax: http://daringfireball.net/projects/markdown/syntax#code
In the case of using actual html for a table, for example, the backticks won't work inside the html, wrap those words in <code> element.
- Code blocks and syntax highlighting
Images and other attachments
All images we've identified so far are small and suitable to be checked into github alongside our docs pages. Flag the issue if you run into an image which seems unsuitably large.