Building Blocks

Znai has three levels of documentation organization:ChaptersPagesPage 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 onesIntroduce chaptersFocus on one thing at a time

Similarity with OOP

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.

Table of Contents

Each documentation must have toc file in its root. This file contains chapters and pages.This is a toc file for this documentation. introduction rationale example getting-started flow structure names page-references lookup-paths search footer support presentation testing shortcuts snippets code-snippets external-code-snippets inlined-code-snippets api-parameters code-references java java-doc groovy typescript cpp json xml open-API CLI math jupyter-notebook markdown layout attention-signs tabs tables columns templates two-sides-pages two-sides-tabs jupyter-notebook-two-sides visuals spoilers smart-bullet-points icons keyboard-shortcuts charts images image-annotations iframe SVG flow-diagrams PlantUml deployment static-content static-hosting synergy-with-testing java REST web-UI configuration basic example-references domain api 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 .

Sub Headings

Only a first level heading is treated as a first class citizen:Part of TOCSmallest 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 content of sub headingcontent of sub sub heading

Meta

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": "Transforms Markdown files into rich, well-structured documentation served in a modern web front-end. Znai provides many custom add-ons that supercharge basic generated docs with advanced layout features, dynamic references to code and test artifacts, and many visual and functional enhancements.", "viewOn": { "link": "https://github.com/testingisdocumenting/znai/blob/master/znai-docs/znai", "title": "View On GitHub" }, "support": { "link": "https://github.com/testingisdocumenting/znai/issues" } }