# How to use markdown in Juicebox docs

Markdown makes sections and code blocks easy, but cross-referencing hard.

- Wrap lines at 80 characters
- **EVERY** section title must be unique.


## Code blocks in Markdown

Code blocks are easy with triple back-ticks. Here's an example

```
def a():
  return 2.0
```

Here's some python highlighted code.

``` python
class PostInsightCommand(PostToSlackCommand):
    """
    Post a snapshot to slack.

    Requires hook_url to be configured in app.metadata.
    Text and image_title can also be configured in app.metadata to
    customize this command.
    """

    class Meta:
        name = 'post-insight'
        label = 'Post an insight'
        icon = 'icon-lightbulb-o'
        data_type = 'slice'
        context = 'slice'
        response_action = 'display'
```


## How to build links in Markdown

This is a [Orbit slice](/topics/juicebox_reference/slices/orbit.html) reference.
It uses Markdown links and a full absolute path to the file. You can link 
directly to a section like this:
[Header background](/topics/styling/backgrounds.html#header-background). This 
link will break if docs are re-organized.


## Using directives

Wrap restructured text directives as follows.

```eval_rst

.. code-block:: none
     :linenos:
     :emphasize-lines: 3,5
     :caption: An example code-block with everything turned on.
     :name: Full code-block example in markdown

     # Comment line
     import System
     System.run_emphasis_line
     # Long lines in code blocks create a auto horizontal scrollbar
     System.exit!
```

Some directives don't work.

```eval_rst

.. contents::

```