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#

New in version 1.2.

.. versionadded:: 1.2

New 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