Examples of blocks for writing documentation

A collection of examples of non-obvious blocks that can be used when writing documentation.

Admonitions

docs | supported types

CodePreview

!!! note

	You should note that the title will be automatically capitalized.

Note

You should note that the title will be automatically capitalized.

inline usage

inline end inline

Lorem ipsum

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

!!! info inline end "Lorem ipsum"

	Lorem ipsum dolor sit amet, consectetur
	adipiscing elit. Nulla et euismod nulla.
	Curabitur feugiat, tortor non consequat
	finibus, justo purus auctor massa, nec
	semper lorem quam in massa.

Use inline end to align to the right (left for rtl languages).

Lorem ipsum

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.

!!! info inline "Lorem ipsum"

	Lorem ipsum dolor sit amet, consectetur
	adipiscing elit. Nulla et euismod nulla.
	Curabitur feugiat, tortor non consequat
	finibus, justo purus auctor massa, nec
	semper lorem quam in massa.

Use inline to align to the left (right for rtl languages).

Collapsible blocks

docs

???+ note "Open styled details"

	??? danger "Nested details!"
		And more content again.

Open styled details

Nested details!

And more content again.

Footnotes

docs

Footnotes[^1] have a label[^test-label] and the footnote's content.

[^1]: This is a footnote content.
[^test-label]: A footnote on the label: "test-label".

Footnotes¹ have a label² and the footnote's content.

Highlight

docs

CodePreview

```console linenums="42" hl_lines="1 4-6"
$ echo hello world!
hello world!

$ git clone git@github.com:dd/Meringue.git
$ cd Meringue
$ hatch run docs:serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  mkdocstrings_handlers: Formatting signatures requires Black to be
			installed.
INFO     -  Documentation built in 1.96 seconds
INFO     -  [02:05:37] Watching paths for changes: 'docs/src', 'mkdocs.yml',
			'docs/theme', 'meringue', 'README.md'
INFO     -  [02:05:37] Serving on http://127.0.0.1:7000/
```

```pycon
>>> for word in ("Hello", "mkdocstrings!"):
...     print(word, end=" ")
...
Hello mkdocstrings!
```

$ echo hello world!
hello world!

$ git clone git@github.com:dd/Meringue.git
$ cd Meringue
$ hatch run docs:serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  mkdocstrings_handlers: Formatting signatures requires Black to be
			installed.
INFO     -  Documentation built in 1.96 seconds
INFO     -  [02:05:37] Watching paths for changes: 'docs/src', 'mkdocs.yml',
			'docs/theme', 'meringue', 'README.md'
INFO     -  [02:05:37] Serving on http://127.0.0.1:7000/

>>> for word in ("Hello", "mkdocstrings!"):
...     print(word, end=" ")
...
Hello mkdocstrings!

Inline

docs

`#!console $ python3 manage.py runserver`

$ python3 manage.py runserver

`#!python3 import this`

import this

Annotates

docs

```python
import this # (1)
```

1.  :fontawesome-brands-python: Simple is better than complex.

import this # (1)

1. Simple is better than complex.

Diagrams

docs

```mermaid
graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];
```

graph LR
  A[Start] --> B{Error?};
  B -->|Yes| C[Hmm...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Yay!];

Content tabs

docs

=== "Tab 1"
	Markdown **content**.

	Multiple paragraphs.

=== "Tab 2"
	More Markdown **content**.

	- list item a
	- list item b

Tab 1Tab 2

Markdown content.

Multiple paragraphs.

More Markdown content.

• list item a
• list item b

Smart Symbols

docs

Markdown	Result	Markdown	Result
(tm)	™	<--	←
(c)	©	<-->	↔
(r)	®	=/=	≠
c/o	℅	1/4, etc.	¼, etc.
+/-	±	1st 2nd etc.	1st 2nd etc.
-->	→

Keys

docs

++ctrl+alt+delete++

Ctrl+Alt+Del

Icons and Emojis

docs | icon search

:fontawesome-brands-twitter:{ .twitter } :smile: :heart: :thumbsup:

Tooltips

docs

[Hover me](https://example.com "I'm a tooltip!")

Hover me

Lists

docs

CodePreview

- [X] item 1
	* [X] item A
	* [ ] item B
		more text
		+ [x] item a
		+ [ ] item b
		+ [x] item c
	* [X] item C
- [ ] item 2
- [ ] item 3

• item 1
  • item A
  • item B more text
    • item a
    • item b
    • item c
  • item C
• item 2
• item 3

Tables

docs

CodePreview

First Header | Second Header
------------ | -------------
Content Cell | Content Cell
Content Cell | Content Cell

First Header	Second Header
Content Cell	Content Cell
Content Cell	Content Cell

---

1. This is a footnote content. ↩

2. A footnote on the label: "test-label". ↩

Authors: Dmitry Dobrynin

---