TurnAPI: Using Markdown Syntax

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

Headings

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>.

Emphasis

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

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 ;)

Methods

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:

Images

To add an image use ![alt text](http://example.com/my-image.png).

Source code

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.

Result:

Lists

TurnAPI supports ordered (numbered) and unordered (bulleted) lists.

Unordered lists use hyphens as list markers:

-   Red
-   Green
-   Blue

Ordered lists use numbers followed by periods:

1.  Bird
2.  McHale
3.  Parish

Share

Leave a Reply

Your email address will not be published. Required fields are marked *

*

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>