Writing pages

In Docara the project files are the source of truth. Markdown holds the text and structure of a page, and JSON files hold the settings of the site, a section and a single page. The build turns them into HTML, a search index and receipts for the checks.

The author’s path

1. Write the page in Markdown: headings, lists, links, tables, code and page metadata.
2. Place the pages in the menu: sections, order, hidden pages and the top menu.
3. For several languages, build a multilingual site.
4. When a page address changes, declare a redirect.
5. If you like, turn on the checks of page profiles and documentation freshness.
6. If Markdown is not enough, find a component.
7. Check that the pages work for every reader.
8. Set up the appearance in Site settings and build and check the result.

Do not edit the build output

build_*, the receipts in build_*.docara/ (resolved-page-plans.json, redirects.json and others) and _docara/component-catalog.json are created anew on every build. If the result is wrong, fix the source Markdown or JSON and build again.

Documentation and landing pages

Both kinds of pages — documentation (docs) and landing (landing) — use one content format, one SIMAI Framework release and one set of safety rules. Only the frame differs: a documentation page with a menu and an outline, or a focused page without them. More in Layout regions.