Orkige Help
Orkige

Help portal

The engine's public site lives at orkige.orkitec.com. It is regenerated and deployed by CI on every push to main (.github/workflows/pages.yml) — nothing on a dev machine serves it, and the editor's Help > Orkige Help simply opens the published documentation in the default browser (a network connection is required; the earlier offline, editor-served portal was retired by design — a distributed editor carries no repository and no python toolchain, so it can never generate the site itself).

The deployed site has four parts:

  • / — the landing page: the engine's story (tagline, platform pitch,

    feature highlights distilled from the repository README) with links into the documentation, the API reference and the repository.

  • /help/ — the documentation portal: the repository README.md (the

    Overview page), every Docs/*.md (this page included), and any projects/*/README.md — searchable, cross-linked, generated by Util/make_help_portal.py (python3 stdlib only, like every Util/ tool).

  • /api/ — the C++ class reference, rendered from the orkige_core/ and

    orkige_engine/ headers by Docs/api/Doxyfile. That tooling is CI-only: the Pages workflow installs it on the runner and assembles the output next to the portal, so dev machines need no extra installs.

  • /imprint and /privacy — the legal pages (Docs/legal/imprint.md,

    Docs/legal/privacy.md), linked from a footer that appears on every page of the site, the API reference included. They stay out of the nav and the search index — footer-only is the convention.

Local preview

python3 Util/make_help_portal.py --output /tmp/orkige-site   # build the site
python3 Util/make_help_portal.py --output <dir> --if-stale   # skip when current
python3 Util/make_help_portal.py --selftest                  # the unit ctest

Everything is relative-linked, so opening <dir>/index.html straight off the disk works. A local preview lacks /api/ — the generator stays stdlib-only and never runs the API tooling; if you want the class reference locally, render it yourself with the same config the workflow uses (doxygen Docs/api/Doxyfile, output under the gitignored Docs/api/build/) and move html/ to <dir>/api.

How docs authors see their pages

The portal PRESENTS the corpus — write normal repository markdown and it renders as written. Because python has no stdlib markdown library, the renderer is a subset tailored to what the corpus actually uses:

  • ATX headings (#–######), paragraphs, horizontal rules.
  • Nested unordered/ordered lists, continuation lines, and fenced code blocks

    indented inside list items.

  • Fenced code blocks with a language tag (rendered as plain preformatted

    code — mermaid blocks included, which appear as their source text).

  • Pipe tables with the \| cell escape and :---: alignment.
  • Inline code, **bold**, *italic*, links and images.
  • HTML comments (the GENERATED block markers) are stripped from the output.

Heading anchors use the familiar slug rules (lower-case, punctuation dropped, every space becomes a dash — ## Show / hide transitions anchors as #show--hide-transitions), so [text](gui.md#section) links written for the repository browser work in the portal unchanged.

Link semantics keep the site self-contained and honest:

  • A link to another corpus page (lua-api.md, ../README.md, optionally

    with #anchor) becomes a site page link — and is verified: a target page or heading anchor that does not exist fails the build, reported as BROKEN LINK <file>:<line> -> <target> so the author can fix the exact spot. Because the Pages workflow runs this generator, the broken-link gate is also the deploy gate; the make_help_portal_selftest ctest keeps the real corpus at zero broken links locally, before a push ever reaches CI.

  • A link to /api/ is the ONE allowlisted target with no corpus page behind

    it — the Pages workflow assembles the class reference there.

  • A link to a repository file outside the corpus (a header, LICENSE)

    renders as inline code — there is no page to link to.

  • External http(s) links stay links; images degrade to their alt text (the

    portal ships no images and never fetches remote ones).

The API reference

Docs/api/Doxyfile renders the full public surface of orkige_core/ and orkige_engine/ (EXTRACT_ALL, so classes appear even where the 2009-era comments are sparse; warnings are logged, never fatal). Docs/api/footer.html puts the site-root link and the imprint/privacy links on every generated page. The check_doxyfile ctest validates the config by rendering the real tree when the tool is installed and skips honestly (exit 77) when it is not.

Delivery

.github/workflows/pages.yml runs on every push to main: generate the site, render /api/, write the CNAME for the custom domain, upload and deploy to GitHub Pages (concurrency-grouped, so a newer push supersedes an in-flight deployment). Repository one-time setup: Settings → Pages → Source "GitHub Actions", custom domain orkige.orkitec.com (DNS: a CNAME record pointing orkige.orkitec.com at orkitec.github.io), then Enforce HTTPS.

Verified by make_help_portal_selftest (unit: synthetic + real corpus, balanced HTML on every page, zero broken links, legal-footer and search conventions, stamp logic), check_doxyfile (unit, skips without the tooling) and editor_help_portal (integration: the Help menu action resolves the published URL and the automated-run browser gate holds — no network in tests).