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

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

References#

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

seealso#

See also

Reference: Schema The schema provides a detailed specification of the fields, data structures and rules for publishing OFDS data.

```{seealso}

   Reference: [Schema](http://www.example.com)
      The schema provides a detailed specification of the fields, data structures and rules for publishing OFDS data.
```

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#

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

```json
{
   "some": "text",
   "key": "value"
}
```
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