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