A well-organized documentation hierarchy helps your users find the answers they need quickly and intuitively. GitDocAI uses a simple but powerful structure of sections, folders, and pages to keep your content logical, scalable, and easy to navigate.
By planning your structure before you write, you ensure that as your product grows, your documentation can grow seamlessly alongside it.
Understanding the Hierarchy
GitDocAI organizes your content into three distinct levels.
flowchart TD
A["Section (e.g., Documentation)"] --> B["Folder (e.g., Getting Started)"]
A --> C["Folder (e.g., Connecting Data Sources)"]
B --> D["Page: Welcome to GitDocAI"]
B --> E["Page: Using the Setup Wizard"]
C --> F["Page: Connecting Git Repositories"]
C --> G["Page: Syncing Repository Content"]Sections: The highest level of organization. Sections often represent entirely different manuals or areas of your site (e.g., "Product Documentation", "API Reference", "Tutorials").
Folders: Used to group related pages together under a specific topic or workflow (e.g., "Getting Started", "Publishing & Customization"). Folders can be assigned icons to make them stand out in the sidebar.
Pages: The actual markdown files containing your content. Pages are nested inside folders or directly under sections.
Keep your folder names short and action-oriented (like "Managing Content" or "Connecting Data Sources") to make the sidebar easy to scan.
Setting Up Your Structure
Follow these steps to build a logical flow for your readers.
- 1
Define your top-level sections
Decide on the primary pillars of your documentation. If you only have one main guide, a single "Documentation" section is perfect. If you have distinct audiences (like developers vs. end-users), create separate sections for each.
- 2
Group content into folders
Break your section down into chronological or thematic folders. A standard flow usually starts with a "Getting Started" folder, moves into core feature folders, and ends with advanced topics or troubleshooting.
- 3
Assign folder icons
Give your folders visual context by assigning icons (like a rocket for "Getting Started" or a globe for "Publishing"). This helps users visually anchor themselves in the navigation menu.
- 4
Order your pages logically
Determine the sequence of pages within each folder. Use the
orderproperty to ensure pages flow naturally from basic concepts to advanced configurations.
Page Metadata and Visibility
Every page in your hierarchy comes with metadata settings that control what information is displayed to the reader. You can toggle these on or off depending on your documentation style.
| Setting | Description |
|---|---|
show_author | Displays the name or avatar of the person who wrote the page. Great for internal wikis or community-driven docs. |
show_reading_time | Shows an estimated time to read (e.g., "5 min read"). Helps set expectations for longer guides. |
show_publish_date | Displays the date the page was originally published. |
show_update_date | Shows when the page was last modified, assuring users the content is current. |
show_tags | Displays categorical tags associated with the page, making it easier to find related content. |
Slugs (the URL path for your pages) are automatically generated based on your page titles (e.g., "Welcome to GitDocAI" becomes welcome-to-gitdocai). If you change a page title later, you can manually update the slug to match, but be mindful of breaking existing links!
Frequently Asked Questions
Can I nest folders inside other folders?
Currently, GitDocAI supports a flat folder structure within sections (Section > Folder > Page) to keep navigation menus clean and prevent users from getting lost in deeply nested trees.
What happens if I don't put a page in a folder?
Pages that aren't assigned a parent_id (a folder) will appear at the root level of the Section. This is useful for high-level overview pages or standalone indexes.
How do I reorder my content?
Content order is managed via the order numerical value. Lower numbers appear first. For example, a page with order: 0 will appear above a page with order: 1.
Next Steps
Now that you understand how to structure your documentation, dive into creating content or customizing how it looks.