Factorizer/Cluster ERP WikiCluster ERP Türkçe
Home / Contributing

How-to guide

Write a wiki page

How to add or update a page of the Cluster ERP wiki under the documentation standard, with its Turkish twin, and build the static HTML site.

This guide adds a new page to the wiki in docs/wiki/, or updates an existing one, so that it meets the documentation standard (docs/wiki/_standard/DOC_STANDARD.md) and builds into the static HTML site. It covers placement, front matter, citations, admonitions, diagrams, the Turkish twin, and the build script docs/wiki/_build/build.py. The full rules are in the standard and the style checklist (docs/wiki/_standard/STYLE_CHECKLIST.md); this page is the working sequence.

Prerequisites

  • Read the documentation standard (docs/wiki/_standard/DOC_STANDARD.md) and the information architecture (docs/wiki/_standard/INFORMATION_ARCHITECTURE.md).
  • For the build: Python with the packages markdown, pygments, and yaml (docs/wiki/_build/build.py:22-23, docs/wiki/_build/build.py:37-41). For diagrams: the Mermaid package installed with npm install in docs/wiki/_build/ (docs/wiki/_build/package.json, docs/wiki/_build/build.py:524-528).

Steps

  1. Find the row for the page in the information architecture. It gives the folder, the file name, and the page type. If no row fits, add one and name it in your change.
  2. Copy the template for the page type from docs/wiki/_standard/templates/ and its .tr.md twin. A decision record uses the explanation template with the headings "Context", "Decision", "Consequences", "Where the code enforces it", and "Related pages".
  3. Fill the front matter. title, description, lang, type, section, stage, verified_commit, and verified_date are mandatory; audience is optional. The build parses the block as YAML and stops with an error when it does not parse (docs/wiki/_build/build.py:181-194).

```yaml

title: Event bus description: How modules exchange events and queries through the EventBus without importing each other. lang: en type: explanation section: platform stage: 2 audience: developer verified_commit: 92f8051 verified_date: 2026-11-09

```

  1. Write one H1 equal to the title, then a summary of two to four sentences. The build removes the first H1 from the body and draws the title in the page header instead (docs/wiki/_build/build.py:337-338).
  2. Open every file you describe and cite it inline as path:line or path:start-end, with the symbol name when one exists. Where the code gives no answer, write "Not determined from code." and say what you searched. Write a discrepancy warning when the code and the project's written engineering rules disagree.
  3. Use only the three admonitions > **Note:**, > **Warning:**, and > **Tip:**. The build turns them, and their Turkish forms Not, Uyarı, and İpucu, into styled callouts (docs/wiki/_build/build.py:121-125, docs/wiki/_build/build.py:278-299).
  4. Draw diagrams as mermaid fenced blocks and repeat their content in prose. The build keeps these blocks out of the Markdown renderer and hands them to Mermaid in the browser (docs/wiki/_build/build.py:225-246).
  5. Link other pages with relative paths to .md files. The build rewrites them to .html and reports every link whose target page does not exist (docs/wiki/_build/build.py:249-275). Turkish pages link to .tr.md files.
  6. Add new terms to the "Terms introduced" table, then the "Related pages" list, then the footer line with the same commit and date as the front matter.
  7. Write the Turkish twin name.tr.md in the same folder with the same structure: the same headings, tables, rows, admonitions, code blocks, and citations. The build pairs files by stem and offers a language switch (docs/wiki/_build/build.py:197-200, docs/wiki/_build/build.py:555-556).

  8. Build the site from the repository root:

    bash python docs/wiki/_build/build.py

    The output goes to docs/wiki/_site; --out chooses another folder and --site-root adds links back to a product page (docs/wiki/_build/build.py:613-617).

Verify the result

The build prints the number of pages per language and then every link that points at a missing page (docs/wiki/_build/build.py:603-609). It also writes a client-side search index with the title, section, headings, description, and the first 4,000 characters of each page (docs/wiki/_build/build.py:583-590, docs/wiki/_build/build.py:602). The page outline covers H2 and H3 headings (docs/wiki/_build/build.py:329). Open the new page in docs/wiki/_site and check the language switch, the outline, and the diagrams. Then apply the style checklist (docs/wiki/_standard/STYLE_CHECKLIST.md).

Troubleshooting

Symptom Cause in code Fix
The build stops with "front matter does not parse" yaml.safe_load raised an error (docs/wiki/_build/build.py:188-191) Correct the YAML, for example quote a value that contains a colon
"mermaid.min.js not found" warning; diagrams show as text The Mermaid package is missing in _build/node_modules (docs/wiki/_build/build.py:524-528) Run npm install in docs/wiki/_build/
A link is listed under "links point at pages that do not exist yet" The relative target is not a known page (docs/wiki/_build/build.py:267-268) Fix the path; the build still exits with code 0 (docs/wiki/_build/build.py:610)
A section appears at the end of the navigation Its slug is not in SECTIONS (docs/wiki/_build/build.py:56-69) Use an existing section slug

Terms introduced

Term Code identifier Definition Turkish term Source
Turkish twin name.tr.md The Turkish page with the same stem and the same structure as an English page. Türkçe ikiz docs/wiki/_build/build.py:197-200
admonition ADMONITION_WORDS A blockquote that starts with a bold Note, Warning, or Tip label and is shown as a callout. Uyarı kutusu docs/wiki/_build/build.py:121-125

Verified against commit 92f8051 on 2026-11-13.

Verified against commit 92f8051 · 2026-11-13