Znai has three levels of documentation organization:Chapters Pages Page Sections Znai encourages authors to split their content across multiple pages.If you feel like you need to use nested headings, consider moving your content hierarchy one level up:Split overlong page into multiple ones Introduce chapters Focus on one thing at a time

It may be useful to compare documentation design to an object-oriented programming approach:Chapters as packages Pages as classes Page Sections as methods It is a bad practice to have a class with loosely related methods. Similarly, it is a bad practice to have a long page with loosely related sections.

Each documentation must have toc file in its root. This file contains chapters and pages.This is a toc file for this documentation. introduction what-is-this getting-started flow structure landing names page-references page-toc lookup-paths search footer support presentation testing-is-documenting shortcuts snippets code-snippets external-code-snippets snippets-manipulation snippets-highlighting code-comments inlined-code-snippets api-parameters code-references json xml open-API CLI math jupyter-notebook cpp python java groovy markdown visuals attention-signs images image-annotations cards charts mermaid-diagrams SVG icons headings text-badge spoilers keyboard-shortcuts smart-bullet-points flow-diagrams graphviz-diagrams PlantUml iframe layout tabs tables columns templates two-sides-pages two-sides-tabs jupyter-notebook-two-sides python content-extraction description-extraction auto-reference CPP doxygen-setup description-extraction auto-reference java content-extraction description-extraction auto-reference synergy-with-testing web-UI REST-API business-logic plugins plugin-types default-parameters development configuration basic deployment additional-files example-references domain api znai-development local-build release-notes 2024 2023 2022 2021 Take a look at the left side bar and compare it with the file content.The top entry, introduction , corresponds to the directory of the same name. The nested entry, rationale , corresponds to the file rationale.md .

Only a first level heading is treated as a first class citizen:Part of TOC Smallest unit of search result # First Class Citizen Nested sub headings only add visual distinction within a page. ## Sub heading content of sub heading ### Sub Sub heading content of sub sub heading Sub heading content of sub heading Sub Sub heading content of sub sub heading

Each documentation must have the meta.json file in its root. This JSON file contains documentation display name, type, and optional View On information. { "title": "Znai", "type": "User Guide", "category": "Documentation", "description": "Build functional, maintainable, beautiful User Guides with markdown and Znai plugins. Instant pages navigation. Local search. Multiple integrations to work with Python, Java, C++, OpenAPI, etc. Transform \"getting started\" sections into slideshow for your workshops. Manage multiple documentations with self-deployed znai hub.", "viewOn": { "link": "https://github.com/testingisdocumenting/znai/blob/master/znai-docs/znai", "title": "View Markdown" }, "support": { "link": "https://github.com/testingisdocumenting/znai/discussions", "title": "GitHub" } }