TYPO3 Logo
Writing Documentation
Release: master

Loading data.

BASICS

  • About this guide
  • Help & Support
  • Basic principles
  • Documentation content style guide
    • Spelling
    • Spelling, terms and glossary
    • Directories and file names
    • Examples
    • Formats (reST, Markdown)
    • Menu hierarchy
    • Coding guidelines for reST files
    • Guidelines for creating images
    • Commit messages
    • Licenses
  • reStructuredText & Sphinx
    • Introduction
    • Basic reST & Sphinx syntax
    • Common pitfalls
      • Problems with headers
      • Problems with links
      • Problems with indents
      • Problems with inline style
      • Problems with lists
    • reST & Sphinx cheat sheet
    • reST & Sphinx reference
      • Bold, Italic etc.
      • Hyperlinks & cross referencing
      • Code blocks with syntax highlighting
      • Inline code & text roles
      • Headlines and sections
      • Toctree and the hierarchical structure of a manual
      • Including files
      • Bullet lists
      • Numbered lists
      • Definition lists
      • List items as buttons
      • Styled numbered sections (bignums)
      • Images
      • Embed YouTube videos
      • Tip, Note, Important etc. (Admonitions)
      • Comments
      • Tables
      • Special characters
      • Orphaned pages
      • Clever reST
      • Special styles

HOWTOS

  • How to write good content
    • Tips for writing good content
    • Writing a tutorial
    • Writing Resources
  • How to document an extension
    • Start extension documentation from the example manual
    • Start documentation with the extension builder
    • Register for docs.typo3.org
    • Webhook
    • Reregister versions
    • FAQ
    • Contribute to system extensions
    • Contribute to third-party extensions
  • How to contribute to official documentation
    • Workflow #1: “Edit on GitHub”
    • Workflow #2: “Local editing and rendering with Docker”
    • How You Can Help
  • Tools for Editing reST
  • How to render documentation
    • Rendering the documentation with Docker
    • Rendering the documentation with Docker Compose
    • Troubleshooting local rendering with Docker
  • How to work with GitHub

ADVANCED

  • How to add translations
  • Update documentation for new releases
  • Guidelines for reviewing manuals

MAINTAINERS

  • For maintainers
    • Backport changes
  • Index
  • Appendix
    • Example Toctree
      • Topic1
        • Subtopic 1
        • Subtopic 2
    • Information for editing this guide
  • Sitemap

PAGE CONTENTS

  • Menu hierarchy
    • Multi-file solution
    • Single-file solution
  1. Start
  2. Documentation content style guide
  3. Menu hierarchy
Edit on GitHub View source

Menu hierarchy¶

Technically, the file hierarchy on disc must not affect the menu hierarchy in any way. But, as a general convention, we use the common practice that the file hierarchy reflects the menu hierarchy.

Multi-file solution¶

So, the menu structure for the files described under Directories and file names

Documentation/
|
 --> Index.rst
|
 --> Topic1/
       |
       -> Index.rst
       -> Subtopic1.rst
       -> Subtopic2.rst

would look something like this:

Documentation/Index.rst:

.. toctree::
   :hidden:

   Topic1/Index

Documentation/Topic1/Index.rst

.. toctree::
   :hidden:

   Subtopic1
   Subtopic2

See Example Toctree to see how this is rendered.

../_images/toctree.png

Single-file solution¶

What you can also do, is put everything into one file, e.g. Index.rst contains:

=======
Chapter
=======

Topic 1
=======

Subtopic 1
----------

some text

Subtopic 2
----------

some text

The rendered result will look the same as the multi-file example above, meaning the menu hierarchy and the rendered headings on the page.

Tip

Whatever variant you choose, it depends what is already common practice in the manual you are working on and what is easiest to manage.

  • Previous
  • Next
  • Home
  • Contact
  • Issues
  • Repository

Last updated: Jan 04, 2021 17:40

Last rendered: Jan 15, 2021 20:08

TYPO3 Theme 4.4.2

© Copyright since 1999 by the TYPO3 Documentation Team
  • Legal Notice
  • Privacy Policy