How this site works (v1.0)

This single page is the placeholder for the whole docs tree: one product (docs), one category (functional), one version folder (v1.0). Replace or grow this tree under content/ when you ship real products (e.g. api, web, mobile).

How the repo fits together

• content/<product>/<doc_type>/<version>/ — Markdown sources; products and doc types are discovered automatically (see scripts/generate_site_data.py).
• make build — Refreshes permalinks, regenerates _data/*.yml, runs Jekyll → static site in _site/.
• Toolbar — Picks product → doc type → version; sidebar lists sibling pages in the same version folder and an outline from headings on this page.
• _config.yml — Branding, environment URLs, optional logo and favicon (ico); validated on build.
• Functional layout — The functional layout appends the Functional doc checklist aside (_includes/functional_checklist.html), not from your Markdown body. Set front matter show_functional_checklist: false on a page to hide it.

Sample workflow (Mermaid)

Diagrams use fenced mermaid blocks; they render in the browser after build.

flowchart LR
  A[Edit Markdown] --> B[make site-data]
  B --> C[make build test]
  C --> D[make serve]

In practice make build already runs permalinks, make site-data, and Jekyll; make serve does the same prep then starts the preview server—you do not need every step as a separate manual run unless you are debugging generators.

If a diagram ever uses text that looks like Liquid tags, wrap that part of the Markdown in Jekyll’s raw tag so the build does not break.

Hello world (code preview)

Fenced blocks with a language tag get syntax highlighting (Rouge). Examples:

Kotlin

fun main() {
    println("Hello, world")
}

JSON

{ "message": "hello", "version": 1 }

Bash

make build && open http://127.0.0.1:4000

Markdown building blocks

Inline: code, bold, italic, link.

Bullets

• Use these for checklists and feature lists.
• Nest ideas under one topic.

Numbered

1. First step
2. Second step
3. Third step

Blockquote

Use blockquotes for callouts, warnings, or quoted text.

Table

Horizontal rule

Images

Put files under assets/images/…. Configure a canonical example path in _config.yml → asset_paths.example_image, then reference it with Liquid so baseurl stays correct:

Next steps

• Copy this folder pattern for more products: content/<product>/functional/v1.0/introduction.md.
• Run make build after structural changes; see versioning.md for version folder naming.