`` tag or an element with ``role=main``, and there should only be one per page. This node is the one that contains all the page content to be indexed. Example: .. code-block:: html :emphasize-lines: 10-12 ...

This content isn't processed

All content inside the main node is processed

If a main node isn't found, we try to infer the main node from the parent of the first section with a ``h1`` tag. Example: .. code-block:: html :emphasize-lines: 10-20 ...

This content isn't processed

First title

The parent of the h1 title will be taken as the main node, this is the div tag.

Second title

More content

If a section title isn't found, we default to the ``body`` tag. Example: .. code-block:: html :emphasize-lines: 5-7 ...

Content

Irrelevant content ~~~~~~~~~~~~~~~~~~ If you have content inside the main node that isn't relevant to the page (like navigation items, menus, or search box), make sure to use the correct role or tag for it. Roles to be ignored: - ``navigation`` - ``search`` Tags to be ignored: - ``nav`` Special rules that are derived from specific documentation tools applied in the generic parser: .. https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#adding-line-numbers - ``.linenos``, ``.lineno`` (line numbers in code-blocks, comes from both MkDocs and Sphinx) - ``.headerlink`` (added by Sphinx to links in headers) - ``.toctree-wrapper`` (added by Sphinx to the table of contents generated from the ``toctree`` directive) Example: .. code-block:: html :emphasize-lines: 3-5

... ...

Sections ~~~~~~~~ Sections are stored in a dictionary composed of an ``id``, ``title`` and ``content`` key. Sections are defined as: * ``h1-h7``, all content between one heading level and the next header on the same level is used as content for that section. * ``dt`` elements with an ``id`` attribute, we map the ``title`` to the ``dt`` element and the content to the ``dd`` element. All sections have to be identified by a DOM container's ``id`` attribute, which will be used to link to the section. How the id is detected varies with the type of element: * ``h1-h7`` elements use the ``id`` attribute of the header itself if present, or its ``section`` parent (if exists). * ``dt`` elements use the ``id`` attribute of the ``dt`` element. To avoid duplication and ambiguous section references, all indexed ``dl`` elements are removed from the DOM before indexing of other sections happen. Here is an example of how all content below the title, until a new section is found, will be indexed as part of the section content: .. code-block:: html :emphasize-lines: 2-10, 12-17, 21-26

Section title

Content to be indexed

This is also part of the section and will be indexed as well

This is the start of a new section

...

This is also a valid section title

This is the content of the third section.

Sections can be contained in up to two nested tags, and can contain other sections (nested sections). Note that the section content still needs to be below the section title. Example: .. code-block:: html :emphasize-lines: 3-11,14-21

Section title

Content to be indexed

This is also part of the section

This is the start of a sub-section

With the h tag within two levels

.. note:: The title of the first section will be the title of the page, falling back to the ``title`` tag. Other special nodes ~~~~~~~~~~~~~~~~~~~ - **Anchors**: If the title of your section contains an anchor, wrap it in a ``headerlink`` class, so it won't be indexed as part of the title. .. code-block:: html :emphasize-lines: 3

Section title ¶

- **Code blocks**: If a code block contains line numbers, wrap them in a ``linenos`` or ``lineno`` class, so they won't be indexed as part of the code. .. code-block:: html :emphasize-lines: 3-7

1 2 3

First line
   Second line
   Third line

Overriding the default search ----------------------------- Static sites usually have their own static search index, and search results are retrieved via JavaScript. Read the Docs overrides the default search for Sphinx projects only, and provides a fallback to the original search in case of an error or no results. Sphinx ~~~~~~ Sphinx's basic theme provides the `static/searchtools.js`_ file, which initializes search with the ``Search.init()`` method. Read the Docs overrides the ``Search.query`` method and makes use of ``Search.output.append`` to add the results. A simplified example looks like this: .. code-block:: js var original_search = Search.query; function search_override(query) { var results = fetch_resuls(query); if (results) { for (var i = 0; i < results.length; i += 1) { var result = process_result(results[i]); Search.output.append(result); } } else { original_search(query); } } Search.query = search_override; $(document).ready(function() { Search.init(); }); Highlights from results will be in a ``span`` tag with the ``highlighted`` class (``This is a result``). If your theme works with the search from the basic theme, it will work with Read the Docs' SSS. .. _`static/searchtools.js`: https://github.com/sphinx-doc/sphinx/blob/275d9/sphinx/themes/basic/static/searchtools.js Other static site generators ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ All projects that have HTML pages that follow the conventions described in this document can make use of the server side search from the dashboard or by calling the API. Supporting more themes and static site generators ------------------------------------------------- All themes that follow these conventions should work as expected. If you think other generators or other conventions should be supported, or content that should be ignored or have an especial treatment, or if you found an error with our indexing, let us know in `our issue tracker`_. .. _our issue tracker: https://github.com/readthedocs/readthedocs.org/issues/ .. [*] For Sphinx projects, the content of the main node is provided by an intermediate step in the build process, but the HTML components from the node are preserved.