In this post I would like to tell you more about Markdown syntax and best practices of using it in TurnAPI editor.
We also recommend everyone to read the official documentation about Markdown syntax here – http://daringfireball.net/projects/markdown/syntax
Those who have never worked with markdown syntax can find it a bit difficult to start writing documentation, but very soon you will understand why we decided to build TurnAPI around it. Those who had relevant experience appreciated our idea immediately!
TurnAPI Markdown © is Different from Markdown
Markdown used in TurnAPI slightly differs from the official standard. We have simplified layout by removing certain elements and added a couple of things which are specific for writing API documentation
TurnAPI supports only 3 levels of headings instead of 6 in markdown or HTML. This restriction allows you to write documentation in simpler way avoiding complex hierarchy.
- <h1> secured by text entered into the title field.
- 2nd level heading <h2> is any text underlined with =======
- 3d level heading <h3> is any text underlined with ——-
- # ## ### etc. not used in defining headings.
# used to define methods. Text after # symbol and until the end of a current document or next # will be considered as a single method. # will be converted into <h3 class=”method”>.
## used to refer to the sections inside the method. ## will be converted into <h4>.
Markdown treats asterisks (*) and underscores (_) as emphasis indicators. Text wrapped in one * or _ will be wrapped in HTML <em> tag; double ** or __ will be wrapped in HTML<strong> tag.
In TurnAPI we use only * and ** respectively for <em> and <strong> tags.
Links can be defined via standard markdown way. However, we recommend using syntax like: [link text] (http://example.com/” Title “) We have also added another way of using shorthand references
[link text](#docID – doc title)
Just try to type in TurnAPI editor (# and you’ll understand what I mean
As I have mentioned above you should use # to define a method.
What is next? How to describe a new method? Start writing #MyMethodName… from new line then skip one more line and write method content. To declare parameters we have another emphasis – @. Further you can continue using headings, params in the way you need.
The result should look something like this:
To add an image use ![alt text](http://example.com/my-image.png).
Code blocks are enclosed in ~ and there should be 4 or more ~~~~~~. The number of ~ at the beginning and the end of the code block should be the same. In the next line you should specify code language after ~. After that you can paste your code snippet.
TurnAPI supports ordered (numbered) and unordered (bulleted) lists.
Unordered lists use hyphens as list markers:
Ordered lists use numbers followed by periods: