has three levels of documentation organization Chapters Pages Page Sections 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 Znai Znai
It may be useful to compare documentation design to an object oriented programming approach Chapters as Pages as Page Sections as 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 packages classes methods
Each documentation must have file in its root This file contains chapters and pages This is a file for this documentation Take a look at the left side bar and compare it with the file content The top entry corresponds to the directory of the same name The nested entry corresponds to the file toc toc introduction what is this getting started flow structure landing names page references page toc lookup paths search footer support footnotes 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 styling top header deployment additional files hub introduction setup build artifacts watch example references domain api znai development local build release notes 2024 2023 2022 2021 introduction rationale rationale md
Only a first level heading is treated as a first class citizen Part of TOC Smallest unit of search result Nested sub headings only add visual distinction within a page Sub heading content of sub heading Sub Sub heading content of sub sub heading # First Class Citizen ## Sub heading content of sub heading ### Sub Sub heading content of sub sub heading
Keep headings text simple and short Try to avoid putting extra formatting into headings inconsistent heading look and feel can feel distracting Note Only inlined code and Links are allowed as part of the heading content Consider sticking to a regular text
Each documentation must have the file in its root This file contains documentation display name type and optional information meta json JSON View On 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