Documatt logo
  • Product
  • Pricing
  • Resources
    • Sphinx Errors
    • reStructuredText
    • Community
  • Blog
  • Login
  • Try free
  • Product
  • Pricing
  • Sphinx Errors
  • reStructuredText
  • Community
  • Blog
Logo of reStructuredText Reference

reStructuredText Reference

Example based gentle reference of the reStructuredText and Sphinx syntax, directives, roles and common issues. It demonstrates almost all the markup making it also good for testing Sphinx themes. Free and open-source.

Intro

  • reStructuredText overview
  • Directives and roles
  • Sphinx and Docutils
  • Tools and editors

Collections

  • Admonitions
  • Body elements
  • Code examples
  • Images
  • Inline elements
  • Lists
  • Document parts
  • Semantic elements
  • Sphinx additions

Elements

  • admonition
  • attention
  • caution
  • code-block
  • contents
  • danger
  • emphasis
  • enumerated-list
  • error
  • figure
  • file
  • hint
  • image
  • important
  • inline image
  • inline literal
  • literal-block
  • note
  • paragraph
  • parsed-literal-block
  • rubric
  • section
  • seealso
  • sidebar
    • Requires title and content
    • Optional subtitle
    • Directive name in uppercase
    • Complex content
  • strong emphasis
  • subscript
  • substitution
  • superscript
  • tip
  • toctree
  • topic
  • transition
  • warning

Etc.

  • Contributing
reStructuredText Reference sidebar

sidebar#

In collections

  • Document parts

  • Body elements

See official docs.

Sidebar is like miniature document inside the main document. It provides related or reference material. A sidebar is typically displayed as right or left floating box outside the the main text.

See also

The similar purpose, but less strong, has the footnote also.

Requires title and content#

Sidebars need a title right after sidebar:: (note the space after ::) and a content bellow the blank line.

1Sunt cupidatat do esse incididunt cupidatat incididunt nisi anim sint elit incididunt laborum nisi enim. Dolore culpa veniam nulla ullamco. Laboris veniam dolor minim magna.
2
3.. sidebar:: Sidebar title
4
5   Sidebar content is bellow.
6
7Cillum reprehenderit dolor fugiat irure aute qui commodo excepteur ea incididunt minim voluptate ex anim. Enim irure dolor nulla laboris sint deserunt ex. Dolor fugiat officia dolor qui nisi ex. Sit pariatur duis duis exercitation consequat sint. Nisi labore amet eiusmod consequat excepteur excepteur. Voluptate incididunt dolore pariatur nisi eu ipsum amet ullamco id consectetur commodo in velit. Pariatur tempor officia minim officia.

Sunt cupidatat do esse incididunt cupidatat incididunt nisi anim sint elit incididunt laborum nisi enim. Dolore culpa veniam nulla ullamco. Laboris veniam dolor minim magna.

Sidebar title

Sidebar content is bellow.

Cillum reprehenderit dolor fugiat irure aute qui commodo excepteur ea incididunt minim voluptate ex anim. Enim irure dolor nulla laboris sint deserunt ex. Dolor fugiat officia dolor qui nisi ex. Sit pariatur duis duis exercitation consequat sint. Nisi labore amet eiusmod consequat excepteur excepteur. Voluptate incididunt dolore pariatur nisi eu ipsum amet ullamco id consectetur commodo in velit. Pariatur tempor officia minim officia.

Optional subtitle#

You might pass an optional subtitle with the subtitle option.

1Sunt cupidatat do esse incididunt cupidatat incididunt nisi anim sint elit incididunt laborum nisi enim. Dolore culpa veniam nulla ullamco. Laboris veniam dolor minim magna.
2
3.. sidebar:: Sidebar title
4   :subtitle: Optional subtitle
5
6   Sidebar content is bellow.
7
8Cillum reprehenderit dolor fugiat irure aute qui commodo excepteur ea incididunt minim voluptate ex anim. Enim irure dolor nulla laboris sint deserunt ex. Dolor fugiat officia dolor qui nisi ex. Sit pariatur duis duis exercitation consequat sint. Nisi labore amet eiusmod consequat excepteur excepteur. Voluptate incididunt dolore pariatur nisi eu ipsum amet ullamco id consectetur commodo in velit.

Sunt cupidatat do esse incididunt cupidatat incididunt nisi anim sint elit incididunt laborum nisi enim. Dolore culpa veniam nulla ullamco. Laboris veniam dolor minim magna.

Sidebar title

Optional subtitle

Sidebar content is bellow.

Cillum reprehenderit dolor fugiat irure aute qui commodo excepteur ea incididunt minim voluptate ex anim. Enim irure dolor nulla laboris sint deserunt ex. Dolor fugiat officia dolor qui nisi ex. Sit pariatur duis duis exercitation consequat sint. Nisi labore amet eiusmod consequat excepteur excepteur. Voluptate incididunt dolore pariatur nisi eu ipsum amet ullamco id consectetur commodo in velit.

Directive name in uppercase#

Directive name is case insensitive (like all directive and role names). Most documentation and book authors prefer typing directives and roles all in lowercase. However, writing directive name in uppercase corresponds with their “raise attention” objective and improves reStructuredText code readability.”

1.. SIDEBAR:: Sidebar title
2  
3   Writing sidebar in uppercase can be considered as
4   reasonable exception to "all-lowercase" rule.

Complex content#

Any reStructuredText elements can be in sidebar content. As always, you need only to keep correct indentation.

 1Sunt cupidatat do esse incididunt cupidatat incididunt nisi anim sint elit incididunt laborum nisi enim. Dolore culpa veniam nulla ullamco. Laboris veniam dolor minim magna.
 2
 3.. sidebar:: Sidebar title
 4              
 5   This is the sidebar with complex body containing
 6   
 7   - two items
 8   - bullet list
 9   
10   And, code example::
11   
12       $ nano ~/.bash_aliases
13
14Cillum reprehenderit dolor fugiat irure aute qui commodo excepteur ea incididunt minim voluptate ex anim. Enim irure dolor nulla laboris sint deserunt ex. Dolor fugiat officia dolor qui nisi ex. Sit pariatur duis duis exercitation consequat sint. Nisi labore amet eiusmod consequat excepteur excepteur. Voluptate incididunt dolore pariatur nisi eu ipsum amet ullamco id consectetur commodo in velit. Pariatur tempor officia minim officia. Pariatur occaecat nulla enim occaecat incididunt. Elit ea ea excepteur deserunt in et. Consequat amet non ullamco laborum laborum veniam enim est. In anim dolor aliqua esse irure officia sunt reprehenderit nulla fugiat. Adipisicing magna consequat ullamco qui.

Sunt cupidatat do esse incididunt cupidatat incididunt nisi anim sint elit incididunt laborum nisi enim. Dolore culpa veniam nulla ullamco. Laboris veniam dolor minim magna.

Sidebar title

This is the sidebar with complex body containing

  • two items

  • bullet list

And, code example:

$ nano ~/.bash_aliases

Cillum reprehenderit dolor fugiat irure aute qui commodo excepteur ea incididunt minim voluptate ex anim. Enim irure dolor nulla laboris sint deserunt ex. Dolor fugiat officia dolor qui nisi ex. Sit pariatur duis duis exercitation consequat sint. Nisi labore amet eiusmod consequat excepteur excepteur. Voluptate incididunt dolore pariatur nisi eu ipsum amet ullamco id consectetur commodo in velit. Pariatur tempor officia minim officia. Pariatur occaecat nulla enim occaecat incididunt. Elit ea ea excepteur deserunt in et. Consequat amet non ullamco laborum laborum veniam enim est. In anim dolor aliqua esse irure officia sunt reprehenderit nulla fugiat. Adipisicing magna consequat ullamco qui.

<- seealso
strong emphasis ->
Documatt logo
Effortlessly create books and docs in Markdown and reStructuredText. Perfect for tech and novel writers.
© 2025, Documatt.com, s.r.o. and contributors - All rights reserved.

Product

  • What is Documatt
  • Plans & Pricing
  • Tech writing services

Resources

  • Blog
  • Sphinx Errors
  • reStructuredText

Company

  • About us
  • Legal
  • Contact us

Social