Structure of this repository

We basically follow the Jekyll and Minimal Mistakes layout our documentation site is based on, with a small set of additions for our custom plugins, tools, and includes.

.
├── _data
│   ├── links/                 # auto-generated, gitignored
│   ├── manpages/              # auto-generated, gitignored
│   ├── navigation.yml         # auto-generated by _tools/navgen
│   ├── excluded_titles.yml
│   ├── external_links.yml
│   └── link_aliases.yml
│
├── _includes
│   ├── doc/                   # reusable doc snippets (options, warnings, notes, examples)
│   ├── footer/
│   ├── head/
│   ├── search/
│   └── … (theme partials)
│
├── _js
│   ├── custom/                # our scripts (auto-bundled by _tools/pack)
│   ├── plugins/               # 3rd-party plugins
│   ├── vendor/                # 3rd-party libraries
│   ├── lunr/                  # Lunr search engine + our lunr-store.js
│   └── _main.js               # pre-pack entry; the packed result is `assets/js/main.min.js`
│
├── _layouts
│
├── _plugins                   # our Jekyll plugins (see Directories below)
│
├── _sass
│   └── minimal-mistakes/
│
├── .github
│   └── workflows/             # CI build pipeline (jekyll-gh-pages.yml)
│
├── _site                      # generated output, gitignored
│
├── _tools                     # our helper tools (see Directories below)
│
├── assets
│   ├── css/
│   ├── images/
│   └── js/                    # built from `_js`, gitignored
│
├── doc
│   ├── _admin-guide/
│   ├── _dev-guide/
│   ├── _doc-guide/
│   └── site-internal/
│
├── _config.yml
├── Gemfile
├── LICENSE.*
└── README.md

Directories

  • _data
    Inputs Jekyll consumes during site generation: navigation, link descriptors, alias and exclusion tables, manpage metadata, etc.
    • links/
      Do not edit. Auto-generated during the first build pass (JEKYLL_BUILD_LINKS=yes) by _plugins/generate_links.rb; gitignored. Contains one YAML descriptor per page used as input for the autolink/tooltip generation in the second build pass.
    • manpages/
      Do not edit. Auto-generated by _tools/mangen; gitignored. Holds intermediate metadata used to build the rendered manpages under _site/manpages/.

  • _includes
    Reusable HTML/Liquid fragments. The bulk are Minimal Mistakes theme partials (masthead, sidebar, TOC, breadcrumbs, archive, …); our additions live under _includes/doc/ (admin-guide and dev-guide reusable snippets, plus the site-wide common_links and common_snippets) and a few standalone helpers (e.g. settings_panel.html).
    No inline <script> or <style> blocks here — behaviour belongs in _js/custom/<feature>.js (auto-bundled by _tools/pack) and styling in _sass/minimal-mistakes/minimal-mistakes/_<area>.scss using SCSS skin variables, so light/dark skins both work. Inline <script> is not picked up by _tools/pack (forces a full Jekyll rebuild on every edit); inline <style> bypasses the SASS skin variables and breaks dark/light parity.

  • _js
    • custom/
      Our own scripts. Every *.js here, plus _js/plugins/ and _js/vendor/, is bundled into assets/js/main.min.js by _tools/pack — a repack alone ships JS changes, no Jekyll build needed when running _tools/serve. Note: _tools/pack uses an explicit, order-sensitive file list — a new _js/custom/<feature>.js must be appended there too, otherwise it will silently NOT be bundled.
    • plugins/
      3rd-party jQuery plugins used by the theme plus clipboard.js (FitVids, Magnific-Popup, greedy-navigation, throttle/debounce, smooth-scroll, gumshoe).
    • vendor/
      3rd-party libraries the bundle depends on — currently just jquery/jquery-3.7.1.js.
    • lunr/
      Lunr is the default search engine. We ship our own fully rewritten lunr-en.js (multi-strategy search with location-based boosting) plus our lunr-store.js (which uses the extract_headings Liquid filter from [[doc-jekyll-extensions]] to add per-heading search entries).

  • _layouts
    The page layouts the site is built on — a curated subset of the Minimal Mistakes layouts: base, compress, default, single. Unused theme layouts were removed.

  • _plugins
    Our Jekyll plugins — see Jekyll extensions for the per-plugin reference. Short index:
    • common_includes.rb — prepends doc/common_snippets to every page (always-active :site, :pre_render).
    • expand_notice_blocks.rb — expands paired {: .notice--TYPE-start/-end} markers (always-active).
    • extract_headings.rb — Liquid filter that returns the heading anchors of an HTML fragment (used by Lunr).
    • generate_links.rb — first-build link descriptor generator (JEKYLL_BUILD_LINKS=yes, :site, :post_render).
    • generate_tooltips.rb — second-build autolink/tooltip injector (JEKYLL_BUILD_TOOLTIPS=yes, two :pre_render hooks).
    • liquify.rb — Liquid filter that forces evaluation of a Liquid expression embedded in data.
    • sass_silence_deprecations.rb — propagates _config.yml’s sass.silence_deprecations list into the sass-embedded runtime.
    • site_data_by_path.rb — Liquid filter (data_by_path) that walks a dotted path through a hash to dereference _data/... entries dynamically.

  • _sass
    The Jekyll SASS converter input. Holds the full Minimal Mistakes SCSS tree under _sass/minimal-mistakes/ and the minimal-mistakes.scss entry. The actual top-level entry points (main.scss and the per-skin main_*.scss variants) live under assets/css/.

  • _site
    Do not edit. Generated static site output; gitignored.

  • _tools
    Our self-made helper tools.

  • .github
  • assets
    • css/
      The site’s stylesheet entry points: main.scss for the default skin plus one main_<skin>.scss per Minimal Mistakes (mm-air, mm-aqua, mm-contrast, mm-dark, mm-dirt, mm-mint, mm-neon, mm-plum, mm-sunrise) and One Identity (oi-light, oi-dark, oi-midnight) skin. Each one imports _sass/minimal-mistakes/.
    • images/
      Image files used by the site. Keep them organized by their owning collection (admin-guide/, dev-guide/, …); the shared notice icons (note.png, info.png, caution.png, warning.png, success.png) and favicons/ live at the top level.
    • js/
      Do not edit. Built from _js/ by _tools/pack; gitignored.
  • doc
    The actual documentation source — the Markdown files of each documentation collection.

Files

  • _config.yml
    Our Jekyll configuration file. The product.version field is overwritten by _tools/update_config_version during CI.
  • Gemfile
    Jekyll and Minimal Mistakes Ruby gem dependencies.
  • LICENSE.*
    License files of the modules the project uses (Lunr, Midnight, Minimal Mistakes).
  • README.md
    The GitHub repository landing-page README.

  • AGENTS.md, .github/copilot-instructions.md
    Repository conventions and build rules consumed by AI coding agents (and useful as a contributor cheat-sheet).

  • _data/navigation.yml
    Input YAML for the left navigation sidebar. Generated by _tools/navgen — do not edit, your changes will be overwritten on every build.
  • _data/excluded_titles.yml
    Title patterns (plain strings or [Cc]haracter classes) that the autolink/tooltip generator must skip — generic words like Example, Note, Options, Default value, etc.
  • _data/external_links.yml
    Central collector for every external (non-site) link referenced in the documentation. Entries are grouped by ID prefix (gh: GitHub, bb: Balabit, oi: One Identity, sn: syslog-ng, mm: Minimal Mistakes, lic: licenses, rfc: RFCs); keep alphabetical order inside each block.

  • _data/link_aliases.yml
    Per link-ID list of alternate phrases (plain or /regex/) that the autolink/tooltip generator should resolve to the same target page or anchor.

  • .github/workflows/jekyll-gh-pages.yml
    The GitHub Actions CI build workflow — runs the pre-build tools, the two Jekyll passes, and the post-build steps (_tools/pack, doxygen, _tools/mangen).

  • _js/_main.js
    The Minimal Mistakes theme’s main jQuery init script (FitVids, Magnific-Popup, smooth-scroll, gumshoe, navigation, etc.). Packed last by _tools/pack — the comment in _tools/pack notes this is required to avoid runtime Lunr errors.
  • _js/custom/*.js
    Our own scripts — currently copy-to-clipboard-btn.js, navigation.js, settings-panel.js, custom-init.js. Bundled in this exact order by _tools/pack (see the explicit list inside the script). When adding a new file, append it there too — the bundler does not auto-discover it.
  • _js/plugins/*.js
    3rd-party jQuery plugins (FitVids, Magnific-Popup, greedy-navigation, throttle/debounce, smooth-scroll, gumshoe, clipboard.js). Bundled by _tools/pack between jQuery and _js/custom/.
  • _js/vendor/jquery/jquery-3.7.1.js
    The jQuery build packed first by _tools/pack (every other script depends on it).
  • _js/lunr/lunr.js, _js/lunr/lunr.min.js
    Upstream Lunr search engine. Copied as-is to assets/js/lunr/ by _tools/pack — not bundled into main.min.js, since per-language and per-heading support is now produced via Liquid at content-generation time.
  • _js/lunr/lunr-en.js
    Our fully rewritten Lunr search front-end. Implements a multi-strategy compound-term search (full compound, all-terms-together, exact component parts, wildcard variations, fuzzy matches) with location-based boosting (title vs. excerpt-start vs. body) on top of the per-heading entries produced by lunr-store.js. The search algorithm is intentionally specific to our documentation layout and bears little resemblance to the upstream Lunr help example.
  • _js/lunr/lunr-store.js
    Liquid template that builds the per-page search documents fed to Lunr; expanded with one entry per heading via the extract_headings Liquid filter from [[doc-jekyll-extensions]].

  • assets/js/main.min.js
    The bundle produced by _tools/pack from _js/vendor/jquery/, _js/plugins/, _js/custom/, and _js/_main.js (in that order). Lunr is not included. Do not edit, your changes will be overwritten.

  • _plugins/*.rb
    Our Jekyll plugins — see the Jekyll extensions page for the per-plugin reference.
  • _tools/*
    Our helper tools — see the Self-made tools page for the per-tool reference (banner.js, linkcheck, mangen, navgen, pack, package.json.in, serve, update_config_version).

Updated: