Edit this page
On this page

Typography

Text formatting and structural elements for readable documentation. This page covers every text-level feature Lumina styles.

4 min read

Headings

Headings create the document hierarchy and appear in the right-side table of contents. Lumina renders h1–h6 with a carefully tuned type scale.

The MyST syntax:

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Heading 3

Heading 4

Heading 5
Heading 6

Tip

Use heading level 1 for the page title only — one per page. Start sections with h2, and sub-sections with h3. Lumina’s right-side table of contents displays h2 and h3 by default.

Steps

Number a sequence of sections on a connecting rail, for setup guides and tutorials. Steps are ordinary headings, so each one keeps its anchor link and its entry in the table of contents.

Add the lumina-steps class before the first step heading:

## Get started

```{rst-class} lumina-steps
```

### Install the theme

### Configure Sphinx

Get started
-----------

.. rst-class:: lumina-steps

Install the theme
~~~~~~~~~~~~~~~~~

Configure Sphinx
~~~~~~~~~~~~~~~~

The marked heading and every following heading at the same level become steps, up to the end of the parent section. Put the steps under their own heading, as above, so the sections after them stay unnumbered. Steps can hold any content, including tabs, code blocks, and admonitions.

Install the theme

Add sphinx-lumina-theme to your docs dependencies.

Configure Sphinx

Set html_theme = "lumina" in conf.py.

Build the docs

Run sphinx-build docs docs/_build/html and open index.html.

Inline Formatting

Use inline formatting to emphasize or annotate text.

This text is bold. This text is italic. This text is bold and italic. This is ~~strikethrough~~. This is inline code. This is a subscript and this is a superscript.

The MyST syntax:

**bold** *italic* ***bold and italic*** ~~strikethrough~~ `inline code`
{sub}`subscript` {sup}`superscript`

Paragraphs and Line Breaks

Regular paragraph text flows naturally and wraps at the container width. Multiple sentences in a paragraph are separated by spaces, not line breaks.

This is a second paragraph. A blank line between blocks of text creates a new paragraph.

A line break within a paragraph
is created with a backslash at the end of a line.

Block Quotes

Use block quotes to highlight excerpts or callouts.

This is a block quote. It can contain formatted text, inline code, and other inline elements.

Nested block quotes:

This is the outer quote.

This is a nested quote inside the outer one.

The MyST syntax:

> This is a block quote.
>
> > This is a nested quote.

Horizontal Rules

Use a horizontal rule to visually separate sections.

The MyST syntax:

---

Definition Lists

Definition lists pair a term with its description. Useful for glossaries and option references.

Term 1

Definition for term 1. Can contain inline formatting.

Term 2

First definition for term 2.

Second definition for term 2.

Longer term with details

This definition can span multiple lines and contain additional content like code and emphasis.

The MyST syntax:

Term 1
: Definition for term 1. Can contain **inline formatting**.

Term 2
: First definition for term 2.
: Second definition for term 2.

Field Lists

Field lists are commonly used for metadata, parameters, and structured key-value content.

Author:

Jane Doe

Version:

2.0

Status:

Draft

Date:

2026-04-02

The MyST syntax:

:Author: Jane Doe
:Version: 2.0
:Status: Draft
:Date: 2026-04-02

Abbreviations

Use HTML <abbr> tags to add tooltip definitions for abbreviations.

The HTML output is generated by MyST and rendered via CSS.

The MyST syntax:

<abbr title="Hyper Text Markup Language">HTML</abbr>

Keyboard Input

Show keyboard shortcuts using HTML <kbd> tags.

Press Ctrl+C to copy and Ctrl+V to paste. On macOS, use ⌘+C and ⌘+V.

Open the search modal with Ctrl+K or ⌘+K.

The MyST syntax:

<kbd>Ctrl</kbd>+<kbd>C</kbd>

Topics and Sidebars

A topic is a titled, self-contained block that sits in the flow of the page. A sidebar floats beside the text for asides and related notes; on narrow screens it stacks above the text instead.

Lumina styles both with the same quiet surface used for code captions, so they read as supporting material rather than warnings. Use a sidebar for tangents a reader can skip, like a historical note or an alternative approach, and keep it short so it ends before the next heading. Use a topic when the content belongs in the reading order but deserves its own frame.

The MyST syntax:

```{topic} Before you begin
Topic body.
```

```{sidebar} Did you know?
Sidebar body.
```

Rubrics

A rubric is an informal heading: it labels the content that follows without creating a section or a table-of-contents entry.

Related options

show_toc, show_breadcrumbs, and show_prev_next control the page chrome around the article.

The MyST syntax:

```{rubric} Related options
```

GUI Labels and Menus

Mark up interface text the reader should look for on screen. Menu paths are joined with arrows.

Click Save changes, then open Settings ‣ Appearance ‣ Theme.

The MyST syntax:

{guilabel}`Save changes`
{menuselection}`Settings --> Appearance --> Theme`

Formatting Best Practices

Tip

  • Use bold for key terms on first introduction and UI element names

  • Use italic for emphasis and introducing concepts

  • Use code for file names, commands, configuration keys, and values

  • Use admonitions for important callouts instead of bold paragraphs — they’re more scannable

  • Use definition lists for option references instead of tables when definitions are long