# Typography Text formatting and structural elements for readable documentation. This page covers every text-level feature Lumina styles. ## 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: ```markdown # Heading 1 ## Heading 2 ### Heading 3 #### Heading 4 ##### Heading 5 ###### Heading 6 ``` ### Heading 3 #### Heading 4 ##### Heading 5 ###### Heading 6 ## 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: ### MyST ```markdown ## Get started ```{rst-class} lumina-steps ``` ### Install the theme ### Configure Sphinx ``` ### reStructuredText ```rst 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: ```markdown **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: ```markdown > This is a block quote. > > > This is a nested quote. ``` ## Horizontal Rules Use a horizontal rule to visually separate sections. --- The MyST syntax: ```markdown --- ``` ## 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: ```markdown 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: ```markdown :Author: Jane Doe :Version: 2.0 :Status: Draft :Date: 2026-04-02 ``` ## Abbreviations Use HTML `` tags to add tooltip definitions for abbreviations. The HTML output is generated by MyST and rendered via CSS. The MyST syntax: ```html HTML ``` ## Keyboard Input Show keyboard shortcuts using HTML `` 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: ```html Ctrl+C ``` ## 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. > ##### Before you begin > > You need Sphinx 7 or newer and Python 3.10+. Everything else installs with the theme. 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: ```markdown ```{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: ```markdown ```{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: ```markdown {guilabel}`Save changes` {menuselection}`Settings --> Appearance --> Theme` ``` ## Links Standard Markdown links work as expected. - External: [Sphinx Documentation](https://www.sphinx-doc.org) - Internal: [Admonitions](admonitions.html.md) (uses the `{doc}` role) - Section: [Section References](footnotes-and-references.html.md#section-label) in another page (uses the `{ref}` role) The MyST syntax: ```markdown [External link](https://example.com) {doc}`page-name` {ref}`section-label` ``` See [Footnotes & References](footnotes-and-references.html.md) for the full cross-referencing guide. ## Formatting Best Practices