Markdown Crash Course & Standards

Table of Contents

Each page has a toc metadata property that dictates whether a table of contents, i.e. a list of links within the page is generated and displayed. toc is set to true by default. There's usually no reason to not have a table of contents.

Each h1 or h2 header on the page ends up in the table of contents. So in the Markdown below, Foo, Bar, and Baz would end up in the TOC:

# Foo

Here's some stuff

## Bar

Some more stuff

### A Sub-heading

## Baz

Wiki Links

The docs use a wiki links system, which will make your life a lot easier. This enables you to link to docs within the Basho docs by name rather than by needing to specify a full URL. So if you need to insert a link to, say, the Managing Strong Consistency doc, you don't need to do <a href="...">Link</a>. You only need to do something like this:

For more information on this, see the [[Managing Strong Consistency]]
doc.

Sometimes, though, you'll want to link to an internal doc but you'll want the link to say something that isn't the title, for example if you want to link to the Managing Strong Consistency doc but want the link to say "this tutorial" instead. Here's how you do that:

For more information, see [[this tutorial|Managing Strong Consistency]].

Notice the | between the link content and the title of the doc.

You can also link to specific places in the docs using the wiki link system. If there's a h1 or h2 header in any doc, the docs will automatically generate an anchor tag that you can link to. So if there's a #Enabling-Strong-Consistency link in the Managing Strong Consistency doc, you can link to it like this:

In order to do that, you must [[enable strong consistency|Managing
Strong Consistency#Enabling-Strong-Consistency]].

Code Samples

Our goal is to provide code samples for all official Basho client libraries. The currently available clients are Java, Ruby, Python, and Erlang, with more on the way in the coming weeks and months. Some good examples of code sample blocks can be found on this page.

The order of the code blocks should correspond to how widely used the libraries are. The current ordering is Java, Ruby, Python, Erlang. Adjust as you see fit when new libraries come on board.

You'll also want to provide curl examples for Riak's HTTP API whenever applicable.

Because interfaces can vary so widely from client to client, you may need to provide additional explanatory material within the block. This has been done quite frequently throughout the docs.

Notes

In this section of a live doc, scroll down a bit and you'll see a section with a greenish background that says Note on the HTTP API. Insert these notes whenever you see fit. You'll need to do these in plain HTML rather than Markdown. Here's an example:

<div class="note">
<div class="title">This is the title</div>
This is the content of the note.
</div>