Markdown style guide

This style guide covers our conventions when writing Markdown files in Sphinx documentation.

This page shows relevant directives from Sphinx and reStructuredText. It also shows some examples of reStructuredText.

We use the following directives from sphinxcontrib-opendataservices and sphinxcontrib-opendataservices-jsonschema:

Layout

transition

before

after

before

----

after

Generic admonitions

Note

A note

.. note::
   A note

In addition to note, there are (see demo):

  • note

  • hint

  • tip

  • important

  • attention

  • caution

  • warning

  • danger

  • error

Custom title

Content

.. admonition:: Custom title

   Content

Version admonitions

deprecated

Deprecated since version 1.2: Use this alternative instead.

.. deprecated:: 1.2
   Use this alternative instead.

versionadded

Added in version 1.2.

.. versionadded:: 1.2

Added in version 1.2: Brief explanation of the addition, if needed.

.. versionadded:: 1.2
   Brief explanation of the addition, if needed.

versionchanged

Changed in version 1.2: Brief explanation of the change.

.. versionchanged:: 1.2
   Brief explanation of the change.

References

See the documentation on Markdown footnotes (or reStructuredText footnotes).

seealso

See also

Example: A link

A short description of its relevance.

Example: A link

A short description of its relevance.

.. seealso::

   Example: A link
      A short description of its relevance.
   Example: A link
      A short description of its relevance.

glossary

a term

its definition

another term
a synonym

its definition

a term reference.

.. glossary::

   a term
      its definition
   another term
   a synonym
      its definition

:term:`a term` reference.

Code blocks

code-block

A caption
2{
3   "some": "text",
4   "key": "value"
5}

.. code-block:: json
   :linenos:
   :lineno-start: 2
   :emphasize-lines: 1-2,4
   :caption: A caption
   :name: label-to-reference

   {
      "some": "text",
      "key": "value"
   }

literalinclude

.. literalinclude:: filename.ext
   :language: json

The path can be relative to the file, or relative to the top source directory if starting with /.

It accepts the same options as code-block. It also accepts:

:lines: 1-2,4

Show specific lines only

:start-after: text to match

Show lines after the first matching line

:end-before: text to match

Show lines before the first matching line

:start-at: text to match

Show lines as of the first matching line

:end-at: text to match

Show lines up to the first matching line

:lineno-match:

Show the original line numbers

:prepend:

Prepend a line

:append:

Append a line

Lists

Definition list

who

what

where

when

who
   what
where
   when

Field list

who:

what

where:

when

:who:
   what
:where: when