In Lumocs, the hierarchical structure of your documentation is determined using
parent front-matter in your Markdown files. This allows for
the creation of a structured navigation sidebar and organized content
Table of Content
- First Level: Main Sections
- Second Level: Subsections
- Recommended File Structure
The first level typically consists of main sections or categories. These are top-level items that act as general buckets or categories for your content.
--- title: "Getting Started" nav_order: 1 ---
To prevent a section with children from being collapsed, use front matter option
The second level includes subsections or specific topics under the main
sections. To define a second-level item, you need to specify the
front-matter and set its value to the
title of the first-level item.
--- title: "Installation" parent: "Getting Started" nav_order: 1 ---
For easier maintenance and organization, it's beneficial to follow a recommended file structure:
First Level Pages: These can either be saved with their title as the filename directly under
/docs/src/, or if you intend to have a sub-level under this page, be saved as
index.mdwithin their respective directories.
Second Level Pages: Create a subdirectory within the first-level directory, named after the first-level topic. Save the second-level pages as separate
.mdfiles within these subdirectories.
Here's an example showing a two-level hierarchy:
/docs/src/ |-- index.md |-- contributing.md |-- getting-started/ | |-- index.md | |-- installation.md | |-- configuration.md |-- usage/ | |-- index.md | |-- hierarchical-structure.md | |-- another-subtopic.md
In this structure:
contributing.mdare first-level pages without children.
usage/index.mdare first-level pages with children.
getting-started/configuration.mdetc. are second-level pages.
- Ensure that the
nav_orderis set appropriately to define the order of appearance in the navigation sidebar.
- While Lumocs supports up to three levels of hierarchy, always consider the user experience. Too many nested levels might make navigation confusing.
Remember, a clear and organized structure can enhance the readability and usability of your documentation. Use the hierarchical capabilities and recommended file structure wisely to create a seamless experience for your readers.