RDF/XML serialization is deferred.
{
"@context": {
"schema": "https://schema.org/",
"wiki": "https://wazootech.github.io/wiki/",
"foaf": "http://xmlns.com/foaf/0.1/",
"rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
"rdfs": "http://www.w3.org/2000/01/rdf-schema#",
"xsd": "http://www.w3.org/2001/XMLSchema#",
"owl": "http://www.w3.org/2002/07/owl#",
"dc": "http://purl.org/dc/elements/1.1/",
"dcterms": "http://purl.org/dc/terms/",
"sh": "http://www.w3.org/ns/shacl#",
"wazoo": "https://schema.wazoo.dev/"
},
"@id": "wiki:Wiki_Configuration",
"@type": "schema:TechArticle",
"schema:articleBody": "# Wiki Configuration\n\nThe CLI loads **Config** from `wiki.yml`, `wiki.yaml`, or `wiki.json` in the working directory (or from `-c path`).\n\nThe in-memory **Config** model uses the same nested blocks as the file (`wiki`, `graph`, `site`, `link`, `check`, `lint`, `fmt`, `sparql_service`). There is no separate flat runtime shape. `Config.load()` validates the file, injects `config_root` (the directory containing the config file), and resolves relative paths under `wiki` and `site`. Library and test code can construct configs with `Config(wiki={...}, config_root=path)` or `Config.for_root(path, wiki={...})`.\n\nConfig files are validated strictly by the TypeScript schema in [`src/wiki/schemas/wiki_config.ts`](https://github.com/wazootech/wiki/blob/main/src/wiki/schemas/wiki_config.ts), which forbids extra keys on every block. Unknown keys, removed aliases, wrong nested keys under `check`, `lint`, or `sparql_service`, invalid syntax, or a non-mapping top level all fail immediately instead of being ignored. An unknown key is reported by name against the accepted surface; the engine does not guess which key you meant.\n\nJSON configs may use `graph.context` or `graph.@context` for prefix maps (JSON-LD compatible).\n\n## Overview\n\n### Terminology\n\n| Label | Meaning |\n| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Schema optional** | Key or block may be omitted; the schema applies a default. No yaml key is strictly required for `Config.load()` to succeed. |\n| **Init** | Written by `wiki init` ([`wiki.yml`](https://github.com/wazootech/wiki/blob/main/src/wiki/templates/wiki.yml)); omitting an Init key is the same as the schema default. |\n| **Recommended** | Not enforced by schema, but you typically set it for a real wiki (for example `graph.context.wiki`, `wiki.filename_pattern`, `site.layout`). |\n| **Always on** | Behavior not gated by yaml severities (route safety, URL collisions, built-in RDF prefixes). |\n\n### Audit lanes\n\nThree audit lanes map to three commands:\n\n| Lane | Command | YAML block | Purpose |\n| ---------- | ------------ | ---------- | ------------------------------------------------------------------------------------------------------ |\n| Integrity | `wiki check` | `check:` | SHACL, JSON Schema frontmatter, layout file existence |\n| Convention | `wiki lint` | `lint:` | Links, filename pattern severity, headings, link style in prose |\n| Formatting | `wiki fmt` | `fmt:` | Mechanical Markdown via the Deno formatter's native `textWrap`, `lineWidth`, and `newLineKind` options |\n\n**Rule placement:** Mechanical markdown belongs under **`fmt:`**. Wiki policy and link conventions belong under **`lint:`**. SHACL, JSON Schema, and layout keys belong under **`check:`** — never under `lint:`. See [Style Guide](Style_Guide.md) for the full matrix.\n\n- Putting a regex under `check.filename_pattern` fails at load with a hint.\n- `check.filename_pattern` and `check.headings` fail at load — use `lint.filename_pattern` and `lint.headings`.\n\nRelative **`--input`** paths on the CLI resolve against the config file directory (same as paths in yaml), not the shell cwd.\n\n### Blocks\n\nTop-level blocks follow a **compile pipeline** plus **audit lanes**, not arbitrary grouping. `wiki init` and [docs/wiki.yml](https://github.com/wazootech/wiki/blob/main/docs/wiki.yml) use the same order as the packaged scaffold [`wiki.yml`](https://github.com/wazootech/wiki/blob/main/src/wiki/templates/wiki.yml).\n\n| Block | Role | Command(s) | Schema | Init scaffold |\n| ----------------- | ----------------------------------------------------- | --------------------------------- | -------- | ----------------- |\n| `wiki:` | Corpus on disk — inputs, assets, filename regex | `check`, `lint`, `build`, `serve` | optional | yes |\n| `graph:` | RDF compile — prefixes, document IRIs, body literals | `check`, `query`, `render` | optional | yes |\n| `site:` | Publish routing — layout path, URL prefix, path style | `build`, `serve` | optional | yes |\n| `link:` | `wiki link` apply format and rename repair map | `wiki link` | optional | yes |\n| `check:` | Integrity severities | `wiki check` | optional | yes |\n| `lint:` | Convention severities | `wiki lint` | optional | yes |\n| `sources:` | External data sources (git repos) | `wiki install`, `wiki remove` | optional | commented example |\n| `sparql_service:` | Opt-in SPARQL HTTP on `wiki serve` | `wiki serve` | optional | commented example |\n| `fmt:` | Mechanical Markdown via the Deno formatter | `wiki fmt` | optional | inline mapping |\n\n**Order in the file:** source and semantics first (`wiki`, `graph`), then publish and authoring (`site`, `link`), then severity tables (`check`, `lint`), optional serve (`sparql_service`), then `fmt` last.\n\n**Split keys** — policy lives in one block, severity or tooling in another:\n\n- **`wiki.filename_pattern`** — the regex string. **`lint.filename_pattern`** — how strictly to flag violations (`error`, `warning`, or `off`).\n- **`link.style`** — what `wiki link --apply` inserts (`standard` page links or `wikilink`). **`lint.link_style`** — whether Obsidian `[[wikilinks]]` in body prose are flagged when `link.style` is `standard`. `style` also still accepts the retired spellings `markdown` and `obsidian`, with a deprecation warning (see `link:` settings below).\n\nFor why `check`, `lint`, `fmt`, and `wiki link` are separate commands, see [Design philosophies](Design_Philosophies.md#check-lint-fmt-and-link).\n\n### Always on\n\nThese apply regardless of yaml severities:\n\n- **Route safety** — unsafe URL characters and spaces in routes (`wiki check`).\n- **Output URL collisions** — duplicate built routes (`wiki check`).\n- **SHACL** — when shape documents exist in the corpus (`wiki check`).\n- **Built-in RDF prefixes** — `schema`, `wiki`, `foaf`, `rdf`, `rdfs`, `xsd`, `owl`, `dc`, `dcterms`, `sh`, `wazoo` are always merged at runtime; yaml `graph.context` entries override or add.\n\n## Wiki (`wiki:`)\n\n```yaml\nwiki: # optional block\n input: [wiki] # default [wiki]; init writes\n assets: [assets] # default [assets] if assets/ exists, else []; init omits\n exclude: [] # default []; init omits\n filename_pattern: \"[A-Za-z0-9_()-]+\\\\.md\" # no default; recommended; init writes\n allow_unknown_keys: false # default false; init omits\n```\n\n| Key | Required | Default | Init | Audited by |\n| -------------------- | ---------------------- | ------------------------------------------- | ------ | ------------------------------------------ |\n| `input` | optional | `[wiki]` | writes | indexing (`build`, `check`, `lint`, `fmt`) |\n| `assets` | optional | `[assets]` when `assets/` exists, else `[]` | omits | `wiki build` (static copy) |\n| `exclude` | optional | `[]` | omits | indexing (skipped paths) |\n| `filename_pattern` | optional (recommended) | unset — no regex check until set | writes | `wiki lint` (`lint.filename_pattern`) |\n| `allow_unknown_keys` | optional | `false` | omits | config load |\n\nPage URLs come from paths under `wiki.input`: `wiki/Alice.md` → `/wiki/Alice/` with default `site.base_url` and `site.url_style: dir`. `index.md` in a folder owns that folder’s route (for example `wiki/index.md` → `/wiki/`).\n\nSee [Filename conventions](#filename-conventions) for regex patterns.\n\nUnknown top-level keys fail at load, so a typo such as `lnit:` is caught. Set `wiki.allow_unknown_keys: true` to accept them instead. Unknown keys inside a wiki block (`site:`, `lint:`, ...) are still rejected.\n\n## Graph (`graph:`)\n\nRDF and document URI settings for graph build, `wiki query`, microdata, and SHACL.\n\n```yaml\ngraph: # optional block\n # base_iri: unset → graph.context.wiki → https://wiki.example.org/\n content_predicate: schema:articleBody # unset by default; init writes when flagged\n include_file_extension: false # default false; init omits (commented)\n implicit_types: [] # default []; init omits (commented)\n implicit_types_policy: fallback # default fallback; init omits (commented)\n context: # merges with built-in prefixes; init writes\n schema: https://schema.org/\n wiki: https://example.org/wiki/ # recommended\n wazoo: https://schema.wazoo.dev/\n foaf: http://xmlns.com/foaf/0.1/\n dc: http://purl.org/dc/elements/1.1/\n dcterms: http://purl.org/dc/terms/\n sh: http://www.w3.org/ns/shacl#\n xsd: http://www.w3.org/2001/XMLSchema#\n```\n\n| Key | Required | Default | Init | Audited by |\n| ------------------------ | ------------------------------ | ---------------------------------------------------------- | --------------------------------------- | ------------------------------------------------- |\n| `base_iri` | optional | unset → `graph.context.wiki` → `https://wiki.example.org/` | commented example | document IRIs, `wiki query` |\n| `context` / `@context` | optional (recommended: `wiki`) | built-in prefixes only when unset | writes extended map | CURIE expansion, SHACL, microdata |\n| `content_predicate` | optional | unset — no body literals in graph | writes when `--graph-content-predicate` | SPARQL full-text |\n| `include_file_extension` | optional | `false` | omits (commented) | document URI generation |\n| `implicit_types` | optional | `[]` | omits (commented) | default `rdf:type` on untyped pages |\n| `implicit_types_policy` | optional | `fallback` | omits (commented) | `fallback` or `append` (SHACL shapes skip append) |\n\nWhen `implicit_types_policy` is `append`, frontmatter types are unioned with `implicit_types` (deduped by resolved URI).\n\n## Site (`site:`)\n\nDefault page layout and routing for `wiki build` / `wiki serve`. Branding and chrome → [Page layout](#page-layout).\n\n```yaml\nsite: # optional block\n layout: index.html # unset → built-in minimal fallback layout\n base_url: /wiki # default /wiki; init writes\n url_style: dir # default dir; init writes\n```\n\n| Key | Required | Default | Init | Audited by |\n| ----------- | ---------------------- | ------------------------------------- | ------ | ----------------------------------------------------------------------------------- |\n| `layout` | optional (recommended) | unset — packaged minimal `index.html` | writes | `wiki build`, `wiki serve`; `check.missing_layout_file` for per-page `wazoo:layout` |\n| `base_url` | optional | `/wiki` (`\"\"` allowed for site root) | writes | routes, layout `%wiki.base_url%` |\n| `url_style` | optional | `dir` (`file` → `slug.html`) | writes | output paths; overridable per CLI run |\n\n`site:` does not carry site name, theme color, favicon, or sidebar logo. If you want custom styling, write a custom layout template file and place custom assets under the `wiki.assets` directory, then configure `site.layout` to point to it.\n\nCLI flags on `wiki build` and `wiki serve` can override `site.base_url` and `site.url_style` for a single run.\n\n## Link (`link:`)\n\nSettings for the `wiki link` command family (separate from `lint.link_style` severity).\n\n```yaml\nlink: # optional block\n style: standard # default standard; init writes\n renames: {} # default {}; init omits (commented example)\n```\n\n| Key | Required | Default | Init | Audited by |\n| --------- | -------- | ------------------------------------- | ----------------- | ------------------------ |\n| `style` | optional | `standard` (`wikilink` for wikilinks) | writes | `wiki link --apply` only |\n| `renames` | optional | `{}` | commented example | `wiki link --fix-broken` |\n\n`wiki link --fix-broken` preserves the existing link kind in each file; only `--apply` uses `link.style`.\n\n**Retired spellings.** `markdown` and `obsidian` are still accepted as values for `style`, and `wiki init --link-style` accepts them too. Each prints a deprecation warning and rewrites the value to `standard` or `wikilink`:\n\n```text\nlink.style: 'obsidian' is deprecated, use 'wikilink' instead (edit config file link.style and re-run)\n```\n\nThey are accepted but never advertised: an invalid `--link-style` value lists only `standard` and `wikilink`. Rename the value in your config file to silence the warning.\n\n## Integrity checks (`check:`)\n\nUnder `check`, each rule is `error`, `warning`, or `off`:\n\n```yaml\ncheck: # optional block\n missing_layout_file: error # default error; init writes\n frontmatter_schema: error # default error; init writes\n missing_schema_ref: error # default error; init writes\n shape_definition: error # default error\n shape_unused: warning # default warning\n```\n\n| Key | Required | Default | Init | Audited by |\n| --------------------- | -------- | --------- | ------ | ------------------------------------ |\n| `missing_layout_file` | optional | `error` | writes | `wazoo:layout` paths missing on disk |\n| `frontmatter_schema` | optional | `error` | writes | JSON Schema validation failures |\n| `missing_schema_ref` | optional | `error` | writes | unloadable `wazoo:jsonSchema` refs |\n| `shape_definition` | optional | `error` | — | ill-formed SHACL shape pages |\n| `shape_unused` | optional | `warning` | — | node shapes that validate nothing |\n\nBuild-safety rules (unsafe URL characters, spaces in routes) and output URL collision detection always apply regardless of `check` settings.\n\n### JSON Schema frontmatter (`wazoo:jsonSchema`)\n\n`wiki check` validates frontmatter against JSON Schema in parallel with SHACL. Bind schemas on shape documents with **`wazoo:jsonSchema`** beside **`sh:targetClass`**; every page whose effective `type` matches that class must pass the bound schema(s). Individual pages may append extra schemas with their own `wazoo:jsonSchema` key (scalar or YAML list). Schema refs are local paths under the wiki config root (`.json` only) or remote `http(s)` URLs.\n\nShape binding documents are not validated as instances — only their schema refs are checked for loadability. Authoring detail: [SHACL](SHACL.md), [Style Guide](Style_Guide.md).\n\n## Convention audits (`lint:`)\n\nUnder `lint`, each rule is `error`, `warning`, or `off`:\n\n```yaml\nlint: # optional block\n broken_links: warning # default warning; init writes\n filename_pattern: warning # default warning; init writes\n headings: off # default off; init omits\n heading_levels: off # default off; init omits\n duplicate_headings: off # default off; init omits\n thematic_breaks: off # default off; init omits\n link_style: warning # default warning; init writes\n redundant_frontmatter: off # default off; init omits\n```\n\n| Key | Required | Default | Init | Audited by |\n| ----------------------- | -------- | --------- | ------ | --------------------------------------------------------------------------------- |\n| `broken_links` | optional | `warning` | writes | wikilinks, markdown links, fragments, assets, `wiki:` CURIEs |\n| `filename_pattern` | optional | `warning` | writes | full filename vs `wiki.filename_pattern` |\n| `headings` | optional | `off` | omits | ATX syntax, sentence-case H2+, numbered headings |\n| `heading_levels` | optional | `off` | omits | heading level gaps (for example H1 then H3) |\n| `duplicate_headings` | optional | `off` | omits | duplicate heading text on one page |\n| `thematic_breaks` | optional | `off` | omits | horizontal rules in body prose |\n| `link_style` | optional | `warning` | writes | Obsidian `[[wikilinks]]` when `link.style` is `standard` |\n| `redundant_frontmatter` | optional | `off` | omits | frontmatter that repeats a derived headline or Git date ([wiki fix](wiki_fix.md)) |\n\nATX heading syntax is also enforced by **`wiki fmt`**, the Deno Markdown formatter; Setext underlines are converted on format.\n\nWhen `link.style` is `standard`, set `lint.link_style: off` to allow wikilinks in prose, or set `link.style: wikilink` for an Obsidian-style wiki.\n\n## External data sources (`sources:`)\n\n<!-- wiki:anchor external-data-sources-sources -->\n\nDeclare external git repositories that contribute wiki pages or RDF data to the graph. After adding a source, run `wiki install` to clone it and pin the resolved commit in `wiki.lock`.\n\nSources are read-only inputs during graph construction. Wiki composes root content and installed sources into one default query view, while preserving each installed source as a stable RDF named graph for provenance and SPARQL `GRAPH` clauses.\n\n```yaml\nsources: # optional block\n - name: solar-system\n type: git\n url: https://github.com/EthanThatOneKid/solar-system-wiki.git\n ref: v0.1.0 # optional — branch, tag, or commit\n path: wiki # optional — subdirectory within the repo\n```\n\n| Key | Required | Default | Init | Command(s) |\n| ------ | -------- | --------- | ----------------- | -------------- |\n| `name` | required | — | omits (commented) | `wiki install` |\n| `type` | required | `git` | omits (commented) | `wiki install` |\n| `url` | required | — | omits (commented) | `wiki install` |\n| `ref` | optional | `HEAD` | omits (commented) | `wiki install` |\n| `path` | optional | repo root | omits (commented) | `wiki install` |\n\nEach source must have a unique `name`. The `type` field is currently limited to `git`. Unknown keys and unsupported types are rejected at config load time.\n\nRun `wiki install` to fetch all declared sources and write `wiki.lock`. Check `wiki.lock` into version control for reproducible builds. The resolved source paths are automatically appended to `wiki.input` so the existing graph, check, and build pipeline picks them up.\n\nUse `wiki graph list` to inspect the root graph and installed source graph URIs. Source graph URIs are derived from `graph.context.wiki`:\n\n- Root corpus: `{graph.context.wiki}graphs/root`\n- Installed source: `{graph.context.wiki}graphs/source/{source-name}`\n\nRequested refs, resolved commits, source URLs, cache paths, and direct/transitive dependency metadata remain source metadata; they are not embedded in graph URIs.\n\n**Transitive dependencies** are resolved recursively. After cloning each source, `wiki install` reads the source's own `wiki.yml` (or `wiki.yaml`/`wiki.json`) to discover its `sources:` block. Those transitive sources are fetched and locked too, forming a dependency tree. Circular dependency chains are detected and reported as errors. If two sources declare the same dependency name with different URLs or refs, install fails with a conflict error.\n\nWhen a source is removed with `wiki remove`, transitive sources that are no longer needed by any remaining top-level source are automatically cleaned up (cache and lockfile entry removed).\n\nAfter `wiki update`, newly declared transitive sources are installed, and orphaned sources are reported (but not auto-removed — run `wiki remove` to clean up).\n\nThe `.wiki/` source cache directory is not committed — `wiki init` scaffolds a `.gitignore` that excludes it (alongside the `_site/` build output).\n\nTo add a source without editing the config file by hand:\n\n```bash\nwiki install https://github.com/EthanThatOneKid/solar-system-wiki.git\n# GitHub shorthand also works:\nwiki install EthanThatOneKid/solar-system-wiki\n```\n\nThe name is inferred from the URL (`solar-system`). To remove it:\n\n```bash\nwiki remove solar-system\n```\n\nSee [wiki install](wiki_install.md) and [wiki remove](wiki_remove.md).\n\n### Contributing changes to a source\n\nAn installed source is a read-only input. To change one, change its upstream repository and pull the result back in; never edit the installed copy.\n\n- **Local resolution** (`wiki install`) is a cache: a shallow clone under `.wiki/sources/<name>/repo/`, pinned by `wiki.lock`. It is not committed and is not a place to author.\n- **Vendoring** (copying the pages into your own repository) makes them yours: they are then ordinary root pages and no longer track upstream. Wiki has no vendoring command or config yet ([#150](https://github.com/wazootech/wiki/issues/150)); copy the files and remove the source with `wiki remove`.\n- **Upstream contribution** keeps the source a dependency and sends the change to its owner:\n\n1. Clone the source's repository normally, outside `.wiki/`, and branch (fork it first when you cannot push). It is a wiki in its own right, so use its `wiki file` verbs and its own checks there.\n2. Open a pull request upstream.\n3. Until it merges, point your wiki at the branch: set the source's `url` to your fork (if you forked) and `ref` to the branch, then run `wiki update <name>`. This moves the `wiki.lock` entry to the branch's head.\n4. After it merges, set `url` and `ref` back and run `wiki update <name>` again. Commit `wiki.yml` and `wiki.lock`.\n\nTo follow upstream without contributing, run `wiki update` (or `wiki update <name>`); `wiki update --dry-run` shows what would move.\n\nDo not edit files in `.wiki/sources/`. The edit verbs (`wiki file set`, `patch`, `mv`, `rm`, and `wiki edit`) refuse any path under `.wiki/`. A hand edit there survives `wiki install`, stays uncommitted, and is not in `wiki.lock`, so nobody else sees it. It also breaks `wiki update`: when upstream changes the same file, the update fails with git's \"local changes would be overwritten\" error until you discard the edit (`git -C .wiki/sources/<name>/repo checkout -- .`).\n\nSPARQL Update and in-place writes to sources are not supported; see [Recursive Semantic Datasets](Recursive_Semantic_Datasets.md).\n\nFor the product framing behind recursive source composition, see [Recursive Semantic Datasets](Recursive_Semantic_Datasets.md). For what happens when a source describes the same entity as your root wiki, see [Cross-Wiki Identity](Cross_Wiki_Identity.md).\n\n## Serve API\n\nOpt-in read-only SPARQL HTTP endpoint on `wiki serve`:\n\n```yaml\nsparql_service: # optional block\n enabled: false # default false; init omits (commented)\n path: /api/sparql # default /api/sparql; init omits (commented)\n```\n\n| Key | Required | Default | Init | Audited by |\n| --------- | -------- | ------------- | ----------------- | ---------------------------- |\n| `enabled` | optional | `false` | commented example | `wiki serve` SPARQL endpoint |\n| `path` | optional | `/api/sparql` | commented example | reserved route on serve |\n\n`sparql_service.enabled` accepts YAML booleans and normalizes common string forms such as `true`, `false`, `on`, `off`, `yes`, `no`, `1`, and `0`; prefer native YAML booleans.\n\nExample when enabled:\n\n```yaml\nsparql_service:\n enabled: true\n path: /api/sparql\n```\n\nThe endpoint reuses the same SPARQL engine as `wiki query`. It is read-only and intended for local or development-oriented use. HTTP request forms, supported query types, and `Accept` negotiation are documented in [wiki serve](wiki_serve.md#sparql-endpoint).\n\nIt is **opt-in by default** because enabling it exposes raw graph-query access in addition to HTML preview.\n\n`sparql_service.path` must not collide with the effective `site.base_url` page routes or the watch endpoint. Invalid values such as `/`, `/wiki`, `/wiki/foo`, or `/wiki/__watch` are rejected when `wiki serve` starts.\n\n## Formatting (`fmt`)\n\nTop-level **`fmt`** configures Wiki's in-process `dprint-plugin-markdown` formatter. The inline mapping uses native Deno/dprint option names:\n\n```yaml\nfmt:\n textWrap: never\n lineWidth: 80\n newLineKind: lf\n```\n\n| Option | Values | Default | Effect |\n| ------------- | ----------------------------- | ------- | ------------------------------------------------------------------------ |\n| `textWrap` | `always`, `maintain`, `never` | `never` | Whether prose wraps to the configured width or preserves/avoids wrapping |\n| `lineWidth` | Positive integer | `80` | Target width when `textWrap` is `always` |\n| `newLineKind` | `auto`, `crlf`, `lf` | `lf` | Line ending emitted by the formatter |\n\nOnly an inline mapping is supported. TOML pointers, `.mdformat.toml` discovery, and mdformat-only keys such as `wrap`, `end_of_line`, and `extensions` are not supported. Existing values must be removed or rewritten using the native options above. Omitting `fmt` or using `fmt: {}` selects the Wiki CLI defaults. See [wiki fmt](wiki_fmt.md) for details.\n\n## Page layout\n\nWhen `site.layout` is set, the CLI renders every page through that page layout (`.html`). Per-page overrides use `wazoo:layout` in frontmatter; see [Wiki Page Layouts](Wiki_Page_Layouts.md).\n\n### Layout strategy\n\nThe first-class presentation contract in this repository is layout files referenced from `site.layout` (for example `index.html`).\n\n- The [wiki](wiki.md) owns the semantic markdown-to-HTML pipeline and layout slot contract.\n- Wiki page layout files are the primary built-in extension point for presentation.\n- Advanced themes or framework-specific sites such as Next.js, Mintlify, or other external docs stacks are treated as downstream integrations or separate layout/template repositories.\n\n### Minimal fallback\n\nWithout a configured layout file (or when the path is missing), every page is rendered with the built-in minimal fallback layout (`index.html`), which outputs plain, unstyled HTML containing only `<h1>` and content. It does not link any default CSS or assets and does not include a sidebar, tabs, infobox, table of contents, backlinks, or categories out-of-the-box.\n\n### Layout slots\n\nLayout files use `%wiki.*%` slot substitution (not Jinja). On each page render, the CLI builds a slot map from the current page context and replaces every known slot in your layout file. Unknown `%wiki.*%` spellings are left unchanged.\n\nLayout settings and the supported slots are documented in [Wiki Page Layouts](Wiki_Page_Layouts.md).\n\nCanonical slot list (3 slots):\n\n| Slot | Source | Substitution |\n| ----------------- | ---------------------- | ------------------------------------------------------------- |\n| `%wiki.base_url%` | `site.base_url` | HTML-escaped text (`/wiki`, or `\"\"` for site root) |\n| `%wiki.head%` | built per page | `<title>{page title} - Wiki CLI</title>` (title HTML-escaped) |\n| `%wiki.body%` | rendered markdown body | Pre-built HTML (not escaped) |\n\n**Packaged layouts**\n\n| File | When used | Typical slots |\n| ------------ | ----------------------------------- | ---------------------------- |\n| `index.html` | `site.layout` unset or missing file | `%wiki.head%`, `%wiki.body%` |\n\nExample excerpt (`index.html`):\n\n```html\n<!DOCTYPE html>\n<html lang=en>\n <head>\n<meta charset=UTF-8>\n<meta name=viewport content=width=device-width,initial-scale=1.0>\n%wiki.head%\n </head>\n <body>\n%wiki.body%\n </body>\n</html>\n```\n\n### Custom CSS\n\nThe Wiki CLI does not copy or link a default stylesheet out-of-the-box. To add styling to your pages:\n\n1. **Edit the layout file** — set `site.layout` in `wiki.yml` to a custom layout file. Link stylesheets in `<head>`, or write inline styles.\n1. **Link wiki assets** — place `.css` files under a directory listed in `wiki.assets`, then reference them from the layout, for example `<link rel=\"stylesheet\" href=\"%wiki.base_url%/assets/site.css\">`. Built assets are served at `%wiki.base_url%/assets/…` during `wiki serve` and copied into the build output.\n\n### Custom logos and icons\n\nTo customize site logos, icons, favicons, or touch icons:\n\n1. Place your asset files (such as `logo.svg`, `logo.png`, `favicon.ico`) under a directory listed in `wiki.assets`.\n1. Reference the assets from your custom layout file, for example:\n\n```html\n<img src=\"%wiki.base_url%/assets/logo.svg\" alt=\"\" width=\"80\" height=\"80\">\n```\n\nYou can also add `<link rel=\"icon\">`, `<link rel=\"apple-touch-icon\">`, or other `<head>` tags directly in your custom layout file.\n\nBuilt assets are served at `%wiki.base_url%/assets/…` during `wiki serve` and copied into the build output.\n\nSee also [Wiki Page Layouts](Wiki_Page_Layouts.md) for `site.layout`, `wazoo:layout`, and packaged layout files.\n\nThe metadata pane uses the same RDF serialization path as `wiki export` (compacted JSON-LD, Turtle, N3, N-Triples, TriG, and N-Quads). A compact **Format** chip row switches views without JavaScript. In `wiki serve`, set the initial chip with `?metadata_format=FORMAT` (for example `turtle` or `json-ld`). In `wiki build`, all supported format views are embedded in the page HTML so the picker works offline. RDF/XML output is deferred and is not offered.\n\n### Built-in CSS classes and IDs\n\nThe wiki builder generates these selectors in the rendered page content:\n\n| Selector | Where |\n| --------------------------- | ------------------------------------------------------------------------------------------------- |\n| `#article-top` | Read-view `<article>` wrapper around rendered markdown body. |\n| `#firstHeading` | Read-view page title `<h1>`; also Talk / Source / Metadata pane headings. TOC “(Top)” links here. |\n| `#siteSub` | Subtitle under Talk / Source / Metadata pane headings. |\n| `article` | Wrapper around the rendered markdown body (`#article-top`). |\n| `.layout-label` | Uppercase type or custom-layout badge in read view. |\n| `.toc` / `#toc` | Table of contents container. |\n| `#catlinks` / `.catlinks` | Category links box. |\n| `.backlinks` / `#backlinks` | Backlinks section. |\n| `.catlinks-label` | Categories heading label. |\n| `.catlinks-list` | Categories `<ul>`. |\n| `.infobox` | Typed frontmatter property table. |\n| `.page-meta` | Infobox class (used for styling). |\n| `.template-SLUG` | Per-template class on infobox (e.g. `template-person`). |\n| `toclevel-N` / `lN` | TOC list item classes for heading level N. |\n| `.wikilink` | Internal wiki page links. |\n| `pre[data-copy]` | Block code with raw source for clipboard copy. |\n| `.code-block` | Wrapper injected around copyable pre blocks. |\n| `.code-copy-btn` | Copy button shown on code-block hover/focus. |\n\n### JavaScript hooks\n\nCustom layout files can utilize standard JavaScript hooks or customize their own. In premium layouts (such as template repositories), the following JavaScript features can be implemented:\n\n| Function | Purpose |\n| ------------------------------ | ---------------------------------------------------- |\n| `switchTab(viewName)` | Switch between read / talk / source / metadata tabs. |\n| `loadTalkNotes()` | Load per-page local-storage notes. |\n| `saveTalkNotes()` | Save per-page notes to localStorage. |\n| `clearTalkNotes()` | Clear per-page notes. |\n| `copySourceCode()` | Copy markdown source to clipboard. |\n| `copyPreContent()` | Copy a `pre[data-copy]` block to clipboard. |\n| `initCodeCopyButtons()` | Wrap copyable pre blocks and inject copy buttons. |\n| `toggleToc()` | Show/hide table of contents. |\n| `goToRandomArticle()` | Navigate to a random page. |\n| `triggerSearch()` | Execute search and navigate to first match. |\n| `onSearchInput(e)` | Live search suggestions. |\n| `handleSearchKey(e)` | Keyboard navigation for search suggestions. |\n| `navigateSearch(slug)` | Navigate to a search result. |\n| `applyCategoryFilterFromUrl()` | Filter index page by `?category=` URL parameter. |\n\nIf the configured page layout file does not exist, the packaged minimal `index.html` layout is used silently — no error.\n\n## Filename conventions\n\nThe CLI does not hard-code kebab-case. Projects choose a convention with **`wiki.filename_pattern`**, matched against the **full filename** (including `.md`) on markdown files only.\n\n**Wikipedia-style (recommended):** preserved capitalization and underscores — `Gregory_Davidson.md`, `Pokemon_Diamond_(copy_1).md`, `LLM_Wiki_CLI.md`. Use a pattern such as:\n\n```yaml\nwiki:\n filename_pattern: \"[A-Za-z0-9_()-]+\\\\.md\"\n```\n\n**Kebab-case (optional):** if you prefer `gregory-house.md`, set an explicit pattern (for example `[a-z0-9-]+\\\\.md`) and enforce it via `lint.filename_pattern`. Wikipedia-style and kebab-case should not be mixed in one wiki.\n\nPage routes keep the casing from the filename; GitHub Pages URLs are case-sensitive.\n\n`wiki link --fix-broken` preserves the existing link kind in each file; only `--apply` uses `link.style`.\n\nWhen `link.style` is `standard`, `lint.link_style` (default `warning`) flags Obsidian wikilinks (`[[Page]]`) in body prose. Set `lint.link_style: off` to allow wikilinks while keeping standard links as the apply format, or set `link.style: wikilink` for an Obsidian-style wiki.\n\n## Formatting (`fmt`)\n\n`wiki fmt` uses native Deno/dprint options under an inline `fmt:` mapping. The accepted options, defaults, and removed mdformat/TOML behavior are documented in [wiki fmt](wiki_fmt.md).\n\n## Integrity checks (`check`)\n\nUnder `check`, each rule is `error`, `warning`, or `off`:\n\n| Rule key | Default | What it audits |\n| --------------------- | --------- | ------------------------------------------------------------------------------------------ |\n| `missing_layout_file` | `error` | `wazoo:layout` paths that do not resolve to a readable `.html` file |\n| `frontmatter_schema` | `error` | Frontmatter that fails JSON Schema validation |\n| `missing_schema_ref` | `error` | `wazoo:jsonSchema` paths or URLs that cannot be loaded |\n| `shape_definition` | `error` | Ill-formed SHACL shape pages (see [wiki check](wiki_check.md#shape-definitions)) |\n| `shape_unused` | `warning` | Node shape pages that validate nothing (see [wiki check](wiki_check.md#shape-definitions)) |\n| `remote_schema_refs` | `allow` | Policy for remote `http(s)` schema refs: `allow`, `deny`, or `allowlist` |\n| `remote_schema_hosts` | `[]` | Hostnames permitted when `remote_schema_refs` is `allowlist` |\n\nBuild-safety rules (unsafe URL characters, spaces in routes) and output URL collision detection always apply regardless of `check` settings.\n\n### JSON Schema frontmatter (`wazoo:jsonSchema`)\n\n`wiki check` validates frontmatter against JSON Schema in parallel with SHACL. Bind schemas on shape documents with **`wazoo:jsonSchema`** beside **`sh:targetClass`**; every page whose effective `type` matches that class must pass the bound schema(s). Individual pages may append extra schemas with their own `wazoo:jsonSchema` key (scalar or YAML list). Schema refs are local paths under the wiki config root (`.json` only) or remote `http(s)` URLs. Remote refs can trigger outbound network requests; set `check.remote_schema_refs: deny` in CI over untrusted wikis, or `allowlist` with `check.remote_schema_hosts` for trusted hosts only.\n\nShape binding documents are not validated as instances — only their schema refs are checked for loadability. Authoring detail: [SHACL](SHACL.md), [Style Guide](Style_Guide.md).\n\n## Convention audits (`lint`)\n\nUnder `lint`, each rule is `error`, `warning`, or `off`:\n\n| Rule key | Default | What it audits |\n| ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `broken_links` | `warning` | Wikilinks, internal markdown links, heading fragments, assets, `wiki:` CURIEs |\n| `filename_pattern` | `warning` | Full filename vs `wiki.filename_pattern` regex |\n| `headings` | `off` | ATX `#` headings only (no Setext underlines), sentence-case H2+, H1 title case conventional, numbered headings |\n| `thematic_breaks` | `off` | Horizontal rules (`---`, `***`, `___`) in body prose |\n| `link_style` | `warning` | Obsidian wikilinks (`[[Page]]`) in body prose when `link.style` is `standard` |\n| `redundant_frontmatter` | `off` | A `headline`, `dateCreated`, or `dateModified` that repeats the value the graph derives from the H1 or Git history; remove with [wiki fix](wiki_fix.md) |\n\n`redundant_frontmatter` is `off` by default because many wikis follow the convention of repeating the H1 as `headline`: as a default warning it would fail every such page under `lint --strict`. Turn it on once the redundant keys are removed with `wiki fix --apply`, as this wiki does in `docs/wiki.yml`.\n\n### What `broken_links` accepts\n\n`broken_links` reports a link only when its target is missing. It accepts everything CommonMark allows:\n\n- **Titled and angle-bracket destinations** — `[a](Page.md \"Title\")` and `[a](<Page.md>)` resolve like `[a](Page.md)`; `wiki file mv` keeps the title when it rewrites them.\n- **URLs with a scheme** — `https://`, `ftp://`, `obsidian://`, and `//host` are external and never checked.\n- **Site-root-relative links** — `[a](/wiki/Guides/Setup/)` is resolved against `site.base_url` and `site.url_style` and checked against the page that route maps to. A missing route or heading is still reported; a link outside `site.base_url`, or to a non-page file, is checked as before.\n- **`#top`** — scrolls to the top of the page and needs no matching heading.\n- **Fenced and commented-out links** — links inside backtick or `~~~` fences and HTML comments are skipped.\n\n## This repository\n\n`docs/wiki.yml` is the dogfood wiki config for this repository. It follows the same block order as the packaged scaffold, but with project-specific overrides — `graph.context.wiki` for GitHub Pages and `graph.content_predicate: schema:articleBody` for SPARQL full-text.\n\n## Related\n\n- [wiki](wiki.md#global-options) — `-c` and `--input` global options\n- [wiki init](wiki_init.md) — scaffold a new wiki project\n- [wiki check](wiki_check.md) — integrity checks\n- [wiki lint](wiki_lint.md) — convention audits\n- [wiki query](wiki_query.md) — ad-hoc SPARQL\n- [wiki render](wiki_render.md) — inline SPARQL tables\n- [wiki serve](wiki_serve.md#sparql-endpoint) — `#serve-api` config block\n- [Graph Cache](Graph_Cache.md) — `--cache` and graph reuse\n- [Style Guide](Style_Guide.md) — shapes and frontmatter",
"schema:dateCreated": {
"@type": "xsd:dateTime",
"@value": "2026-10-31T23:19:03Z"
},
"schema:dateModified": {
"@type": "xsd:dateTime",
"@value": "2026-10-31T23:19:03Z"
},
"schema:description": "Reference for wiki.yaml, wiki.yml, and wiki.json (Config).",
"schema:headline": "Wiki Configuration"
}
@prefix schema: <https://schema.org/>.
@prefix wiki: <https://wazootech.github.io/wiki/>.
@prefix foaf: <http://xmlns.com/foaf/0.1/>.
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
@prefix owl: <http://www.w3.org/2002/07/owl#>.
@prefix dc: <http://purl.org/dc/elements/1.1/>.
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix sh: <http://www.w3.org/ns/shacl#>.
@prefix wazoo: <https://schema.wazoo.dev/>.
wiki:Wiki_Configuration a schema:TechArticle;
schema:description "Reference for wiki.yaml, wiki.yml, and wiki.json (Config).";
schema:articleBody "# Wiki Configuration\n\nThe CLI loads **Config** from `wiki.yml`, `wiki.yaml`, or `wiki.json` in the working directory (or from `-c path`).\n\nThe in-memory **Config** model uses the same nested blocks as the file (`wiki`, `graph`, `site`, `link`, `check`, `lint`, `fmt`, `sparql_service`). There is no separate flat runtime shape. `Config.load()` validates the file, injects `config_root` (the directory containing the config file), and resolves relative paths under `wiki` and `site`. Library and test code can construct configs with `Config(wiki={...}, config_root=path)` or `Config.for_root(path, wiki={...})`.\n\nConfig files are validated strictly by the TypeScript schema in [`src/wiki/schemas/wiki_config.ts`](https://github.com/wazootech/wiki/blob/main/src/wiki/schemas/wiki_config.ts), which forbids extra keys on every block. Unknown keys, removed aliases, wrong nested keys under `check`, `lint`, or `sparql_service`, invalid syntax, or a non-mapping top level all fail immediately instead of being ignored. An unknown key is reported by name against the accepted surface; the engine does not guess which key you meant.\n\nJSON configs may use `graph.context` or `graph.@context` for prefix maps (JSON-LD compatible).\n\n## Overview\n\n### Terminology\n\n| Label | Meaning |\n| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Schema optional** | Key or block may be omitted; the schema applies a default. No yaml key is strictly required for `Config.load()` to succeed. |\n| **Init** | Written by `wiki init` ([`wiki.yml`](https://github.com/wazootech/wiki/blob/main/src/wiki/templates/wiki.yml)); omitting an Init key is the same as the schema default. |\n| **Recommended** | Not enforced by schema, but you typically set it for a real wiki (for example `graph.context.wiki`, `wiki.filename_pattern`, `site.layout`). |\n| **Always on** | Behavior not gated by yaml severities (route safety, URL collisions, built-in RDF prefixes). |\n\n### Audit lanes\n\nThree audit lanes map to three commands:\n\n| Lane | Command | YAML block | Purpose |\n| ---------- | ------------ | ---------- | ------------------------------------------------------------------------------------------------------ |\n| Integrity | `wiki check` | `check:` | SHACL, JSON Schema frontmatter, layout file existence |\n| Convention | `wiki lint` | `lint:` | Links, filename pattern severity, headings, link style in prose |\n| Formatting | `wiki fmt` | `fmt:` | Mechanical Markdown via the Deno formatter's native `textWrap`, `lineWidth`, and `newLineKind` options |\n\n**Rule placement:** Mechanical markdown belongs under **`fmt:`**. Wiki policy and link conventions belong under **`lint:`**. SHACL, JSON Schema, and layout keys belong under **`check:`** — never under `lint:`. See [Style Guide](Style_Guide.md) for the full matrix.\n\n- Putting a regex under `check.filename_pattern` fails at load with a hint.\n- `check.filename_pattern` and `check.headings` fail at load — use `lint.filename_pattern` and `lint.headings`.\n\nRelative **`--input`** paths on the CLI resolve against the config file directory (same as paths in yaml), not the shell cwd.\n\n### Blocks\n\nTop-level blocks follow a **compile pipeline** plus **audit lanes**, not arbitrary grouping. `wiki init` and [docs/wiki.yml](https://github.com/wazootech/wiki/blob/main/docs/wiki.yml) use the same order as the packaged scaffold [`wiki.yml`](https://github.com/wazootech/wiki/blob/main/src/wiki/templates/wiki.yml).\n\n| Block | Role | Command(s) | Schema | Init scaffold |\n| ----------------- | ----------------------------------------------------- | --------------------------------- | -------- | ----------------- |\n| `wiki:` | Corpus on disk — inputs, assets, filename regex | `check`, `lint`, `build`, `serve` | optional | yes |\n| `graph:` | RDF compile — prefixes, document IRIs, body literals | `check`, `query`, `render` | optional | yes |\n| `site:` | Publish routing — layout path, URL prefix, path style | `build`, `serve` | optional | yes |\n| `link:` | `wiki link` apply format and rename repair map | `wiki link` | optional | yes |\n| `check:` | Integrity severities | `wiki check` | optional | yes |\n| `lint:` | Convention severities | `wiki lint` | optional | yes |\n| `sources:` | External data sources (git repos) | `wiki install`, `wiki remove` | optional | commented example |\n| `sparql_service:` | Opt-in SPARQL HTTP on `wiki serve` | `wiki serve` | optional | commented example |\n| `fmt:` | Mechanical Markdown via the Deno formatter | `wiki fmt` | optional | inline mapping |\n\n**Order in the file:** source and semantics first (`wiki`, `graph`), then publish and authoring (`site`, `link`), then severity tables (`check`, `lint`), optional serve (`sparql_service`), then `fmt` last.\n\n**Split keys** — policy lives in one block, severity or tooling in another:\n\n- **`wiki.filename_pattern`** — the regex string. **`lint.filename_pattern`** — how strictly to flag violations (`error`, `warning`, or `off`).\n- **`link.style`** — what `wiki link --apply` inserts (`standard` page links or `wikilink`). **`lint.link_style`** — whether Obsidian `[[wikilinks]]` in body prose are flagged when `link.style` is `standard`. `style` also still accepts the retired spellings `markdown` and `obsidian`, with a deprecation warning (see `link:` settings below).\n\nFor why `check`, `lint`, `fmt`, and `wiki link` are separate commands, see [Design philosophies](Design_Philosophies.md#check-lint-fmt-and-link).\n\n### Always on\n\nThese apply regardless of yaml severities:\n\n- **Route safety** — unsafe URL characters and spaces in routes (`wiki check`).\n- **Output URL collisions** — duplicate built routes (`wiki check`).\n- **SHACL** — when shape documents exist in the corpus (`wiki check`).\n- **Built-in RDF prefixes** — `schema`, `wiki`, `foaf`, `rdf`, `rdfs`, `xsd`, `owl`, `dc`, `dcterms`, `sh`, `wazoo` are always merged at runtime; yaml `graph.context` entries override or add.\n\n## Wiki (`wiki:`)\n\n```yaml\nwiki: # optional block\n input: [wiki] # default [wiki]; init writes\n assets: [assets] # default [assets] if assets/ exists, else []; init omits\n exclude: [] # default []; init omits\n filename_pattern: \"[A-Za-z0-9_()-]+\\\\.md\" # no default; recommended; init writes\n allow_unknown_keys: false # default false; init omits\n```\n\n| Key | Required | Default | Init | Audited by |\n| -------------------- | ---------------------- | ------------------------------------------- | ------ | ------------------------------------------ |\n| `input` | optional | `[wiki]` | writes | indexing (`build`, `check`, `lint`, `fmt`) |\n| `assets` | optional | `[assets]` when `assets/` exists, else `[]` | omits | `wiki build` (static copy) |\n| `exclude` | optional | `[]` | omits | indexing (skipped paths) |\n| `filename_pattern` | optional (recommended) | unset — no regex check until set | writes | `wiki lint` (`lint.filename_pattern`) |\n| `allow_unknown_keys` | optional | `false` | omits | config load |\n\nPage URLs come from paths under `wiki.input`: `wiki/Alice.md` → `/wiki/Alice/` with default `site.base_url` and `site.url_style: dir`. `index.md` in a folder owns that folder’s route (for example `wiki/index.md` → `/wiki/`).\n\nSee [Filename conventions](#filename-conventions) for regex patterns.\n\nUnknown top-level keys fail at load, so a typo such as `lnit:` is caught. Set `wiki.allow_unknown_keys: true` to accept them instead. Unknown keys inside a wiki block (`site:`, `lint:`, ...) are still rejected.\n\n## Graph (`graph:`)\n\nRDF and document URI settings for graph build, `wiki query`, microdata, and SHACL.\n\n```yaml\ngraph: # optional block\n # base_iri: unset → graph.context.wiki → https://wiki.example.org/\n content_predicate: schema:articleBody # unset by default; init writes when flagged\n include_file_extension: false # default false; init omits (commented)\n implicit_types: [] # default []; init omits (commented)\n implicit_types_policy: fallback # default fallback; init omits (commented)\n context: # merges with built-in prefixes; init writes\n schema: https://schema.org/\n wiki: https://example.org/wiki/ # recommended\n wazoo: https://schema.wazoo.dev/\n foaf: http://xmlns.com/foaf/0.1/\n dc: http://purl.org/dc/elements/1.1/\n dcterms: http://purl.org/dc/terms/\n sh: http://www.w3.org/ns/shacl#\n xsd: http://www.w3.org/2001/XMLSchema#\n```\n\n| Key | Required | Default | Init | Audited by |\n| ------------------------ | ------------------------------ | ---------------------------------------------------------- | --------------------------------------- | ------------------------------------------------- |\n| `base_iri` | optional | unset → `graph.context.wiki` → `https://wiki.example.org/` | commented example | document IRIs, `wiki query` |\n| `context` / `@context` | optional (recommended: `wiki`) | built-in prefixes only when unset | writes extended map | CURIE expansion, SHACL, microdata |\n| `content_predicate` | optional | unset — no body literals in graph | writes when `--graph-content-predicate` | SPARQL full-text |\n| `include_file_extension` | optional | `false` | omits (commented) | document URI generation |\n| `implicit_types` | optional | `[]` | omits (commented) | default `rdf:type` on untyped pages |\n| `implicit_types_policy` | optional | `fallback` | omits (commented) | `fallback` or `append` (SHACL shapes skip append) |\n\nWhen `implicit_types_policy` is `append`, frontmatter types are unioned with `implicit_types` (deduped by resolved URI).\n\n## Site (`site:`)\n\nDefault page layout and routing for `wiki build` / `wiki serve`. Branding and chrome → [Page layout](#page-layout).\n\n```yaml\nsite: # optional block\n layout: index.html # unset → built-in minimal fallback layout\n base_url: /wiki # default /wiki; init writes\n url_style: dir # default dir; init writes\n```\n\n| Key | Required | Default | Init | Audited by |\n| ----------- | ---------------------- | ------------------------------------- | ------ | ----------------------------------------------------------------------------------- |\n| `layout` | optional (recommended) | unset — packaged minimal `index.html` | writes | `wiki build`, `wiki serve`; `check.missing_layout_file` for per-page `wazoo:layout` |\n| `base_url` | optional | `/wiki` (`\"\"` allowed for site root) | writes | routes, layout `%wiki.base_url%` |\n| `url_style` | optional | `dir` (`file` → `slug.html`) | writes | output paths; overridable per CLI run |\n\n`site:` does not carry site name, theme color, favicon, or sidebar logo. If you want custom styling, write a custom layout template file and place custom assets under the `wiki.assets` directory, then configure `site.layout` to point to it.\n\nCLI flags on `wiki build` and `wiki serve` can override `site.base_url` and `site.url_style` for a single run.\n\n## Link (`link:`)\n\nSettings for the `wiki link` command family (separate from `lint.link_style` severity).\n\n```yaml\nlink: # optional block\n style: standard # default standard; init writes\n renames: {} # default {}; init omits (commented example)\n```\n\n| Key | Required | Default | Init | Audited by |\n| --------- | -------- | ------------------------------------- | ----------------- | ------------------------ |\n| `style` | optional | `standard` (`wikilink` for wikilinks) | writes | `wiki link --apply` only |\n| `renames` | optional | `{}` | commented example | `wiki link --fix-broken` |\n\n`wiki link --fix-broken` preserves the existing link kind in each file; only `--apply` uses `link.style`.\n\n**Retired spellings.** `markdown` and `obsidian` are still accepted as values for `style`, and `wiki init --link-style` accepts them too. Each prints a deprecation warning and rewrites the value to `standard` or `wikilink`:\n\n```text\nlink.style: 'obsidian' is deprecated, use 'wikilink' instead (edit config file link.style and re-run)\n```\n\nThey are accepted but never advertised: an invalid `--link-style` value lists only `standard` and `wikilink`. Rename the value in your config file to silence the warning.\n\n## Integrity checks (`check:`)\n\nUnder `check`, each rule is `error`, `warning`, or `off`:\n\n```yaml\ncheck: # optional block\n missing_layout_file: error # default error; init writes\n frontmatter_schema: error # default error; init writes\n missing_schema_ref: error # default error; init writes\n shape_definition: error # default error\n shape_unused: warning # default warning\n```\n\n| Key | Required | Default | Init | Audited by |\n| --------------------- | -------- | --------- | ------ | ------------------------------------ |\n| `missing_layout_file` | optional | `error` | writes | `wazoo:layout` paths missing on disk |\n| `frontmatter_schema` | optional | `error` | writes | JSON Schema validation failures |\n| `missing_schema_ref` | optional | `error` | writes | unloadable `wazoo:jsonSchema` refs |\n| `shape_definition` | optional | `error` | — | ill-formed SHACL shape pages |\n| `shape_unused` | optional | `warning` | — | node shapes that validate nothing |\n\nBuild-safety rules (unsafe URL characters, spaces in routes) and output URL collision detection always apply regardless of `check` settings.\n\n### JSON Schema frontmatter (`wazoo:jsonSchema`)\n\n`wiki check` validates frontmatter against JSON Schema in parallel with SHACL. Bind schemas on shape documents with **`wazoo:jsonSchema`** beside **`sh:targetClass`**; every page whose effective `type` matches that class must pass the bound schema(s). Individual pages may append extra schemas with their own `wazoo:jsonSchema` key (scalar or YAML list). Schema refs are local paths under the wiki config root (`.json` only) or remote `http(s)` URLs.\n\nShape binding documents are not validated as instances — only their schema refs are checked for loadability. Authoring detail: [SHACL](SHACL.md), [Style Guide](Style_Guide.md).\n\n## Convention audits (`lint:`)\n\nUnder `lint`, each rule is `error`, `warning`, or `off`:\n\n```yaml\nlint: # optional block\n broken_links: warning # default warning; init writes\n filename_pattern: warning # default warning; init writes\n headings: off # default off; init omits\n heading_levels: off # default off; init omits\n duplicate_headings: off # default off; init omits\n thematic_breaks: off # default off; init omits\n link_style: warning # default warning; init writes\n redundant_frontmatter: off # default off; init omits\n```\n\n| Key | Required | Default | Init | Audited by |\n| ----------------------- | -------- | --------- | ------ | --------------------------------------------------------------------------------- |\n| `broken_links` | optional | `warning` | writes | wikilinks, markdown links, fragments, assets, `wiki:` CURIEs |\n| `filename_pattern` | optional | `warning` | writes | full filename vs `wiki.filename_pattern` |\n| `headings` | optional | `off` | omits | ATX syntax, sentence-case H2+, numbered headings |\n| `heading_levels` | optional | `off` | omits | heading level gaps (for example H1 then H3) |\n| `duplicate_headings` | optional | `off` | omits | duplicate heading text on one page |\n| `thematic_breaks` | optional | `off` | omits | horizontal rules in body prose |\n| `link_style` | optional | `warning` | writes | Obsidian `[[wikilinks]]` when `link.style` is `standard` |\n| `redundant_frontmatter` | optional | `off` | omits | frontmatter that repeats a derived headline or Git date ([wiki fix](wiki_fix.md)) |\n\nATX heading syntax is also enforced by **`wiki fmt`**, the Deno Markdown formatter; Setext underlines are converted on format.\n\nWhen `link.style` is `standard`, set `lint.link_style: off` to allow wikilinks in prose, or set `link.style: wikilink` for an Obsidian-style wiki.\n\n## External data sources (`sources:`)\n\n<!-- wiki:anchor external-data-sources-sources -->\n\nDeclare external git repositories that contribute wiki pages or RDF data to the graph. After adding a source, run `wiki install` to clone it and pin the resolved commit in `wiki.lock`.\n\nSources are read-only inputs during graph construction. Wiki composes root content and installed sources into one default query view, while preserving each installed source as a stable RDF named graph for provenance and SPARQL `GRAPH` clauses.\n\n```yaml\nsources: # optional block\n - name: solar-system\n type: git\n url: https://github.com/EthanThatOneKid/solar-system-wiki.git\n ref: v0.1.0 # optional — branch, tag, or commit\n path: wiki # optional — subdirectory within the repo\n```\n\n| Key | Required | Default | Init | Command(s) |\n| ------ | -------- | --------- | ----------------- | -------------- |\n| `name` | required | — | omits (commented) | `wiki install` |\n| `type` | required | `git` | omits (commented) | `wiki install` |\n| `url` | required | — | omits (commented) | `wiki install` |\n| `ref` | optional | `HEAD` | omits (commented) | `wiki install` |\n| `path` | optional | repo root | omits (commented) | `wiki install` |\n\nEach source must have a unique `name`. The `type` field is currently limited to `git`. Unknown keys and unsupported types are rejected at config load time.\n\nRun `wiki install` to fetch all declared sources and write `wiki.lock`. Check `wiki.lock` into version control for reproducible builds. The resolved source paths are automatically appended to `wiki.input` so the existing graph, check, and build pipeline picks them up.\n\nUse `wiki graph list` to inspect the root graph and installed source graph URIs. Source graph URIs are derived from `graph.context.wiki`:\n\n- Root corpus: `{graph.context.wiki}graphs/root`\n- Installed source: `{graph.context.wiki}graphs/source/{source-name}`\n\nRequested refs, resolved commits, source URLs, cache paths, and direct/transitive dependency metadata remain source metadata; they are not embedded in graph URIs.\n\n**Transitive dependencies** are resolved recursively. After cloning each source, `wiki install` reads the source's own `wiki.yml` (or `wiki.yaml`/`wiki.json`) to discover its `sources:` block. Those transitive sources are fetched and locked too, forming a dependency tree. Circular dependency chains are detected and reported as errors. If two sources declare the same dependency name with different URLs or refs, install fails with a conflict error.\n\nWhen a source is removed with `wiki remove`, transitive sources that are no longer needed by any remaining top-level source are automatically cleaned up (cache and lockfile entry removed).\n\nAfter `wiki update`, newly declared transitive sources are installed, and orphaned sources are reported (but not auto-removed — run `wiki remove` to clean up).\n\nThe `.wiki/` source cache directory is not committed — `wiki init` scaffolds a `.gitignore` that excludes it (alongside the `_site/` build output).\n\nTo add a source without editing the config file by hand:\n\n```bash\nwiki install https://github.com/EthanThatOneKid/solar-system-wiki.git\n# GitHub shorthand also works:\nwiki install EthanThatOneKid/solar-system-wiki\n```\n\nThe name is inferred from the URL (`solar-system`). To remove it:\n\n```bash\nwiki remove solar-system\n```\n\nSee [wiki install](wiki_install.md) and [wiki remove](wiki_remove.md).\n\n### Contributing changes to a source\n\nAn installed source is a read-only input. To change one, change its upstream repository and pull the result back in; never edit the installed copy.\n\n- **Local resolution** (`wiki install`) is a cache: a shallow clone under `.wiki/sources/<name>/repo/`, pinned by `wiki.lock`. It is not committed and is not a place to author.\n- **Vendoring** (copying the pages into your own repository) makes them yours: they are then ordinary root pages and no longer track upstream. Wiki has no vendoring command or config yet ([#150](https://github.com/wazootech/wiki/issues/150)); copy the files and remove the source with `wiki remove`.\n- **Upstream contribution** keeps the source a dependency and sends the change to its owner:\n\n1. Clone the source's repository normally, outside `.wiki/`, and branch (fork it first when you cannot push). It is a wiki in its own right, so use its `wiki file` verbs and its own checks there.\n2. Open a pull request upstream.\n3. Until it merges, point your wiki at the branch: set the source's `url` to your fork (if you forked) and `ref` to the branch, then run `wiki update <name>`. This moves the `wiki.lock` entry to the branch's head.\n4. After it merges, set `url` and `ref` back and run `wiki update <name>` again. Commit `wiki.yml` and `wiki.lock`.\n\nTo follow upstream without contributing, run `wiki update` (or `wiki update <name>`); `wiki update --dry-run` shows what would move.\n\nDo not edit files in `.wiki/sources/`. The edit verbs (`wiki file set`, `patch`, `mv`, `rm`, and `wiki edit`) refuse any path under `.wiki/`. A hand edit there survives `wiki install`, stays uncommitted, and is not in `wiki.lock`, so nobody else sees it. It also breaks `wiki update`: when upstream changes the same file, the update fails with git's \"local changes would be overwritten\" error until you discard the edit (`git -C .wiki/sources/<name>/repo checkout -- .`).\n\nSPARQL Update and in-place writes to sources are not supported; see [Recursive Semantic Datasets](Recursive_Semantic_Datasets.md).\n\nFor the product framing behind recursive source composition, see [Recursive Semantic Datasets](Recursive_Semantic_Datasets.md). For what happens when a source describes the same entity as your root wiki, see [Cross-Wiki Identity](Cross_Wiki_Identity.md).\n\n## Serve API\n\nOpt-in read-only SPARQL HTTP endpoint on `wiki serve`:\n\n```yaml\nsparql_service: # optional block\n enabled: false # default false; init omits (commented)\n path: /api/sparql # default /api/sparql; init omits (commented)\n```\n\n| Key | Required | Default | Init | Audited by |\n| --------- | -------- | ------------- | ----------------- | ---------------------------- |\n| `enabled` | optional | `false` | commented example | `wiki serve` SPARQL endpoint |\n| `path` | optional | `/api/sparql` | commented example | reserved route on serve |\n\n`sparql_service.enabled` accepts YAML booleans and normalizes common string forms such as `true`, `false`, `on`, `off`, `yes`, `no`, `1`, and `0`; prefer native YAML booleans.\n\nExample when enabled:\n\n```yaml\nsparql_service:\n enabled: true\n path: /api/sparql\n```\n\nThe endpoint reuses the same SPARQL engine as `wiki query`. It is read-only and intended for local or development-oriented use. HTTP request forms, supported query types, and `Accept` negotiation are documented in [wiki serve](wiki_serve.md#sparql-endpoint).\n\nIt is **opt-in by default** because enabling it exposes raw graph-query access in addition to HTML preview.\n\n`sparql_service.path` must not collide with the effective `site.base_url` page routes or the watch endpoint. Invalid values such as `/`, `/wiki`, `/wiki/foo`, or `/wiki/__watch` are rejected when `wiki serve` starts.\n\n## Formatting (`fmt`)\n\nTop-level **`fmt`** configures Wiki's in-process `dprint-plugin-markdown` formatter. The inline mapping uses native Deno/dprint option names:\n\n```yaml\nfmt:\n textWrap: never\n lineWidth: 80\n newLineKind: lf\n```\n\n| Option | Values | Default | Effect |\n| ------------- | ----------------------------- | ------- | ------------------------------------------------------------------------ |\n| `textWrap` | `always`, `maintain`, `never` | `never` | Whether prose wraps to the configured width or preserves/avoids wrapping |\n| `lineWidth` | Positive integer | `80` | Target width when `textWrap` is `always` |\n| `newLineKind` | `auto`, `crlf`, `lf` | `lf` | Line ending emitted by the formatter |\n\nOnly an inline mapping is supported. TOML pointers, `.mdformat.toml` discovery, and mdformat-only keys such as `wrap`, `end_of_line`, and `extensions` are not supported. Existing values must be removed or rewritten using the native options above. Omitting `fmt` or using `fmt: {}` selects the Wiki CLI defaults. See [wiki fmt](wiki_fmt.md) for details.\n\n## Page layout\n\nWhen `site.layout` is set, the CLI renders every page through that page layout (`.html`). Per-page overrides use `wazoo:layout` in frontmatter; see [Wiki Page Layouts](Wiki_Page_Layouts.md).\n\n### Layout strategy\n\nThe first-class presentation contract in this repository is layout files referenced from `site.layout` (for example `index.html`).\n\n- The [wiki](wiki.md) owns the semantic markdown-to-HTML pipeline and layout slot contract.\n- Wiki page layout files are the primary built-in extension point for presentation.\n- Advanced themes or framework-specific sites such as Next.js, Mintlify, or other external docs stacks are treated as downstream integrations or separate layout/template repositories.\n\n### Minimal fallback\n\nWithout a configured layout file (or when the path is missing), every page is rendered with the built-in minimal fallback layout (`index.html`), which outputs plain, unstyled HTML containing only `<h1>` and content. It does not link any default CSS or assets and does not include a sidebar, tabs, infobox, table of contents, backlinks, or categories out-of-the-box.\n\n### Layout slots\n\nLayout files use `%wiki.*%` slot substitution (not Jinja). On each page render, the CLI builds a slot map from the current page context and replaces every known slot in your layout file. Unknown `%wiki.*%` spellings are left unchanged.\n\nLayout settings and the supported slots are documented in [Wiki Page Layouts](Wiki_Page_Layouts.md).\n\nCanonical slot list (3 slots):\n\n| Slot | Source | Substitution |\n| ----------------- | ---------------------- | ------------------------------------------------------------- |\n| `%wiki.base_url%` | `site.base_url` | HTML-escaped text (`/wiki`, or `\"\"` for site root) |\n| `%wiki.head%` | built per page | `<title>{page title} - Wiki CLI</title>` (title HTML-escaped) |\n| `%wiki.body%` | rendered markdown body | Pre-built HTML (not escaped) |\n\n**Packaged layouts**\n\n| File | When used | Typical slots |\n| ------------ | ----------------------------------- | ---------------------------- |\n| `index.html` | `site.layout` unset or missing file | `%wiki.head%`, `%wiki.body%` |\n\nExample excerpt (`index.html`):\n\n```html\n<!DOCTYPE html>\n<html lang=en>\n <head>\n<meta charset=UTF-8>\n<meta name=viewport content=width=device-width,initial-scale=1.0>\n%wiki.head%\n </head>\n <body>\n%wiki.body%\n </body>\n</html>\n```\n\n### Custom CSS\n\nThe Wiki CLI does not copy or link a default stylesheet out-of-the-box. To add styling to your pages:\n\n1. **Edit the layout file** — set `site.layout` in `wiki.yml` to a custom layout file. Link stylesheets in `<head>`, or write inline styles.\n1. **Link wiki assets** — place `.css` files under a directory listed in `wiki.assets`, then reference them from the layout, for example `<link rel=\"stylesheet\" href=\"%wiki.base_url%/assets/site.css\">`. Built assets are served at `%wiki.base_url%/assets/…` during `wiki serve` and copied into the build output.\n\n### Custom logos and icons\n\nTo customize site logos, icons, favicons, or touch icons:\n\n1. Place your asset files (such as `logo.svg`, `logo.png`, `favicon.ico`) under a directory listed in `wiki.assets`.\n1. Reference the assets from your custom layout file, for example:\n\n```html\n<img src=\"%wiki.base_url%/assets/logo.svg\" alt=\"\" width=\"80\" height=\"80\">\n```\n\nYou can also add `<link rel=\"icon\">`, `<link rel=\"apple-touch-icon\">`, or other `<head>` tags directly in your custom layout file.\n\nBuilt assets are served at `%wiki.base_url%/assets/…` during `wiki serve` and copied into the build output.\n\nSee also [Wiki Page Layouts](Wiki_Page_Layouts.md) for `site.layout`, `wazoo:layout`, and packaged layout files.\n\nThe metadata pane uses the same RDF serialization path as `wiki export` (compacted JSON-LD, Turtle, N3, N-Triples, TriG, and N-Quads). A compact **Format** chip row switches views without JavaScript. In `wiki serve`, set the initial chip with `?metadata_format=FORMAT` (for example `turtle` or `json-ld`). In `wiki build`, all supported format views are embedded in the page HTML so the picker works offline. RDF/XML output is deferred and is not offered.\n\n### Built-in CSS classes and IDs\n\nThe wiki builder generates these selectors in the rendered page content:\n\n| Selector | Where |\n| --------------------------- | ------------------------------------------------------------------------------------------------- |\n| `#article-top` | Read-view `<article>` wrapper around rendered markdown body. |\n| `#firstHeading` | Read-view page title `<h1>`; also Talk / Source / Metadata pane headings. TOC “(Top)” links here. |\n| `#siteSub` | Subtitle under Talk / Source / Metadata pane headings. |\n| `article` | Wrapper around the rendered markdown body (`#article-top`). |\n| `.layout-label` | Uppercase type or custom-layout badge in read view. |\n| `.toc` / `#toc` | Table of contents container. |\n| `#catlinks` / `.catlinks` | Category links box. |\n| `.backlinks` / `#backlinks` | Backlinks section. |\n| `.catlinks-label` | Categories heading label. |\n| `.catlinks-list` | Categories `<ul>`. |\n| `.infobox` | Typed frontmatter property table. |\n| `.page-meta` | Infobox class (used for styling). |\n| `.template-SLUG` | Per-template class on infobox (e.g. `template-person`). |\n| `toclevel-N` / `lN` | TOC list item classes for heading level N. |\n| `.wikilink` | Internal wiki page links. |\n| `pre[data-copy]` | Block code with raw source for clipboard copy. |\n| `.code-block` | Wrapper injected around copyable pre blocks. |\n| `.code-copy-btn` | Copy button shown on code-block hover/focus. |\n\n### JavaScript hooks\n\nCustom layout files can utilize standard JavaScript hooks or customize their own. In premium layouts (such as template repositories), the following JavaScript features can be implemented:\n\n| Function | Purpose |\n| ------------------------------ | ---------------------------------------------------- |\n| `switchTab(viewName)` | Switch between read / talk / source / metadata tabs. |\n| `loadTalkNotes()` | Load per-page local-storage notes. |\n| `saveTalkNotes()` | Save per-page notes to localStorage. |\n| `clearTalkNotes()` | Clear per-page notes. |\n| `copySourceCode()` | Copy markdown source to clipboard. |\n| `copyPreContent()` | Copy a `pre[data-copy]` block to clipboard. |\n| `initCodeCopyButtons()` | Wrap copyable pre blocks and inject copy buttons. |\n| `toggleToc()` | Show/hide table of contents. |\n| `goToRandomArticle()` | Navigate to a random page. |\n| `triggerSearch()` | Execute search and navigate to first match. |\n| `onSearchInput(e)` | Live search suggestions. |\n| `handleSearchKey(e)` | Keyboard navigation for search suggestions. |\n| `navigateSearch(slug)` | Navigate to a search result. |\n| `applyCategoryFilterFromUrl()` | Filter index page by `?category=` URL parameter. |\n\nIf the configured page layout file does not exist, the packaged minimal `index.html` layout is used silently — no error.\n\n## Filename conventions\n\nThe CLI does not hard-code kebab-case. Projects choose a convention with **`wiki.filename_pattern`**, matched against the **full filename** (including `.md`) on markdown files only.\n\n**Wikipedia-style (recommended):** preserved capitalization and underscores — `Gregory_Davidson.md`, `Pokemon_Diamond_(copy_1).md`, `LLM_Wiki_CLI.md`. Use a pattern such as:\n\n```yaml\nwiki:\n filename_pattern: \"[A-Za-z0-9_()-]+\\\\.md\"\n```\n\n**Kebab-case (optional):** if you prefer `gregory-house.md`, set an explicit pattern (for example `[a-z0-9-]+\\\\.md`) and enforce it via `lint.filename_pattern`. Wikipedia-style and kebab-case should not be mixed in one wiki.\n\nPage routes keep the casing from the filename; GitHub Pages URLs are case-sensitive.\n\n`wiki link --fix-broken` preserves the existing link kind in each file; only `--apply` uses `link.style`.\n\nWhen `link.style` is `standard`, `lint.link_style` (default `warning`) flags Obsidian wikilinks (`[[Page]]`) in body prose. Set `lint.link_style: off` to allow wikilinks while keeping standard links as the apply format, or set `link.style: wikilink` for an Obsidian-style wiki.\n\n## Formatting (`fmt`)\n\n`wiki fmt` uses native Deno/dprint options under an inline `fmt:` mapping. The accepted options, defaults, and removed mdformat/TOML behavior are documented in [wiki fmt](wiki_fmt.md).\n\n## Integrity checks (`check`)\n\nUnder `check`, each rule is `error`, `warning`, or `off`:\n\n| Rule key | Default | What it audits |\n| --------------------- | --------- | ------------------------------------------------------------------------------------------ |\n| `missing_layout_file` | `error` | `wazoo:layout` paths that do not resolve to a readable `.html` file |\n| `frontmatter_schema` | `error` | Frontmatter that fails JSON Schema validation |\n| `missing_schema_ref` | `error` | `wazoo:jsonSchema` paths or URLs that cannot be loaded |\n| `shape_definition` | `error` | Ill-formed SHACL shape pages (see [wiki check](wiki_check.md#shape-definitions)) |\n| `shape_unused` | `warning` | Node shape pages that validate nothing (see [wiki check](wiki_check.md#shape-definitions)) |\n| `remote_schema_refs` | `allow` | Policy for remote `http(s)` schema refs: `allow`, `deny`, or `allowlist` |\n| `remote_schema_hosts` | `[]` | Hostnames permitted when `remote_schema_refs` is `allowlist` |\n\nBuild-safety rules (unsafe URL characters, spaces in routes) and output URL collision detection always apply regardless of `check` settings.\n\n### JSON Schema frontmatter (`wazoo:jsonSchema`)\n\n`wiki check` validates frontmatter against JSON Schema in parallel with SHACL. Bind schemas on shape documents with **`wazoo:jsonSchema`** beside **`sh:targetClass`**; every page whose effective `type` matches that class must pass the bound schema(s). Individual pages may append extra schemas with their own `wazoo:jsonSchema` key (scalar or YAML list). Schema refs are local paths under the wiki config root (`.json` only) or remote `http(s)` URLs. Remote refs can trigger outbound network requests; set `check.remote_schema_refs: deny` in CI over untrusted wikis, or `allowlist` with `check.remote_schema_hosts` for trusted hosts only.\n\nShape binding documents are not validated as instances — only their schema refs are checked for loadability. Authoring detail: [SHACL](SHACL.md), [Style Guide](Style_Guide.md).\n\n## Convention audits (`lint`)\n\nUnder `lint`, each rule is `error`, `warning`, or `off`:\n\n| Rule key | Default | What it audits |\n| ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `broken_links` | `warning` | Wikilinks, internal markdown links, heading fragments, assets, `wiki:` CURIEs |\n| `filename_pattern` | `warning` | Full filename vs `wiki.filename_pattern` regex |\n| `headings` | `off` | ATX `#` headings only (no Setext underlines), sentence-case H2+, H1 title case conventional, numbered headings |\n| `thematic_breaks` | `off` | Horizontal rules (`---`, `***`, `___`) in body prose |\n| `link_style` | `warning` | Obsidian wikilinks (`[[Page]]`) in body prose when `link.style` is `standard` |\n| `redundant_frontmatter` | `off` | A `headline`, `dateCreated`, or `dateModified` that repeats the value the graph derives from the H1 or Git history; remove with [wiki fix](wiki_fix.md) |\n\n`redundant_frontmatter` is `off` by default because many wikis follow the convention of repeating the H1 as `headline`: as a default warning it would fail every such page under `lint --strict`. Turn it on once the redundant keys are removed with `wiki fix --apply`, as this wiki does in `docs/wiki.yml`.\n\n### What `broken_links` accepts\n\n`broken_links` reports a link only when its target is missing. It accepts everything CommonMark allows:\n\n- **Titled and angle-bracket destinations** — `[a](Page.md \"Title\")` and `[a](<Page.md>)` resolve like `[a](Page.md)`; `wiki file mv` keeps the title when it rewrites them.\n- **URLs with a scheme** — `https://`, `ftp://`, `obsidian://`, and `//host` are external and never checked.\n- **Site-root-relative links** — `[a](/wiki/Guides/Setup/)` is resolved against `site.base_url` and `site.url_style` and checked against the page that route maps to. A missing route or heading is still reported; a link outside `site.base_url`, or to a non-page file, is checked as before.\n- **`#top`** — scrolls to the top of the page and needs no matching heading.\n- **Fenced and commented-out links** — links inside backtick or `~~~` fences and HTML comments are skipped.\n\n## This repository\n\n`docs/wiki.yml` is the dogfood wiki config for this repository. It follows the same block order as the packaged scaffold, but with project-specific overrides — `graph.context.wiki` for GitHub Pages and `graph.content_predicate: schema:articleBody` for SPARQL full-text.\n\n## Related\n\n- [wiki](wiki.md#global-options) — `-c` and `--input` global options\n- [wiki init](wiki_init.md) — scaffold a new wiki project\n- [wiki check](wiki_check.md) — integrity checks\n- [wiki lint](wiki_lint.md) — convention audits\n- [wiki query](wiki_query.md) — ad-hoc SPARQL\n- [wiki render](wiki_render.md) — inline SPARQL tables\n- [wiki serve](wiki_serve.md#sparql-endpoint) — `#serve-api` config block\n- [Graph Cache](Graph_Cache.md) — `--cache` and graph reuse\n- [Style Guide](Style_Guide.md) — shapes and frontmatter";
schema:headline "Wiki Configuration";
schema:dateCreated "2026-10-31T23:19:03Z"^^xsd:dateTime;
schema:dateModified "2026-10-31T23:19:03Z"^^xsd:dateTime.
@prefix schema: <https://schema.org/>.
@prefix wiki: <https://wazootech.github.io/wiki/>.
@prefix foaf: <http://xmlns.com/foaf/0.1/>.
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
@prefix owl: <http://www.w3.org/2002/07/owl#>.
@prefix dc: <http://purl.org/dc/elements/1.1/>.
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix sh: <http://www.w3.org/ns/shacl#>.
@prefix wazoo: <https://schema.wazoo.dev/>.
wiki:Wiki_Configuration a schema:TechArticle;
schema:description "Reference for wiki.yaml, wiki.yml, and wiki.json (Config).";
schema:articleBody "# Wiki Configuration\n\nThe CLI loads **Config** from `wiki.yml`, `wiki.yaml`, or `wiki.json` in the working directory (or from `-c path`).\n\nThe in-memory **Config** model uses the same nested blocks as the file (`wiki`, `graph`, `site`, `link`, `check`, `lint`, `fmt`, `sparql_service`). There is no separate flat runtime shape. `Config.load()` validates the file, injects `config_root` (the directory containing the config file), and resolves relative paths under `wiki` and `site`. Library and test code can construct configs with `Config(wiki={...}, config_root=path)` or `Config.for_root(path, wiki={...})`.\n\nConfig files are validated strictly by the TypeScript schema in [`src/wiki/schemas/wiki_config.ts`](https://github.com/wazootech/wiki/blob/main/src/wiki/schemas/wiki_config.ts), which forbids extra keys on every block. Unknown keys, removed aliases, wrong nested keys under `check`, `lint`, or `sparql_service`, invalid syntax, or a non-mapping top level all fail immediately instead of being ignored. An unknown key is reported by name against the accepted surface; the engine does not guess which key you meant.\n\nJSON configs may use `graph.context` or `graph.@context` for prefix maps (JSON-LD compatible).\n\n## Overview\n\n### Terminology\n\n| Label | Meaning |\n| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Schema optional** | Key or block may be omitted; the schema applies a default. No yaml key is strictly required for `Config.load()` to succeed. |\n| **Init** | Written by `wiki init` ([`wiki.yml`](https://github.com/wazootech/wiki/blob/main/src/wiki/templates/wiki.yml)); omitting an Init key is the same as the schema default. |\n| **Recommended** | Not enforced by schema, but you typically set it for a real wiki (for example `graph.context.wiki`, `wiki.filename_pattern`, `site.layout`). |\n| **Always on** | Behavior not gated by yaml severities (route safety, URL collisions, built-in RDF prefixes). |\n\n### Audit lanes\n\nThree audit lanes map to three commands:\n\n| Lane | Command | YAML block | Purpose |\n| ---------- | ------------ | ---------- | ------------------------------------------------------------------------------------------------------ |\n| Integrity | `wiki check` | `check:` | SHACL, JSON Schema frontmatter, layout file existence |\n| Convention | `wiki lint` | `lint:` | Links, filename pattern severity, headings, link style in prose |\n| Formatting | `wiki fmt` | `fmt:` | Mechanical Markdown via the Deno formatter's native `textWrap`, `lineWidth`, and `newLineKind` options |\n\n**Rule placement:** Mechanical markdown belongs under **`fmt:`**. Wiki policy and link conventions belong under **`lint:`**. SHACL, JSON Schema, and layout keys belong under **`check:`** — never under `lint:`. See [Style Guide](Style_Guide.md) for the full matrix.\n\n- Putting a regex under `check.filename_pattern` fails at load with a hint.\n- `check.filename_pattern` and `check.headings` fail at load — use `lint.filename_pattern` and `lint.headings`.\n\nRelative **`--input`** paths on the CLI resolve against the config file directory (same as paths in yaml), not the shell cwd.\n\n### Blocks\n\nTop-level blocks follow a **compile pipeline** plus **audit lanes**, not arbitrary grouping. `wiki init` and [docs/wiki.yml](https://github.com/wazootech/wiki/blob/main/docs/wiki.yml) use the same order as the packaged scaffold [`wiki.yml`](https://github.com/wazootech/wiki/blob/main/src/wiki/templates/wiki.yml).\n\n| Block | Role | Command(s) | Schema | Init scaffold |\n| ----------------- | ----------------------------------------------------- | --------------------------------- | -------- | ----------------- |\n| `wiki:` | Corpus on disk — inputs, assets, filename regex | `check`, `lint`, `build`, `serve` | optional | yes |\n| `graph:` | RDF compile — prefixes, document IRIs, body literals | `check`, `query`, `render` | optional | yes |\n| `site:` | Publish routing — layout path, URL prefix, path style | `build`, `serve` | optional | yes |\n| `link:` | `wiki link` apply format and rename repair map | `wiki link` | optional | yes |\n| `check:` | Integrity severities | `wiki check` | optional | yes |\n| `lint:` | Convention severities | `wiki lint` | optional | yes |\n| `sources:` | External data sources (git repos) | `wiki install`, `wiki remove` | optional | commented example |\n| `sparql_service:` | Opt-in SPARQL HTTP on `wiki serve` | `wiki serve` | optional | commented example |\n| `fmt:` | Mechanical Markdown via the Deno formatter | `wiki fmt` | optional | inline mapping |\n\n**Order in the file:** source and semantics first (`wiki`, `graph`), then publish and authoring (`site`, `link`), then severity tables (`check`, `lint`), optional serve (`sparql_service`), then `fmt` last.\n\n**Split keys** — policy lives in one block, severity or tooling in another:\n\n- **`wiki.filename_pattern`** — the regex string. **`lint.filename_pattern`** — how strictly to flag violations (`error`, `warning`, or `off`).\n- **`link.style`** — what `wiki link --apply` inserts (`standard` page links or `wikilink`). **`lint.link_style`** — whether Obsidian `[[wikilinks]]` in body prose are flagged when `link.style` is `standard`. `style` also still accepts the retired spellings `markdown` and `obsidian`, with a deprecation warning (see `link:` settings below).\n\nFor why `check`, `lint`, `fmt`, and `wiki link` are separate commands, see [Design philosophies](Design_Philosophies.md#check-lint-fmt-and-link).\n\n### Always on\n\nThese apply regardless of yaml severities:\n\n- **Route safety** — unsafe URL characters and spaces in routes (`wiki check`).\n- **Output URL collisions** — duplicate built routes (`wiki check`).\n- **SHACL** — when shape documents exist in the corpus (`wiki check`).\n- **Built-in RDF prefixes** — `schema`, `wiki`, `foaf`, `rdf`, `rdfs`, `xsd`, `owl`, `dc`, `dcterms`, `sh`, `wazoo` are always merged at runtime; yaml `graph.context` entries override or add.\n\n## Wiki (`wiki:`)\n\n```yaml\nwiki: # optional block\n input: [wiki] # default [wiki]; init writes\n assets: [assets] # default [assets] if assets/ exists, else []; init omits\n exclude: [] # default []; init omits\n filename_pattern: \"[A-Za-z0-9_()-]+\\\\.md\" # no default; recommended; init writes\n allow_unknown_keys: false # default false; init omits\n```\n\n| Key | Required | Default | Init | Audited by |\n| -------------------- | ---------------------- | ------------------------------------------- | ------ | ------------------------------------------ |\n| `input` | optional | `[wiki]` | writes | indexing (`build`, `check`, `lint`, `fmt`) |\n| `assets` | optional | `[assets]` when `assets/` exists, else `[]` | omits | `wiki build` (static copy) |\n| `exclude` | optional | `[]` | omits | indexing (skipped paths) |\n| `filename_pattern` | optional (recommended) | unset — no regex check until set | writes | `wiki lint` (`lint.filename_pattern`) |\n| `allow_unknown_keys` | optional | `false` | omits | config load |\n\nPage URLs come from paths under `wiki.input`: `wiki/Alice.md` → `/wiki/Alice/` with default `site.base_url` and `site.url_style: dir`. `index.md` in a folder owns that folder’s route (for example `wiki/index.md` → `/wiki/`).\n\nSee [Filename conventions](#filename-conventions) for regex patterns.\n\nUnknown top-level keys fail at load, so a typo such as `lnit:` is caught. Set `wiki.allow_unknown_keys: true` to accept them instead. Unknown keys inside a wiki block (`site:`, `lint:`, ...) are still rejected.\n\n## Graph (`graph:`)\n\nRDF and document URI settings for graph build, `wiki query`, microdata, and SHACL.\n\n```yaml\ngraph: # optional block\n # base_iri: unset → graph.context.wiki → https://wiki.example.org/\n content_predicate: schema:articleBody # unset by default; init writes when flagged\n include_file_extension: false # default false; init omits (commented)\n implicit_types: [] # default []; init omits (commented)\n implicit_types_policy: fallback # default fallback; init omits (commented)\n context: # merges with built-in prefixes; init writes\n schema: https://schema.org/\n wiki: https://example.org/wiki/ # recommended\n wazoo: https://schema.wazoo.dev/\n foaf: http://xmlns.com/foaf/0.1/\n dc: http://purl.org/dc/elements/1.1/\n dcterms: http://purl.org/dc/terms/\n sh: http://www.w3.org/ns/shacl#\n xsd: http://www.w3.org/2001/XMLSchema#\n```\n\n| Key | Required | Default | Init | Audited by |\n| ------------------------ | ------------------------------ | ---------------------------------------------------------- | --------------------------------------- | ------------------------------------------------- |\n| `base_iri` | optional | unset → `graph.context.wiki` → `https://wiki.example.org/` | commented example | document IRIs, `wiki query` |\n| `context` / `@context` | optional (recommended: `wiki`) | built-in prefixes only when unset | writes extended map | CURIE expansion, SHACL, microdata |\n| `content_predicate` | optional | unset — no body literals in graph | writes when `--graph-content-predicate` | SPARQL full-text |\n| `include_file_extension` | optional | `false` | omits (commented) | document URI generation |\n| `implicit_types` | optional | `[]` | omits (commented) | default `rdf:type` on untyped pages |\n| `implicit_types_policy` | optional | `fallback` | omits (commented) | `fallback` or `append` (SHACL shapes skip append) |\n\nWhen `implicit_types_policy` is `append`, frontmatter types are unioned with `implicit_types` (deduped by resolved URI).\n\n## Site (`site:`)\n\nDefault page layout and routing for `wiki build` / `wiki serve`. Branding and chrome → [Page layout](#page-layout).\n\n```yaml\nsite: # optional block\n layout: index.html # unset → built-in minimal fallback layout\n base_url: /wiki # default /wiki; init writes\n url_style: dir # default dir; init writes\n```\n\n| Key | Required | Default | Init | Audited by |\n| ----------- | ---------------------- | ------------------------------------- | ------ | ----------------------------------------------------------------------------------- |\n| `layout` | optional (recommended) | unset — packaged minimal `index.html` | writes | `wiki build`, `wiki serve`; `check.missing_layout_file` for per-page `wazoo:layout` |\n| `base_url` | optional | `/wiki` (`\"\"` allowed for site root) | writes | routes, layout `%wiki.base_url%` |\n| `url_style` | optional | `dir` (`file` → `slug.html`) | writes | output paths; overridable per CLI run |\n\n`site:` does not carry site name, theme color, favicon, or sidebar logo. If you want custom styling, write a custom layout template file and place custom assets under the `wiki.assets` directory, then configure `site.layout` to point to it.\n\nCLI flags on `wiki build` and `wiki serve` can override `site.base_url` and `site.url_style` for a single run.\n\n## Link (`link:`)\n\nSettings for the `wiki link` command family (separate from `lint.link_style` severity).\n\n```yaml\nlink: # optional block\n style: standard # default standard; init writes\n renames: {} # default {}; init omits (commented example)\n```\n\n| Key | Required | Default | Init | Audited by |\n| --------- | -------- | ------------------------------------- | ----------------- | ------------------------ |\n| `style` | optional | `standard` (`wikilink` for wikilinks) | writes | `wiki link --apply` only |\n| `renames` | optional | `{}` | commented example | `wiki link --fix-broken` |\n\n`wiki link --fix-broken` preserves the existing link kind in each file; only `--apply` uses `link.style`.\n\n**Retired spellings.** `markdown` and `obsidian` are still accepted as values for `style`, and `wiki init --link-style` accepts them too. Each prints a deprecation warning and rewrites the value to `standard` or `wikilink`:\n\n```text\nlink.style: 'obsidian' is deprecated, use 'wikilink' instead (edit config file link.style and re-run)\n```\n\nThey are accepted but never advertised: an invalid `--link-style` value lists only `standard` and `wikilink`. Rename the value in your config file to silence the warning.\n\n## Integrity checks (`check:`)\n\nUnder `check`, each rule is `error`, `warning`, or `off`:\n\n```yaml\ncheck: # optional block\n missing_layout_file: error # default error; init writes\n frontmatter_schema: error # default error; init writes\n missing_schema_ref: error # default error; init writes\n shape_definition: error # default error\n shape_unused: warning # default warning\n```\n\n| Key | Required | Default | Init | Audited by |\n| --------------------- | -------- | --------- | ------ | ------------------------------------ |\n| `missing_layout_file` | optional | `error` | writes | `wazoo:layout` paths missing on disk |\n| `frontmatter_schema` | optional | `error` | writes | JSON Schema validation failures |\n| `missing_schema_ref` | optional | `error` | writes | unloadable `wazoo:jsonSchema` refs |\n| `shape_definition` | optional | `error` | — | ill-formed SHACL shape pages |\n| `shape_unused` | optional | `warning` | — | node shapes that validate nothing |\n\nBuild-safety rules (unsafe URL characters, spaces in routes) and output URL collision detection always apply regardless of `check` settings.\n\n### JSON Schema frontmatter (`wazoo:jsonSchema`)\n\n`wiki check` validates frontmatter against JSON Schema in parallel with SHACL. Bind schemas on shape documents with **`wazoo:jsonSchema`** beside **`sh:targetClass`**; every page whose effective `type` matches that class must pass the bound schema(s). Individual pages may append extra schemas with their own `wazoo:jsonSchema` key (scalar or YAML list). Schema refs are local paths under the wiki config root (`.json` only) or remote `http(s)` URLs.\n\nShape binding documents are not validated as instances — only their schema refs are checked for loadability. Authoring detail: [SHACL](SHACL.md), [Style Guide](Style_Guide.md).\n\n## Convention audits (`lint:`)\n\nUnder `lint`, each rule is `error`, `warning`, or `off`:\n\n```yaml\nlint: # optional block\n broken_links: warning # default warning; init writes\n filename_pattern: warning # default warning; init writes\n headings: off # default off; init omits\n heading_levels: off # default off; init omits\n duplicate_headings: off # default off; init omits\n thematic_breaks: off # default off; init omits\n link_style: warning # default warning; init writes\n redundant_frontmatter: off # default off; init omits\n```\n\n| Key | Required | Default | Init | Audited by |\n| ----------------------- | -------- | --------- | ------ | --------------------------------------------------------------------------------- |\n| `broken_links` | optional | `warning` | writes | wikilinks, markdown links, fragments, assets, `wiki:` CURIEs |\n| `filename_pattern` | optional | `warning` | writes | full filename vs `wiki.filename_pattern` |\n| `headings` | optional | `off` | omits | ATX syntax, sentence-case H2+, numbered headings |\n| `heading_levels` | optional | `off` | omits | heading level gaps (for example H1 then H3) |\n| `duplicate_headings` | optional | `off` | omits | duplicate heading text on one page |\n| `thematic_breaks` | optional | `off` | omits | horizontal rules in body prose |\n| `link_style` | optional | `warning` | writes | Obsidian `[[wikilinks]]` when `link.style` is `standard` |\n| `redundant_frontmatter` | optional | `off` | omits | frontmatter that repeats a derived headline or Git date ([wiki fix](wiki_fix.md)) |\n\nATX heading syntax is also enforced by **`wiki fmt`**, the Deno Markdown formatter; Setext underlines are converted on format.\n\nWhen `link.style` is `standard`, set `lint.link_style: off` to allow wikilinks in prose, or set `link.style: wikilink` for an Obsidian-style wiki.\n\n## External data sources (`sources:`)\n\n<!-- wiki:anchor external-data-sources-sources -->\n\nDeclare external git repositories that contribute wiki pages or RDF data to the graph. After adding a source, run `wiki install` to clone it and pin the resolved commit in `wiki.lock`.\n\nSources are read-only inputs during graph construction. Wiki composes root content and installed sources into one default query view, while preserving each installed source as a stable RDF named graph for provenance and SPARQL `GRAPH` clauses.\n\n```yaml\nsources: # optional block\n - name: solar-system\n type: git\n url: https://github.com/EthanThatOneKid/solar-system-wiki.git\n ref: v0.1.0 # optional — branch, tag, or commit\n path: wiki # optional — subdirectory within the repo\n```\n\n| Key | Required | Default | Init | Command(s) |\n| ------ | -------- | --------- | ----------------- | -------------- |\n| `name` | required | — | omits (commented) | `wiki install` |\n| `type` | required | `git` | omits (commented) | `wiki install` |\n| `url` | required | — | omits (commented) | `wiki install` |\n| `ref` | optional | `HEAD` | omits (commented) | `wiki install` |\n| `path` | optional | repo root | omits (commented) | `wiki install` |\n\nEach source must have a unique `name`. The `type` field is currently limited to `git`. Unknown keys and unsupported types are rejected at config load time.\n\nRun `wiki install` to fetch all declared sources and write `wiki.lock`. Check `wiki.lock` into version control for reproducible builds. The resolved source paths are automatically appended to `wiki.input` so the existing graph, check, and build pipeline picks them up.\n\nUse `wiki graph list` to inspect the root graph and installed source graph URIs. Source graph URIs are derived from `graph.context.wiki`:\n\n- Root corpus: `{graph.context.wiki}graphs/root`\n- Installed source: `{graph.context.wiki}graphs/source/{source-name}`\n\nRequested refs, resolved commits, source URLs, cache paths, and direct/transitive dependency metadata remain source metadata; they are not embedded in graph URIs.\n\n**Transitive dependencies** are resolved recursively. After cloning each source, `wiki install` reads the source's own `wiki.yml` (or `wiki.yaml`/`wiki.json`) to discover its `sources:` block. Those transitive sources are fetched and locked too, forming a dependency tree. Circular dependency chains are detected and reported as errors. If two sources declare the same dependency name with different URLs or refs, install fails with a conflict error.\n\nWhen a source is removed with `wiki remove`, transitive sources that are no longer needed by any remaining top-level source are automatically cleaned up (cache and lockfile entry removed).\n\nAfter `wiki update`, newly declared transitive sources are installed, and orphaned sources are reported (but not auto-removed — run `wiki remove` to clean up).\n\nThe `.wiki/` source cache directory is not committed — `wiki init` scaffolds a `.gitignore` that excludes it (alongside the `_site/` build output).\n\nTo add a source without editing the config file by hand:\n\n```bash\nwiki install https://github.com/EthanThatOneKid/solar-system-wiki.git\n# GitHub shorthand also works:\nwiki install EthanThatOneKid/solar-system-wiki\n```\n\nThe name is inferred from the URL (`solar-system`). To remove it:\n\n```bash\nwiki remove solar-system\n```\n\nSee [wiki install](wiki_install.md) and [wiki remove](wiki_remove.md).\n\n### Contributing changes to a source\n\nAn installed source is a read-only input. To change one, change its upstream repository and pull the result back in; never edit the installed copy.\n\n- **Local resolution** (`wiki install`) is a cache: a shallow clone under `.wiki/sources/<name>/repo/`, pinned by `wiki.lock`. It is not committed and is not a place to author.\n- **Vendoring** (copying the pages into your own repository) makes them yours: they are then ordinary root pages and no longer track upstream. Wiki has no vendoring command or config yet ([#150](https://github.com/wazootech/wiki/issues/150)); copy the files and remove the source with `wiki remove`.\n- **Upstream contribution** keeps the source a dependency and sends the change to its owner:\n\n1. Clone the source's repository normally, outside `.wiki/`, and branch (fork it first when you cannot push). It is a wiki in its own right, so use its `wiki file` verbs and its own checks there.\n2. Open a pull request upstream.\n3. Until it merges, point your wiki at the branch: set the source's `url` to your fork (if you forked) and `ref` to the branch, then run `wiki update <name>`. This moves the `wiki.lock` entry to the branch's head.\n4. After it merges, set `url` and `ref` back and run `wiki update <name>` again. Commit `wiki.yml` and `wiki.lock`.\n\nTo follow upstream without contributing, run `wiki update` (or `wiki update <name>`); `wiki update --dry-run` shows what would move.\n\nDo not edit files in `.wiki/sources/`. The edit verbs (`wiki file set`, `patch`, `mv`, `rm`, and `wiki edit`) refuse any path under `.wiki/`. A hand edit there survives `wiki install`, stays uncommitted, and is not in `wiki.lock`, so nobody else sees it. It also breaks `wiki update`: when upstream changes the same file, the update fails with git's \"local changes would be overwritten\" error until you discard the edit (`git -C .wiki/sources/<name>/repo checkout -- .`).\n\nSPARQL Update and in-place writes to sources are not supported; see [Recursive Semantic Datasets](Recursive_Semantic_Datasets.md).\n\nFor the product framing behind recursive source composition, see [Recursive Semantic Datasets](Recursive_Semantic_Datasets.md). For what happens when a source describes the same entity as your root wiki, see [Cross-Wiki Identity](Cross_Wiki_Identity.md).\n\n## Serve API\n\nOpt-in read-only SPARQL HTTP endpoint on `wiki serve`:\n\n```yaml\nsparql_service: # optional block\n enabled: false # default false; init omits (commented)\n path: /api/sparql # default /api/sparql; init omits (commented)\n```\n\n| Key | Required | Default | Init | Audited by |\n| --------- | -------- | ------------- | ----------------- | ---------------------------- |\n| `enabled` | optional | `false` | commented example | `wiki serve` SPARQL endpoint |\n| `path` | optional | `/api/sparql` | commented example | reserved route on serve |\n\n`sparql_service.enabled` accepts YAML booleans and normalizes common string forms such as `true`, `false`, `on`, `off`, `yes`, `no`, `1`, and `0`; prefer native YAML booleans.\n\nExample when enabled:\n\n```yaml\nsparql_service:\n enabled: true\n path: /api/sparql\n```\n\nThe endpoint reuses the same SPARQL engine as `wiki query`. It is read-only and intended for local or development-oriented use. HTTP request forms, supported query types, and `Accept` negotiation are documented in [wiki serve](wiki_serve.md#sparql-endpoint).\n\nIt is **opt-in by default** because enabling it exposes raw graph-query access in addition to HTML preview.\n\n`sparql_service.path` must not collide with the effective `site.base_url` page routes or the watch endpoint. Invalid values such as `/`, `/wiki`, `/wiki/foo`, or `/wiki/__watch` are rejected when `wiki serve` starts.\n\n## Formatting (`fmt`)\n\nTop-level **`fmt`** configures Wiki's in-process `dprint-plugin-markdown` formatter. The inline mapping uses native Deno/dprint option names:\n\n```yaml\nfmt:\n textWrap: never\n lineWidth: 80\n newLineKind: lf\n```\n\n| Option | Values | Default | Effect |\n| ------------- | ----------------------------- | ------- | ------------------------------------------------------------------------ |\n| `textWrap` | `always`, `maintain`, `never` | `never` | Whether prose wraps to the configured width or preserves/avoids wrapping |\n| `lineWidth` | Positive integer | `80` | Target width when `textWrap` is `always` |\n| `newLineKind` | `auto`, `crlf`, `lf` | `lf` | Line ending emitted by the formatter |\n\nOnly an inline mapping is supported. TOML pointers, `.mdformat.toml` discovery, and mdformat-only keys such as `wrap`, `end_of_line`, and `extensions` are not supported. Existing values must be removed or rewritten using the native options above. Omitting `fmt` or using `fmt: {}` selects the Wiki CLI defaults. See [wiki fmt](wiki_fmt.md) for details.\n\n## Page layout\n\nWhen `site.layout` is set, the CLI renders every page through that page layout (`.html`). Per-page overrides use `wazoo:layout` in frontmatter; see [Wiki Page Layouts](Wiki_Page_Layouts.md).\n\n### Layout strategy\n\nThe first-class presentation contract in this repository is layout files referenced from `site.layout` (for example `index.html`).\n\n- The [wiki](wiki.md) owns the semantic markdown-to-HTML pipeline and layout slot contract.\n- Wiki page layout files are the primary built-in extension point for presentation.\n- Advanced themes or framework-specific sites such as Next.js, Mintlify, or other external docs stacks are treated as downstream integrations or separate layout/template repositories.\n\n### Minimal fallback\n\nWithout a configured layout file (or when the path is missing), every page is rendered with the built-in minimal fallback layout (`index.html`), which outputs plain, unstyled HTML containing only `<h1>` and content. It does not link any default CSS or assets and does not include a sidebar, tabs, infobox, table of contents, backlinks, or categories out-of-the-box.\n\n### Layout slots\n\nLayout files use `%wiki.*%` slot substitution (not Jinja). On each page render, the CLI builds a slot map from the current page context and replaces every known slot in your layout file. Unknown `%wiki.*%` spellings are left unchanged.\n\nLayout settings and the supported slots are documented in [Wiki Page Layouts](Wiki_Page_Layouts.md).\n\nCanonical slot list (3 slots):\n\n| Slot | Source | Substitution |\n| ----------------- | ---------------------- | ------------------------------------------------------------- |\n| `%wiki.base_url%` | `site.base_url` | HTML-escaped text (`/wiki`, or `\"\"` for site root) |\n| `%wiki.head%` | built per page | `<title>{page title} - Wiki CLI</title>` (title HTML-escaped) |\n| `%wiki.body%` | rendered markdown body | Pre-built HTML (not escaped) |\n\n**Packaged layouts**\n\n| File | When used | Typical slots |\n| ------------ | ----------------------------------- | ---------------------------- |\n| `index.html` | `site.layout` unset or missing file | `%wiki.head%`, `%wiki.body%` |\n\nExample excerpt (`index.html`):\n\n```html\n<!DOCTYPE html>\n<html lang=en>\n <head>\n<meta charset=UTF-8>\n<meta name=viewport content=width=device-width,initial-scale=1.0>\n%wiki.head%\n </head>\n <body>\n%wiki.body%\n </body>\n</html>\n```\n\n### Custom CSS\n\nThe Wiki CLI does not copy or link a default stylesheet out-of-the-box. To add styling to your pages:\n\n1. **Edit the layout file** — set `site.layout` in `wiki.yml` to a custom layout file. Link stylesheets in `<head>`, or write inline styles.\n1. **Link wiki assets** — place `.css` files under a directory listed in `wiki.assets`, then reference them from the layout, for example `<link rel=\"stylesheet\" href=\"%wiki.base_url%/assets/site.css\">`. Built assets are served at `%wiki.base_url%/assets/…` during `wiki serve` and copied into the build output.\n\n### Custom logos and icons\n\nTo customize site logos, icons, favicons, or touch icons:\n\n1. Place your asset files (such as `logo.svg`, `logo.png`, `favicon.ico`) under a directory listed in `wiki.assets`.\n1. Reference the assets from your custom layout file, for example:\n\n```html\n<img src=\"%wiki.base_url%/assets/logo.svg\" alt=\"\" width=\"80\" height=\"80\">\n```\n\nYou can also add `<link rel=\"icon\">`, `<link rel=\"apple-touch-icon\">`, or other `<head>` tags directly in your custom layout file.\n\nBuilt assets are served at `%wiki.base_url%/assets/…` during `wiki serve` and copied into the build output.\n\nSee also [Wiki Page Layouts](Wiki_Page_Layouts.md) for `site.layout`, `wazoo:layout`, and packaged layout files.\n\nThe metadata pane uses the same RDF serialization path as `wiki export` (compacted JSON-LD, Turtle, N3, N-Triples, TriG, and N-Quads). A compact **Format** chip row switches views without JavaScript. In `wiki serve`, set the initial chip with `?metadata_format=FORMAT` (for example `turtle` or `json-ld`). In `wiki build`, all supported format views are embedded in the page HTML so the picker works offline. RDF/XML output is deferred and is not offered.\n\n### Built-in CSS classes and IDs\n\nThe wiki builder generates these selectors in the rendered page content:\n\n| Selector | Where |\n| --------------------------- | ------------------------------------------------------------------------------------------------- |\n| `#article-top` | Read-view `<article>` wrapper around rendered markdown body. |\n| `#firstHeading` | Read-view page title `<h1>`; also Talk / Source / Metadata pane headings. TOC “(Top)” links here. |\n| `#siteSub` | Subtitle under Talk / Source / Metadata pane headings. |\n| `article` | Wrapper around the rendered markdown body (`#article-top`). |\n| `.layout-label` | Uppercase type or custom-layout badge in read view. |\n| `.toc` / `#toc` | Table of contents container. |\n| `#catlinks` / `.catlinks` | Category links box. |\n| `.backlinks` / `#backlinks` | Backlinks section. |\n| `.catlinks-label` | Categories heading label. |\n| `.catlinks-list` | Categories `<ul>`. |\n| `.infobox` | Typed frontmatter property table. |\n| `.page-meta` | Infobox class (used for styling). |\n| `.template-SLUG` | Per-template class on infobox (e.g. `template-person`). |\n| `toclevel-N` / `lN` | TOC list item classes for heading level N. |\n| `.wikilink` | Internal wiki page links. |\n| `pre[data-copy]` | Block code with raw source for clipboard copy. |\n| `.code-block` | Wrapper injected around copyable pre blocks. |\n| `.code-copy-btn` | Copy button shown on code-block hover/focus. |\n\n### JavaScript hooks\n\nCustom layout files can utilize standard JavaScript hooks or customize their own. In premium layouts (such as template repositories), the following JavaScript features can be implemented:\n\n| Function | Purpose |\n| ------------------------------ | ---------------------------------------------------- |\n| `switchTab(viewName)` | Switch between read / talk / source / metadata tabs. |\n| `loadTalkNotes()` | Load per-page local-storage notes. |\n| `saveTalkNotes()` | Save per-page notes to localStorage. |\n| `clearTalkNotes()` | Clear per-page notes. |\n| `copySourceCode()` | Copy markdown source to clipboard. |\n| `copyPreContent()` | Copy a `pre[data-copy]` block to clipboard. |\n| `initCodeCopyButtons()` | Wrap copyable pre blocks and inject copy buttons. |\n| `toggleToc()` | Show/hide table of contents. |\n| `goToRandomArticle()` | Navigate to a random page. |\n| `triggerSearch()` | Execute search and navigate to first match. |\n| `onSearchInput(e)` | Live search suggestions. |\n| `handleSearchKey(e)` | Keyboard navigation for search suggestions. |\n| `navigateSearch(slug)` | Navigate to a search result. |\n| `applyCategoryFilterFromUrl()` | Filter index page by `?category=` URL parameter. |\n\nIf the configured page layout file does not exist, the packaged minimal `index.html` layout is used silently — no error.\n\n## Filename conventions\n\nThe CLI does not hard-code kebab-case. Projects choose a convention with **`wiki.filename_pattern`**, matched against the **full filename** (including `.md`) on markdown files only.\n\n**Wikipedia-style (recommended):** preserved capitalization and underscores — `Gregory_Davidson.md`, `Pokemon_Diamond_(copy_1).md`, `LLM_Wiki_CLI.md`. Use a pattern such as:\n\n```yaml\nwiki:\n filename_pattern: \"[A-Za-z0-9_()-]+\\\\.md\"\n```\n\n**Kebab-case (optional):** if you prefer `gregory-house.md`, set an explicit pattern (for example `[a-z0-9-]+\\\\.md`) and enforce it via `lint.filename_pattern`. Wikipedia-style and kebab-case should not be mixed in one wiki.\n\nPage routes keep the casing from the filename; GitHub Pages URLs are case-sensitive.\n\n`wiki link --fix-broken` preserves the existing link kind in each file; only `--apply` uses `link.style`.\n\nWhen `link.style` is `standard`, `lint.link_style` (default `warning`) flags Obsidian wikilinks (`[[Page]]`) in body prose. Set `lint.link_style: off` to allow wikilinks while keeping standard links as the apply format, or set `link.style: wikilink` for an Obsidian-style wiki.\n\n## Formatting (`fmt`)\n\n`wiki fmt` uses native Deno/dprint options under an inline `fmt:` mapping. The accepted options, defaults, and removed mdformat/TOML behavior are documented in [wiki fmt](wiki_fmt.md).\n\n## Integrity checks (`check`)\n\nUnder `check`, each rule is `error`, `warning`, or `off`:\n\n| Rule key | Default | What it audits |\n| --------------------- | --------- | ------------------------------------------------------------------------------------------ |\n| `missing_layout_file` | `error` | `wazoo:layout` paths that do not resolve to a readable `.html` file |\n| `frontmatter_schema` | `error` | Frontmatter that fails JSON Schema validation |\n| `missing_schema_ref` | `error` | `wazoo:jsonSchema` paths or URLs that cannot be loaded |\n| `shape_definition` | `error` | Ill-formed SHACL shape pages (see [wiki check](wiki_check.md#shape-definitions)) |\n| `shape_unused` | `warning` | Node shape pages that validate nothing (see [wiki check](wiki_check.md#shape-definitions)) |\n| `remote_schema_refs` | `allow` | Policy for remote `http(s)` schema refs: `allow`, `deny`, or `allowlist` |\n| `remote_schema_hosts` | `[]` | Hostnames permitted when `remote_schema_refs` is `allowlist` |\n\nBuild-safety rules (unsafe URL characters, spaces in routes) and output URL collision detection always apply regardless of `check` settings.\n\n### JSON Schema frontmatter (`wazoo:jsonSchema`)\n\n`wiki check` validates frontmatter against JSON Schema in parallel with SHACL. Bind schemas on shape documents with **`wazoo:jsonSchema`** beside **`sh:targetClass`**; every page whose effective `type` matches that class must pass the bound schema(s). Individual pages may append extra schemas with their own `wazoo:jsonSchema` key (scalar or YAML list). Schema refs are local paths under the wiki config root (`.json` only) or remote `http(s)` URLs. Remote refs can trigger outbound network requests; set `check.remote_schema_refs: deny` in CI over untrusted wikis, or `allowlist` with `check.remote_schema_hosts` for trusted hosts only.\n\nShape binding documents are not validated as instances — only their schema refs are checked for loadability. Authoring detail: [SHACL](SHACL.md), [Style Guide](Style_Guide.md).\n\n## Convention audits (`lint`)\n\nUnder `lint`, each rule is `error`, `warning`, or `off`:\n\n| Rule key | Default | What it audits |\n| ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `broken_links` | `warning` | Wikilinks, internal markdown links, heading fragments, assets, `wiki:` CURIEs |\n| `filename_pattern` | `warning` | Full filename vs `wiki.filename_pattern` regex |\n| `headings` | `off` | ATX `#` headings only (no Setext underlines), sentence-case H2+, H1 title case conventional, numbered headings |\n| `thematic_breaks` | `off` | Horizontal rules (`---`, `***`, `___`) in body prose |\n| `link_style` | `warning` | Obsidian wikilinks (`[[Page]]`) in body prose when `link.style` is `standard` |\n| `redundant_frontmatter` | `off` | A `headline`, `dateCreated`, or `dateModified` that repeats the value the graph derives from the H1 or Git history; remove with [wiki fix](wiki_fix.md) |\n\n`redundant_frontmatter` is `off` by default because many wikis follow the convention of repeating the H1 as `headline`: as a default warning it would fail every such page under `lint --strict`. Turn it on once the redundant keys are removed with `wiki fix --apply`, as this wiki does in `docs/wiki.yml`.\n\n### What `broken_links` accepts\n\n`broken_links` reports a link only when its target is missing. It accepts everything CommonMark allows:\n\n- **Titled and angle-bracket destinations** — `[a](Page.md \"Title\")` and `[a](<Page.md>)` resolve like `[a](Page.md)`; `wiki file mv` keeps the title when it rewrites them.\n- **URLs with a scheme** — `https://`, `ftp://`, `obsidian://`, and `//host` are external and never checked.\n- **Site-root-relative links** — `[a](/wiki/Guides/Setup/)` is resolved against `site.base_url` and `site.url_style` and checked against the page that route maps to. A missing route or heading is still reported; a link outside `site.base_url`, or to a non-page file, is checked as before.\n- **`#top`** — scrolls to the top of the page and needs no matching heading.\n- **Fenced and commented-out links** — links inside backtick or `~~~` fences and HTML comments are skipped.\n\n## This repository\n\n`docs/wiki.yml` is the dogfood wiki config for this repository. It follows the same block order as the packaged scaffold, but with project-specific overrides — `graph.context.wiki` for GitHub Pages and `graph.content_predicate: schema:articleBody` for SPARQL full-text.\n\n## Related\n\n- [wiki](wiki.md#global-options) — `-c` and `--input` global options\n- [wiki init](wiki_init.md) — scaffold a new wiki project\n- [wiki check](wiki_check.md) — integrity checks\n- [wiki lint](wiki_lint.md) — convention audits\n- [wiki query](wiki_query.md) — ad-hoc SPARQL\n- [wiki render](wiki_render.md) — inline SPARQL tables\n- [wiki serve](wiki_serve.md#sparql-endpoint) — `#serve-api` config block\n- [Graph Cache](Graph_Cache.md) — `--cache` and graph reuse\n- [Style Guide](Style_Guide.md) — shapes and frontmatter";
schema:headline "Wiki Configuration";
schema:dateCreated "2026-10-31T23:19:03Z"^^xsd:dateTime;
schema:dateModified "2026-10-31T23:19:03Z"^^xsd:dateTime.
<https://wazootech.github.io/wiki/Wiki_Configuration> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://schema.org/TechArticle> .
<https://wazootech.github.io/wiki/Wiki_Configuration> <https://schema.org/description> "Reference for wiki.yaml, wiki.yml, and wiki.json (Config)." .
<https://wazootech.github.io/wiki/Wiki_Configuration> <https://schema.org/articleBody> "# Wiki Configuration\n\nThe CLI loads **Config** from `wiki.yml`, `wiki.yaml`, or `wiki.json` in the working directory (or from `-c path`).\n\nThe in-memory **Config** model uses the same nested blocks as the file (`wiki`, `graph`, `site`, `link`, `check`, `lint`, `fmt`, `sparql_service`). There is no separate flat runtime shape. `Config.load()` validates the file, injects `config_root` (the directory containing the config file), and resolves relative paths under `wiki` and `site`. Library and test code can construct configs with `Config(wiki={...}, config_root=path)` or `Config.for_root(path, wiki={...})`.\n\nConfig files are validated strictly by the TypeScript schema in [`src/wiki/schemas/wiki_config.ts`](https://github.com/wazootech/wiki/blob/main/src/wiki/schemas/wiki_config.ts), which forbids extra keys on every block. Unknown keys, removed aliases, wrong nested keys under `check`, `lint`, or `sparql_service`, invalid syntax, or a non-mapping top level all fail immediately instead of being ignored. An unknown key is reported by name against the accepted surface; the engine does not guess which key you meant.\n\nJSON configs may use `graph.context` or `graph.@context` for prefix maps (JSON-LD compatible).\n\n## Overview\n\n### Terminology\n\n| Label | Meaning |\n| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Schema optional** | Key or block may be omitted; the schema applies a default. No yaml key is strictly required for `Config.load()` to succeed. |\n| **Init** | Written by `wiki init` ([`wiki.yml`](https://github.com/wazootech/wiki/blob/main/src/wiki/templates/wiki.yml)); omitting an Init key is the same as the schema default. |\n| **Recommended** | Not enforced by schema, but you typically set it for a real wiki (for example `graph.context.wiki`, `wiki.filename_pattern`, `site.layout`). |\n| **Always on** | Behavior not gated by yaml severities (route safety, URL collisions, built-in RDF prefixes). |\n\n### Audit lanes\n\nThree audit lanes map to three commands:\n\n| Lane | Command | YAML block | Purpose |\n| ---------- | ------------ | ---------- | ------------------------------------------------------------------------------------------------------ |\n| Integrity | `wiki check` | `check:` | SHACL, JSON Schema frontmatter, layout file existence |\n| Convention | `wiki lint` | `lint:` | Links, filename pattern severity, headings, link style in prose |\n| Formatting | `wiki fmt` | `fmt:` | Mechanical Markdown via the Deno formatter's native `textWrap`, `lineWidth`, and `newLineKind` options |\n\n**Rule placement:** Mechanical markdown belongs under **`fmt:`**. Wiki policy and link conventions belong under **`lint:`**. SHACL, JSON Schema, and layout keys belong under **`check:`** — never under `lint:`. See [Style Guide](Style_Guide.md) for the full matrix.\n\n- Putting a regex under `check.filename_pattern` fails at load with a hint.\n- `check.filename_pattern` and `check.headings` fail at load — use `lint.filename_pattern` and `lint.headings`.\n\nRelative **`--input`** paths on the CLI resolve against the config file directory (same as paths in yaml), not the shell cwd.\n\n### Blocks\n\nTop-level blocks follow a **compile pipeline** plus **audit lanes**, not arbitrary grouping. `wiki init` and [docs/wiki.yml](https://github.com/wazootech/wiki/blob/main/docs/wiki.yml) use the same order as the packaged scaffold [`wiki.yml`](https://github.com/wazootech/wiki/blob/main/src/wiki/templates/wiki.yml).\n\n| Block | Role | Command(s) | Schema | Init scaffold |\n| ----------------- | ----------------------------------------------------- | --------------------------------- | -------- | ----------------- |\n| `wiki:` | Corpus on disk — inputs, assets, filename regex | `check`, `lint`, `build`, `serve` | optional | yes |\n| `graph:` | RDF compile — prefixes, document IRIs, body literals | `check`, `query`, `render` | optional | yes |\n| `site:` | Publish routing — layout path, URL prefix, path style | `build`, `serve` | optional | yes |\n| `link:` | `wiki link` apply format and rename repair map | `wiki link` | optional | yes |\n| `check:` | Integrity severities | `wiki check` | optional | yes |\n| `lint:` | Convention severities | `wiki lint` | optional | yes |\n| `sources:` | External data sources (git repos) | `wiki install`, `wiki remove` | optional | commented example |\n| `sparql_service:` | Opt-in SPARQL HTTP on `wiki serve` | `wiki serve` | optional | commented example |\n| `fmt:` | Mechanical Markdown via the Deno formatter | `wiki fmt` | optional | inline mapping |\n\n**Order in the file:** source and semantics first (`wiki`, `graph`), then publish and authoring (`site`, `link`), then severity tables (`check`, `lint`), optional serve (`sparql_service`), then `fmt` last.\n\n**Split keys** — policy lives in one block, severity or tooling in another:\n\n- **`wiki.filename_pattern`** — the regex string. **`lint.filename_pattern`** — how strictly to flag violations (`error`, `warning`, or `off`).\n- **`link.style`** — what `wiki link --apply` inserts (`standard` page links or `wikilink`). **`lint.link_style`** — whether Obsidian `[[wikilinks]]` in body prose are flagged when `link.style` is `standard`. `style` also still accepts the retired spellings `markdown` and `obsidian`, with a deprecation warning (see `link:` settings below).\n\nFor why `check`, `lint`, `fmt`, and `wiki link` are separate commands, see [Design philosophies](Design_Philosophies.md#check-lint-fmt-and-link).\n\n### Always on\n\nThese apply regardless of yaml severities:\n\n- **Route safety** — unsafe URL characters and spaces in routes (`wiki check`).\n- **Output URL collisions** — duplicate built routes (`wiki check`).\n- **SHACL** — when shape documents exist in the corpus (`wiki check`).\n- **Built-in RDF prefixes** — `schema`, `wiki`, `foaf`, `rdf`, `rdfs`, `xsd`, `owl`, `dc`, `dcterms`, `sh`, `wazoo` are always merged at runtime; yaml `graph.context` entries override or add.\n\n## Wiki (`wiki:`)\n\n```yaml\nwiki: # optional block\n input: [wiki] # default [wiki]; init writes\n assets: [assets] # default [assets] if assets/ exists, else []; init omits\n exclude: [] # default []; init omits\n filename_pattern: \"[A-Za-z0-9_()-]+\\\\.md\" # no default; recommended; init writes\n allow_unknown_keys: false # default false; init omits\n```\n\n| Key | Required | Default | Init | Audited by |\n| -------------------- | ---------------------- | ------------------------------------------- | ------ | ------------------------------------------ |\n| `input` | optional | `[wiki]` | writes | indexing (`build`, `check`, `lint`, `fmt`) |\n| `assets` | optional | `[assets]` when `assets/` exists, else `[]` | omits | `wiki build` (static copy) |\n| `exclude` | optional | `[]` | omits | indexing (skipped paths) |\n| `filename_pattern` | optional (recommended) | unset — no regex check until set | writes | `wiki lint` (`lint.filename_pattern`) |\n| `allow_unknown_keys` | optional | `false` | omits | config load |\n\nPage URLs come from paths under `wiki.input`: `wiki/Alice.md` → `/wiki/Alice/` with default `site.base_url` and `site.url_style: dir`. `index.md` in a folder owns that folder’s route (for example `wiki/index.md` → `/wiki/`).\n\nSee [Filename conventions](#filename-conventions) for regex patterns.\n\nUnknown top-level keys fail at load, so a typo such as `lnit:` is caught. Set `wiki.allow_unknown_keys: true` to accept them instead. Unknown keys inside a wiki block (`site:`, `lint:`, ...) are still rejected.\n\n## Graph (`graph:`)\n\nRDF and document URI settings for graph build, `wiki query`, microdata, and SHACL.\n\n```yaml\ngraph: # optional block\n # base_iri: unset → graph.context.wiki → https://wiki.example.org/\n content_predicate: schema:articleBody # unset by default; init writes when flagged\n include_file_extension: false # default false; init omits (commented)\n implicit_types: [] # default []; init omits (commented)\n implicit_types_policy: fallback # default fallback; init omits (commented)\n context: # merges with built-in prefixes; init writes\n schema: https://schema.org/\n wiki: https://example.org/wiki/ # recommended\n wazoo: https://schema.wazoo.dev/\n foaf: http://xmlns.com/foaf/0.1/\n dc: http://purl.org/dc/elements/1.1/\n dcterms: http://purl.org/dc/terms/\n sh: http://www.w3.org/ns/shacl#\n xsd: http://www.w3.org/2001/XMLSchema#\n```\n\n| Key | Required | Default | Init | Audited by |\n| ------------------------ | ------------------------------ | ---------------------------------------------------------- | --------------------------------------- | ------------------------------------------------- |\n| `base_iri` | optional | unset → `graph.context.wiki` → `https://wiki.example.org/` | commented example | document IRIs, `wiki query` |\n| `context` / `@context` | optional (recommended: `wiki`) | built-in prefixes only when unset | writes extended map | CURIE expansion, SHACL, microdata |\n| `content_predicate` | optional | unset — no body literals in graph | writes when `--graph-content-predicate` | SPARQL full-text |\n| `include_file_extension` | optional | `false` | omits (commented) | document URI generation |\n| `implicit_types` | optional | `[]` | omits (commented) | default `rdf:type` on untyped pages |\n| `implicit_types_policy` | optional | `fallback` | omits (commented) | `fallback` or `append` (SHACL shapes skip append) |\n\nWhen `implicit_types_policy` is `append`, frontmatter types are unioned with `implicit_types` (deduped by resolved URI).\n\n## Site (`site:`)\n\nDefault page layout and routing for `wiki build` / `wiki serve`. Branding and chrome → [Page layout](#page-layout).\n\n```yaml\nsite: # optional block\n layout: index.html # unset → built-in minimal fallback layout\n base_url: /wiki # default /wiki; init writes\n url_style: dir # default dir; init writes\n```\n\n| Key | Required | Default | Init | Audited by |\n| ----------- | ---------------------- | ------------------------------------- | ------ | ----------------------------------------------------------------------------------- |\n| `layout` | optional (recommended) | unset — packaged minimal `index.html` | writes | `wiki build`, `wiki serve`; `check.missing_layout_file` for per-page `wazoo:layout` |\n| `base_url` | optional | `/wiki` (`\"\"` allowed for site root) | writes | routes, layout `%wiki.base_url%` |\n| `url_style` | optional | `dir` (`file` → `slug.html`) | writes | output paths; overridable per CLI run |\n\n`site:` does not carry site name, theme color, favicon, or sidebar logo. If you want custom styling, write a custom layout template file and place custom assets under the `wiki.assets` directory, then configure `site.layout` to point to it.\n\nCLI flags on `wiki build` and `wiki serve` can override `site.base_url` and `site.url_style` for a single run.\n\n## Link (`link:`)\n\nSettings for the `wiki link` command family (separate from `lint.link_style` severity).\n\n```yaml\nlink: # optional block\n style: standard # default standard; init writes\n renames: {} # default {}; init omits (commented example)\n```\n\n| Key | Required | Default | Init | Audited by |\n| --------- | -------- | ------------------------------------- | ----------------- | ------------------------ |\n| `style` | optional | `standard` (`wikilink` for wikilinks) | writes | `wiki link --apply` only |\n| `renames` | optional | `{}` | commented example | `wiki link --fix-broken` |\n\n`wiki link --fix-broken` preserves the existing link kind in each file; only `--apply` uses `link.style`.\n\n**Retired spellings.** `markdown` and `obsidian` are still accepted as values for `style`, and `wiki init --link-style` accepts them too. Each prints a deprecation warning and rewrites the value to `standard` or `wikilink`:\n\n```text\nlink.style: 'obsidian' is deprecated, use 'wikilink' instead (edit config file link.style and re-run)\n```\n\nThey are accepted but never advertised: an invalid `--link-style` value lists only `standard` and `wikilink`. Rename the value in your config file to silence the warning.\n\n## Integrity checks (`check:`)\n\nUnder `check`, each rule is `error`, `warning`, or `off`:\n\n```yaml\ncheck: # optional block\n missing_layout_file: error # default error; init writes\n frontmatter_schema: error # default error; init writes\n missing_schema_ref: error # default error; init writes\n shape_definition: error # default error\n shape_unused: warning # default warning\n```\n\n| Key | Required | Default | Init | Audited by |\n| --------------------- | -------- | --------- | ------ | ------------------------------------ |\n| `missing_layout_file` | optional | `error` | writes | `wazoo:layout` paths missing on disk |\n| `frontmatter_schema` | optional | `error` | writes | JSON Schema validation failures |\n| `missing_schema_ref` | optional | `error` | writes | unloadable `wazoo:jsonSchema` refs |\n| `shape_definition` | optional | `error` | — | ill-formed SHACL shape pages |\n| `shape_unused` | optional | `warning` | — | node shapes that validate nothing |\n\nBuild-safety rules (unsafe URL characters, spaces in routes) and output URL collision detection always apply regardless of `check` settings.\n\n### JSON Schema frontmatter (`wazoo:jsonSchema`)\n\n`wiki check` validates frontmatter against JSON Schema in parallel with SHACL. Bind schemas on shape documents with **`wazoo:jsonSchema`** beside **`sh:targetClass`**; every page whose effective `type` matches that class must pass the bound schema(s). Individual pages may append extra schemas with their own `wazoo:jsonSchema` key (scalar or YAML list). Schema refs are local paths under the wiki config root (`.json` only) or remote `http(s)` URLs.\n\nShape binding documents are not validated as instances — only their schema refs are checked for loadability. Authoring detail: [SHACL](SHACL.md), [Style Guide](Style_Guide.md).\n\n## Convention audits (`lint:`)\n\nUnder `lint`, each rule is `error`, `warning`, or `off`:\n\n```yaml\nlint: # optional block\n broken_links: warning # default warning; init writes\n filename_pattern: warning # default warning; init writes\n headings: off # default off; init omits\n heading_levels: off # default off; init omits\n duplicate_headings: off # default off; init omits\n thematic_breaks: off # default off; init omits\n link_style: warning # default warning; init writes\n redundant_frontmatter: off # default off; init omits\n```\n\n| Key | Required | Default | Init | Audited by |\n| ----------------------- | -------- | --------- | ------ | --------------------------------------------------------------------------------- |\n| `broken_links` | optional | `warning` | writes | wikilinks, markdown links, fragments, assets, `wiki:` CURIEs |\n| `filename_pattern` | optional | `warning` | writes | full filename vs `wiki.filename_pattern` |\n| `headings` | optional | `off` | omits | ATX syntax, sentence-case H2+, numbered headings |\n| `heading_levels` | optional | `off` | omits | heading level gaps (for example H1 then H3) |\n| `duplicate_headings` | optional | `off` | omits | duplicate heading text on one page |\n| `thematic_breaks` | optional | `off` | omits | horizontal rules in body prose |\n| `link_style` | optional | `warning` | writes | Obsidian `[[wikilinks]]` when `link.style` is `standard` |\n| `redundant_frontmatter` | optional | `off` | omits | frontmatter that repeats a derived headline or Git date ([wiki fix](wiki_fix.md)) |\n\nATX heading syntax is also enforced by **`wiki fmt`**, the Deno Markdown formatter; Setext underlines are converted on format.\n\nWhen `link.style` is `standard`, set `lint.link_style: off` to allow wikilinks in prose, or set `link.style: wikilink` for an Obsidian-style wiki.\n\n## External data sources (`sources:`)\n\n<!-- wiki:anchor external-data-sources-sources -->\n\nDeclare external git repositories that contribute wiki pages or RDF data to the graph. After adding a source, run `wiki install` to clone it and pin the resolved commit in `wiki.lock`.\n\nSources are read-only inputs during graph construction. Wiki composes root content and installed sources into one default query view, while preserving each installed source as a stable RDF named graph for provenance and SPARQL `GRAPH` clauses.\n\n```yaml\nsources: # optional block\n - name: solar-system\n type: git\n url: https://github.com/EthanThatOneKid/solar-system-wiki.git\n ref: v0.1.0 # optional — branch, tag, or commit\n path: wiki # optional — subdirectory within the repo\n```\n\n| Key | Required | Default | Init | Command(s) |\n| ------ | -------- | --------- | ----------------- | -------------- |\n| `name` | required | — | omits (commented) | `wiki install` |\n| `type` | required | `git` | omits (commented) | `wiki install` |\n| `url` | required | — | omits (commented) | `wiki install` |\n| `ref` | optional | `HEAD` | omits (commented) | `wiki install` |\n| `path` | optional | repo root | omits (commented) | `wiki install` |\n\nEach source must have a unique `name`. The `type` field is currently limited to `git`. Unknown keys and unsupported types are rejected at config load time.\n\nRun `wiki install` to fetch all declared sources and write `wiki.lock`. Check `wiki.lock` into version control for reproducible builds. The resolved source paths are automatically appended to `wiki.input` so the existing graph, check, and build pipeline picks them up.\n\nUse `wiki graph list` to inspect the root graph and installed source graph URIs. Source graph URIs are derived from `graph.context.wiki`:\n\n- Root corpus: `{graph.context.wiki}graphs/root`\n- Installed source: `{graph.context.wiki}graphs/source/{source-name}`\n\nRequested refs, resolved commits, source URLs, cache paths, and direct/transitive dependency metadata remain source metadata; they are not embedded in graph URIs.\n\n**Transitive dependencies** are resolved recursively. After cloning each source, `wiki install` reads the source's own `wiki.yml` (or `wiki.yaml`/`wiki.json`) to discover its `sources:` block. Those transitive sources are fetched and locked too, forming a dependency tree. Circular dependency chains are detected and reported as errors. If two sources declare the same dependency name with different URLs or refs, install fails with a conflict error.\n\nWhen a source is removed with `wiki remove`, transitive sources that are no longer needed by any remaining top-level source are automatically cleaned up (cache and lockfile entry removed).\n\nAfter `wiki update`, newly declared transitive sources are installed, and orphaned sources are reported (but not auto-removed — run `wiki remove` to clean up).\n\nThe `.wiki/` source cache directory is not committed — `wiki init` scaffolds a `.gitignore` that excludes it (alongside the `_site/` build output).\n\nTo add a source without editing the config file by hand:\n\n```bash\nwiki install https://github.com/EthanThatOneKid/solar-system-wiki.git\n# GitHub shorthand also works:\nwiki install EthanThatOneKid/solar-system-wiki\n```\n\nThe name is inferred from the URL (`solar-system`). To remove it:\n\n```bash\nwiki remove solar-system\n```\n\nSee [wiki install](wiki_install.md) and [wiki remove](wiki_remove.md).\n\n### Contributing changes to a source\n\nAn installed source is a read-only input. To change one, change its upstream repository and pull the result back in; never edit the installed copy.\n\n- **Local resolution** (`wiki install`) is a cache: a shallow clone under `.wiki/sources/<name>/repo/`, pinned by `wiki.lock`. It is not committed and is not a place to author.\n- **Vendoring** (copying the pages into your own repository) makes them yours: they are then ordinary root pages and no longer track upstream. Wiki has no vendoring command or config yet ([#150](https://github.com/wazootech/wiki/issues/150)); copy the files and remove the source with `wiki remove`.\n- **Upstream contribution** keeps the source a dependency and sends the change to its owner:\n\n1. Clone the source's repository normally, outside `.wiki/`, and branch (fork it first when you cannot push). It is a wiki in its own right, so use its `wiki file` verbs and its own checks there.\n2. Open a pull request upstream.\n3. Until it merges, point your wiki at the branch: set the source's `url` to your fork (if you forked) and `ref` to the branch, then run `wiki update <name>`. This moves the `wiki.lock` entry to the branch's head.\n4. After it merges, set `url` and `ref` back and run `wiki update <name>` again. Commit `wiki.yml` and `wiki.lock`.\n\nTo follow upstream without contributing, run `wiki update` (or `wiki update <name>`); `wiki update --dry-run` shows what would move.\n\nDo not edit files in `.wiki/sources/`. The edit verbs (`wiki file set`, `patch`, `mv`, `rm`, and `wiki edit`) refuse any path under `.wiki/`. A hand edit there survives `wiki install`, stays uncommitted, and is not in `wiki.lock`, so nobody else sees it. It also breaks `wiki update`: when upstream changes the same file, the update fails with git's \"local changes would be overwritten\" error until you discard the edit (`git -C .wiki/sources/<name>/repo checkout -- .`).\n\nSPARQL Update and in-place writes to sources are not supported; see [Recursive Semantic Datasets](Recursive_Semantic_Datasets.md).\n\nFor the product framing behind recursive source composition, see [Recursive Semantic Datasets](Recursive_Semantic_Datasets.md). For what happens when a source describes the same entity as your root wiki, see [Cross-Wiki Identity](Cross_Wiki_Identity.md).\n\n## Serve API\n\nOpt-in read-only SPARQL HTTP endpoint on `wiki serve`:\n\n```yaml\nsparql_service: # optional block\n enabled: false # default false; init omits (commented)\n path: /api/sparql # default /api/sparql; init omits (commented)\n```\n\n| Key | Required | Default | Init | Audited by |\n| --------- | -------- | ------------- | ----------------- | ---------------------------- |\n| `enabled` | optional | `false` | commented example | `wiki serve` SPARQL endpoint |\n| `path` | optional | `/api/sparql` | commented example | reserved route on serve |\n\n`sparql_service.enabled` accepts YAML booleans and normalizes common string forms such as `true`, `false`, `on`, `off`, `yes`, `no`, `1`, and `0`; prefer native YAML booleans.\n\nExample when enabled:\n\n```yaml\nsparql_service:\n enabled: true\n path: /api/sparql\n```\n\nThe endpoint reuses the same SPARQL engine as `wiki query`. It is read-only and intended for local or development-oriented use. HTTP request forms, supported query types, and `Accept` negotiation are documented in [wiki serve](wiki_serve.md#sparql-endpoint).\n\nIt is **opt-in by default** because enabling it exposes raw graph-query access in addition to HTML preview.\n\n`sparql_service.path` must not collide with the effective `site.base_url` page routes or the watch endpoint. Invalid values such as `/`, `/wiki`, `/wiki/foo`, or `/wiki/__watch` are rejected when `wiki serve` starts.\n\n## Formatting (`fmt`)\n\nTop-level **`fmt`** configures Wiki's in-process `dprint-plugin-markdown` formatter. The inline mapping uses native Deno/dprint option names:\n\n```yaml\nfmt:\n textWrap: never\n lineWidth: 80\n newLineKind: lf\n```\n\n| Option | Values | Default | Effect |\n| ------------- | ----------------------------- | ------- | ------------------------------------------------------------------------ |\n| `textWrap` | `always`, `maintain`, `never` | `never` | Whether prose wraps to the configured width or preserves/avoids wrapping |\n| `lineWidth` | Positive integer | `80` | Target width when `textWrap` is `always` |\n| `newLineKind` | `auto`, `crlf`, `lf` | `lf` | Line ending emitted by the formatter |\n\nOnly an inline mapping is supported. TOML pointers, `.mdformat.toml` discovery, and mdformat-only keys such as `wrap`, `end_of_line`, and `extensions` are not supported. Existing values must be removed or rewritten using the native options above. Omitting `fmt` or using `fmt: {}` selects the Wiki CLI defaults. See [wiki fmt](wiki_fmt.md) for details.\n\n## Page layout\n\nWhen `site.layout` is set, the CLI renders every page through that page layout (`.html`). Per-page overrides use `wazoo:layout` in frontmatter; see [Wiki Page Layouts](Wiki_Page_Layouts.md).\n\n### Layout strategy\n\nThe first-class presentation contract in this repository is layout files referenced from `site.layout` (for example `index.html`).\n\n- The [wiki](wiki.md) owns the semantic markdown-to-HTML pipeline and layout slot contract.\n- Wiki page layout files are the primary built-in extension point for presentation.\n- Advanced themes or framework-specific sites such as Next.js, Mintlify, or other external docs stacks are treated as downstream integrations or separate layout/template repositories.\n\n### Minimal fallback\n\nWithout a configured layout file (or when the path is missing), every page is rendered with the built-in minimal fallback layout (`index.html`), which outputs plain, unstyled HTML containing only `<h1>` and content. It does not link any default CSS or assets and does not include a sidebar, tabs, infobox, table of contents, backlinks, or categories out-of-the-box.\n\n### Layout slots\n\nLayout files use `%wiki.*%` slot substitution (not Jinja). On each page render, the CLI builds a slot map from the current page context and replaces every known slot in your layout file. Unknown `%wiki.*%` spellings are left unchanged.\n\nLayout settings and the supported slots are documented in [Wiki Page Layouts](Wiki_Page_Layouts.md).\n\nCanonical slot list (3 slots):\n\n| Slot | Source | Substitution |\n| ----------------- | ---------------------- | ------------------------------------------------------------- |\n| `%wiki.base_url%` | `site.base_url` | HTML-escaped text (`/wiki`, or `\"\"` for site root) |\n| `%wiki.head%` | built per page | `<title>{page title} - Wiki CLI</title>` (title HTML-escaped) |\n| `%wiki.body%` | rendered markdown body | Pre-built HTML (not escaped) |\n\n**Packaged layouts**\n\n| File | When used | Typical slots |\n| ------------ | ----------------------------------- | ---------------------------- |\n| `index.html` | `site.layout` unset or missing file | `%wiki.head%`, `%wiki.body%` |\n\nExample excerpt (`index.html`):\n\n```html\n<!DOCTYPE html>\n<html lang=en>\n <head>\n<meta charset=UTF-8>\n<meta name=viewport content=width=device-width,initial-scale=1.0>\n%wiki.head%\n </head>\n <body>\n%wiki.body%\n </body>\n</html>\n```\n\n### Custom CSS\n\nThe Wiki CLI does not copy or link a default stylesheet out-of-the-box. To add styling to your pages:\n\n1. **Edit the layout file** — set `site.layout` in `wiki.yml` to a custom layout file. Link stylesheets in `<head>`, or write inline styles.\n1. **Link wiki assets** — place `.css` files under a directory listed in `wiki.assets`, then reference them from the layout, for example `<link rel=\"stylesheet\" href=\"%wiki.base_url%/assets/site.css\">`. Built assets are served at `%wiki.base_url%/assets/…` during `wiki serve` and copied into the build output.\n\n### Custom logos and icons\n\nTo customize site logos, icons, favicons, or touch icons:\n\n1. Place your asset files (such as `logo.svg`, `logo.png`, `favicon.ico`) under a directory listed in `wiki.assets`.\n1. Reference the assets from your custom layout file, for example:\n\n```html\n<img src=\"%wiki.base_url%/assets/logo.svg\" alt=\"\" width=\"80\" height=\"80\">\n```\n\nYou can also add `<link rel=\"icon\">`, `<link rel=\"apple-touch-icon\">`, or other `<head>` tags directly in your custom layout file.\n\nBuilt assets are served at `%wiki.base_url%/assets/…` during `wiki serve` and copied into the build output.\n\nSee also [Wiki Page Layouts](Wiki_Page_Layouts.md) for `site.layout`, `wazoo:layout`, and packaged layout files.\n\nThe metadata pane uses the same RDF serialization path as `wiki export` (compacted JSON-LD, Turtle, N3, N-Triples, TriG, and N-Quads). A compact **Format** chip row switches views without JavaScript. In `wiki serve`, set the initial chip with `?metadata_format=FORMAT` (for example `turtle` or `json-ld`). In `wiki build`, all supported format views are embedded in the page HTML so the picker works offline. RDF/XML output is deferred and is not offered.\n\n### Built-in CSS classes and IDs\n\nThe wiki builder generates these selectors in the rendered page content:\n\n| Selector | Where |\n| --------------------------- | ------------------------------------------------------------------------------------------------- |\n| `#article-top` | Read-view `<article>` wrapper around rendered markdown body. |\n| `#firstHeading` | Read-view page title `<h1>`; also Talk / Source / Metadata pane headings. TOC “(Top)” links here. |\n| `#siteSub` | Subtitle under Talk / Source / Metadata pane headings. |\n| `article` | Wrapper around the rendered markdown body (`#article-top`). |\n| `.layout-label` | Uppercase type or custom-layout badge in read view. |\n| `.toc` / `#toc` | Table of contents container. |\n| `#catlinks` / `.catlinks` | Category links box. |\n| `.backlinks` / `#backlinks` | Backlinks section. |\n| `.catlinks-label` | Categories heading label. |\n| `.catlinks-list` | Categories `<ul>`. |\n| `.infobox` | Typed frontmatter property table. |\n| `.page-meta` | Infobox class (used for styling). |\n| `.template-SLUG` | Per-template class on infobox (e.g. `template-person`). |\n| `toclevel-N` / `lN` | TOC list item classes for heading level N. |\n| `.wikilink` | Internal wiki page links. |\n| `pre[data-copy]` | Block code with raw source for clipboard copy. |\n| `.code-block` | Wrapper injected around copyable pre blocks. |\n| `.code-copy-btn` | Copy button shown on code-block hover/focus. |\n\n### JavaScript hooks\n\nCustom layout files can utilize standard JavaScript hooks or customize their own. In premium layouts (such as template repositories), the following JavaScript features can be implemented:\n\n| Function | Purpose |\n| ------------------------------ | ---------------------------------------------------- |\n| `switchTab(viewName)` | Switch between read / talk / source / metadata tabs. |\n| `loadTalkNotes()` | Load per-page local-storage notes. |\n| `saveTalkNotes()` | Save per-page notes to localStorage. |\n| `clearTalkNotes()` | Clear per-page notes. |\n| `copySourceCode()` | Copy markdown source to clipboard. |\n| `copyPreContent()` | Copy a `pre[data-copy]` block to clipboard. |\n| `initCodeCopyButtons()` | Wrap copyable pre blocks and inject copy buttons. |\n| `toggleToc()` | Show/hide table of contents. |\n| `goToRandomArticle()` | Navigate to a random page. |\n| `triggerSearch()` | Execute search and navigate to first match. |\n| `onSearchInput(e)` | Live search suggestions. |\n| `handleSearchKey(e)` | Keyboard navigation for search suggestions. |\n| `navigateSearch(slug)` | Navigate to a search result. |\n| `applyCategoryFilterFromUrl()` | Filter index page by `?category=` URL parameter. |\n\nIf the configured page layout file does not exist, the packaged minimal `index.html` layout is used silently — no error.\n\n## Filename conventions\n\nThe CLI does not hard-code kebab-case. Projects choose a convention with **`wiki.filename_pattern`**, matched against the **full filename** (including `.md`) on markdown files only.\n\n**Wikipedia-style (recommended):** preserved capitalization and underscores — `Gregory_Davidson.md`, `Pokemon_Diamond_(copy_1).md`, `LLM_Wiki_CLI.md`. Use a pattern such as:\n\n```yaml\nwiki:\n filename_pattern: \"[A-Za-z0-9_()-]+\\\\.md\"\n```\n\n**Kebab-case (optional):** if you prefer `gregory-house.md`, set an explicit pattern (for example `[a-z0-9-]+\\\\.md`) and enforce it via `lint.filename_pattern`. Wikipedia-style and kebab-case should not be mixed in one wiki.\n\nPage routes keep the casing from the filename; GitHub Pages URLs are case-sensitive.\n\n`wiki link --fix-broken` preserves the existing link kind in each file; only `--apply` uses `link.style`.\n\nWhen `link.style` is `standard`, `lint.link_style` (default `warning`) flags Obsidian wikilinks (`[[Page]]`) in body prose. Set `lint.link_style: off` to allow wikilinks while keeping standard links as the apply format, or set `link.style: wikilink` for an Obsidian-style wiki.\n\n## Formatting (`fmt`)\n\n`wiki fmt` uses native Deno/dprint options under an inline `fmt:` mapping. The accepted options, defaults, and removed mdformat/TOML behavior are documented in [wiki fmt](wiki_fmt.md).\n\n## Integrity checks (`check`)\n\nUnder `check`, each rule is `error`, `warning`, or `off`:\n\n| Rule key | Default | What it audits |\n| --------------------- | --------- | ------------------------------------------------------------------------------------------ |\n| `missing_layout_file` | `error` | `wazoo:layout` paths that do not resolve to a readable `.html` file |\n| `frontmatter_schema` | `error` | Frontmatter that fails JSON Schema validation |\n| `missing_schema_ref` | `error` | `wazoo:jsonSchema` paths or URLs that cannot be loaded |\n| `shape_definition` | `error` | Ill-formed SHACL shape pages (see [wiki check](wiki_check.md#shape-definitions)) |\n| `shape_unused` | `warning` | Node shape pages that validate nothing (see [wiki check](wiki_check.md#shape-definitions)) |\n| `remote_schema_refs` | `allow` | Policy for remote `http(s)` schema refs: `allow`, `deny`, or `allowlist` |\n| `remote_schema_hosts` | `[]` | Hostnames permitted when `remote_schema_refs` is `allowlist` |\n\nBuild-safety rules (unsafe URL characters, spaces in routes) and output URL collision detection always apply regardless of `check` settings.\n\n### JSON Schema frontmatter (`wazoo:jsonSchema`)\n\n`wiki check` validates frontmatter against JSON Schema in parallel with SHACL. Bind schemas on shape documents with **`wazoo:jsonSchema`** beside **`sh:targetClass`**; every page whose effective `type` matches that class must pass the bound schema(s). Individual pages may append extra schemas with their own `wazoo:jsonSchema` key (scalar or YAML list). Schema refs are local paths under the wiki config root (`.json` only) or remote `http(s)` URLs. Remote refs can trigger outbound network requests; set `check.remote_schema_refs: deny` in CI over untrusted wikis, or `allowlist` with `check.remote_schema_hosts` for trusted hosts only.\n\nShape binding documents are not validated as instances — only their schema refs are checked for loadability. Authoring detail: [SHACL](SHACL.md), [Style Guide](Style_Guide.md).\n\n## Convention audits (`lint`)\n\nUnder `lint`, each rule is `error`, `warning`, or `off`:\n\n| Rule key | Default | What it audits |\n| ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `broken_links` | `warning` | Wikilinks, internal markdown links, heading fragments, assets, `wiki:` CURIEs |\n| `filename_pattern` | `warning` | Full filename vs `wiki.filename_pattern` regex |\n| `headings` | `off` | ATX `#` headings only (no Setext underlines), sentence-case H2+, H1 title case conventional, numbered headings |\n| `thematic_breaks` | `off` | Horizontal rules (`---`, `***`, `___`) in body prose |\n| `link_style` | `warning` | Obsidian wikilinks (`[[Page]]`) in body prose when `link.style` is `standard` |\n| `redundant_frontmatter` | `off` | A `headline`, `dateCreated`, or `dateModified` that repeats the value the graph derives from the H1 or Git history; remove with [wiki fix](wiki_fix.md) |\n\n`redundant_frontmatter` is `off` by default because many wikis follow the convention of repeating the H1 as `headline`: as a default warning it would fail every such page under `lint --strict`. Turn it on once the redundant keys are removed with `wiki fix --apply`, as this wiki does in `docs/wiki.yml`.\n\n### What `broken_links` accepts\n\n`broken_links` reports a link only when its target is missing. It accepts everything CommonMark allows:\n\n- **Titled and angle-bracket destinations** — `[a](Page.md \"Title\")` and `[a](<Page.md>)` resolve like `[a](Page.md)`; `wiki file mv` keeps the title when it rewrites them.\n- **URLs with a scheme** — `https://`, `ftp://`, `obsidian://`, and `//host` are external and never checked.\n- **Site-root-relative links** — `[a](/wiki/Guides/Setup/)` is resolved against `site.base_url` and `site.url_style` and checked against the page that route maps to. A missing route or heading is still reported; a link outside `site.base_url`, or to a non-page file, is checked as before.\n- **`#top`** — scrolls to the top of the page and needs no matching heading.\n- **Fenced and commented-out links** — links inside backtick or `~~~` fences and HTML comments are skipped.\n\n## This repository\n\n`docs/wiki.yml` is the dogfood wiki config for this repository. It follows the same block order as the packaged scaffold, but with project-specific overrides — `graph.context.wiki` for GitHub Pages and `graph.content_predicate: schema:articleBody` for SPARQL full-text.\n\n## Related\n\n- [wiki](wiki.md#global-options) — `-c` and `--input` global options\n- [wiki init](wiki_init.md) — scaffold a new wiki project\n- [wiki check](wiki_check.md) — integrity checks\n- [wiki lint](wiki_lint.md) — convention audits\n- [wiki query](wiki_query.md) — ad-hoc SPARQL\n- [wiki render](wiki_render.md) — inline SPARQL tables\n- [wiki serve](wiki_serve.md#sparql-endpoint) — `#serve-api` config block\n- [Graph Cache](Graph_Cache.md) — `--cache` and graph reuse\n- [Style Guide](Style_Guide.md) — shapes and frontmatter" .
<https://wazootech.github.io/wiki/Wiki_Configuration> <https://schema.org/headline> "Wiki Configuration" .
<https://wazootech.github.io/wiki/Wiki_Configuration> <https://schema.org/dateCreated> "2026-10-31T23:19:03Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .
<https://wazootech.github.io/wiki/Wiki_Configuration> <https://schema.org/dateModified> "2026-10-31T23:19:03Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .
@prefix schema: <https://schema.org/>.
@prefix wiki: <https://wazootech.github.io/wiki/>.
@prefix foaf: <http://xmlns.com/foaf/0.1/>.
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
@prefix owl: <http://www.w3.org/2002/07/owl#>.
@prefix dc: <http://purl.org/dc/elements/1.1/>.
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix sh: <http://www.w3.org/ns/shacl#>.
@prefix wazoo: <https://schema.wazoo.dev/>.
wiki:Wiki_Configuration a schema:TechArticle;
schema:description "Reference for wiki.yaml, wiki.yml, and wiki.json (Config).";
schema:articleBody "# Wiki Configuration\n\nThe CLI loads **Config** from `wiki.yml`, `wiki.yaml`, or `wiki.json` in the working directory (or from `-c path`).\n\nThe in-memory **Config** model uses the same nested blocks as the file (`wiki`, `graph`, `site`, `link`, `check`, `lint`, `fmt`, `sparql_service`). There is no separate flat runtime shape. `Config.load()` validates the file, injects `config_root` (the directory containing the config file), and resolves relative paths under `wiki` and `site`. Library and test code can construct configs with `Config(wiki={...}, config_root=path)` or `Config.for_root(path, wiki={...})`.\n\nConfig files are validated strictly by the TypeScript schema in [`src/wiki/schemas/wiki_config.ts`](https://github.com/wazootech/wiki/blob/main/src/wiki/schemas/wiki_config.ts), which forbids extra keys on every block. Unknown keys, removed aliases, wrong nested keys under `check`, `lint`, or `sparql_service`, invalid syntax, or a non-mapping top level all fail immediately instead of being ignored. An unknown key is reported by name against the accepted surface; the engine does not guess which key you meant.\n\nJSON configs may use `graph.context` or `graph.@context` for prefix maps (JSON-LD compatible).\n\n## Overview\n\n### Terminology\n\n| Label | Meaning |\n| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Schema optional** | Key or block may be omitted; the schema applies a default. No yaml key is strictly required for `Config.load()` to succeed. |\n| **Init** | Written by `wiki init` ([`wiki.yml`](https://github.com/wazootech/wiki/blob/main/src/wiki/templates/wiki.yml)); omitting an Init key is the same as the schema default. |\n| **Recommended** | Not enforced by schema, but you typically set it for a real wiki (for example `graph.context.wiki`, `wiki.filename_pattern`, `site.layout`). |\n| **Always on** | Behavior not gated by yaml severities (route safety, URL collisions, built-in RDF prefixes). |\n\n### Audit lanes\n\nThree audit lanes map to three commands:\n\n| Lane | Command | YAML block | Purpose |\n| ---------- | ------------ | ---------- | ------------------------------------------------------------------------------------------------------ |\n| Integrity | `wiki check` | `check:` | SHACL, JSON Schema frontmatter, layout file existence |\n| Convention | `wiki lint` | `lint:` | Links, filename pattern severity, headings, link style in prose |\n| Formatting | `wiki fmt` | `fmt:` | Mechanical Markdown via the Deno formatter's native `textWrap`, `lineWidth`, and `newLineKind` options |\n\n**Rule placement:** Mechanical markdown belongs under **`fmt:`**. Wiki policy and link conventions belong under **`lint:`**. SHACL, JSON Schema, and layout keys belong under **`check:`** — never under `lint:`. See [Style Guide](Style_Guide.md) for the full matrix.\n\n- Putting a regex under `check.filename_pattern` fails at load with a hint.\n- `check.filename_pattern` and `check.headings` fail at load — use `lint.filename_pattern` and `lint.headings`.\n\nRelative **`--input`** paths on the CLI resolve against the config file directory (same as paths in yaml), not the shell cwd.\n\n### Blocks\n\nTop-level blocks follow a **compile pipeline** plus **audit lanes**, not arbitrary grouping. `wiki init` and [docs/wiki.yml](https://github.com/wazootech/wiki/blob/main/docs/wiki.yml) use the same order as the packaged scaffold [`wiki.yml`](https://github.com/wazootech/wiki/blob/main/src/wiki/templates/wiki.yml).\n\n| Block | Role | Command(s) | Schema | Init scaffold |\n| ----------------- | ----------------------------------------------------- | --------------------------------- | -------- | ----------------- |\n| `wiki:` | Corpus on disk — inputs, assets, filename regex | `check`, `lint`, `build`, `serve` | optional | yes |\n| `graph:` | RDF compile — prefixes, document IRIs, body literals | `check`, `query`, `render` | optional | yes |\n| `site:` | Publish routing — layout path, URL prefix, path style | `build`, `serve` | optional | yes |\n| `link:` | `wiki link` apply format and rename repair map | `wiki link` | optional | yes |\n| `check:` | Integrity severities | `wiki check` | optional | yes |\n| `lint:` | Convention severities | `wiki lint` | optional | yes |\n| `sources:` | External data sources (git repos) | `wiki install`, `wiki remove` | optional | commented example |\n| `sparql_service:` | Opt-in SPARQL HTTP on `wiki serve` | `wiki serve` | optional | commented example |\n| `fmt:` | Mechanical Markdown via the Deno formatter | `wiki fmt` | optional | inline mapping |\n\n**Order in the file:** source and semantics first (`wiki`, `graph`), then publish and authoring (`site`, `link`), then severity tables (`check`, `lint`), optional serve (`sparql_service`), then `fmt` last.\n\n**Split keys** — policy lives in one block, severity or tooling in another:\n\n- **`wiki.filename_pattern`** — the regex string. **`lint.filename_pattern`** — how strictly to flag violations (`error`, `warning`, or `off`).\n- **`link.style`** — what `wiki link --apply` inserts (`standard` page links or `wikilink`). **`lint.link_style`** — whether Obsidian `[[wikilinks]]` in body prose are flagged when `link.style` is `standard`. `style` also still accepts the retired spellings `markdown` and `obsidian`, with a deprecation warning (see `link:` settings below).\n\nFor why `check`, `lint`, `fmt`, and `wiki link` are separate commands, see [Design philosophies](Design_Philosophies.md#check-lint-fmt-and-link).\n\n### Always on\n\nThese apply regardless of yaml severities:\n\n- **Route safety** — unsafe URL characters and spaces in routes (`wiki check`).\n- **Output URL collisions** — duplicate built routes (`wiki check`).\n- **SHACL** — when shape documents exist in the corpus (`wiki check`).\n- **Built-in RDF prefixes** — `schema`, `wiki`, `foaf`, `rdf`, `rdfs`, `xsd`, `owl`, `dc`, `dcterms`, `sh`, `wazoo` are always merged at runtime; yaml `graph.context` entries override or add.\n\n## Wiki (`wiki:`)\n\n```yaml\nwiki: # optional block\n input: [wiki] # default [wiki]; init writes\n assets: [assets] # default [assets] if assets/ exists, else []; init omits\n exclude: [] # default []; init omits\n filename_pattern: \"[A-Za-z0-9_()-]+\\\\.md\" # no default; recommended; init writes\n allow_unknown_keys: false # default false; init omits\n```\n\n| Key | Required | Default | Init | Audited by |\n| -------------------- | ---------------------- | ------------------------------------------- | ------ | ------------------------------------------ |\n| `input` | optional | `[wiki]` | writes | indexing (`build`, `check`, `lint`, `fmt`) |\n| `assets` | optional | `[assets]` when `assets/` exists, else `[]` | omits | `wiki build` (static copy) |\n| `exclude` | optional | `[]` | omits | indexing (skipped paths) |\n| `filename_pattern` | optional (recommended) | unset — no regex check until set | writes | `wiki lint` (`lint.filename_pattern`) |\n| `allow_unknown_keys` | optional | `false` | omits | config load |\n\nPage URLs come from paths under `wiki.input`: `wiki/Alice.md` → `/wiki/Alice/` with default `site.base_url` and `site.url_style: dir`. `index.md` in a folder owns that folder’s route (for example `wiki/index.md` → `/wiki/`).\n\nSee [Filename conventions](#filename-conventions) for regex patterns.\n\nUnknown top-level keys fail at load, so a typo such as `lnit:` is caught. Set `wiki.allow_unknown_keys: true` to accept them instead. Unknown keys inside a wiki block (`site:`, `lint:`, ...) are still rejected.\n\n## Graph (`graph:`)\n\nRDF and document URI settings for graph build, `wiki query`, microdata, and SHACL.\n\n```yaml\ngraph: # optional block\n # base_iri: unset → graph.context.wiki → https://wiki.example.org/\n content_predicate: schema:articleBody # unset by default; init writes when flagged\n include_file_extension: false # default false; init omits (commented)\n implicit_types: [] # default []; init omits (commented)\n implicit_types_policy: fallback # default fallback; init omits (commented)\n context: # merges with built-in prefixes; init writes\n schema: https://schema.org/\n wiki: https://example.org/wiki/ # recommended\n wazoo: https://schema.wazoo.dev/\n foaf: http://xmlns.com/foaf/0.1/\n dc: http://purl.org/dc/elements/1.1/\n dcterms: http://purl.org/dc/terms/\n sh: http://www.w3.org/ns/shacl#\n xsd: http://www.w3.org/2001/XMLSchema#\n```\n\n| Key | Required | Default | Init | Audited by |\n| ------------------------ | ------------------------------ | ---------------------------------------------------------- | --------------------------------------- | ------------------------------------------------- |\n| `base_iri` | optional | unset → `graph.context.wiki` → `https://wiki.example.org/` | commented example | document IRIs, `wiki query` |\n| `context` / `@context` | optional (recommended: `wiki`) | built-in prefixes only when unset | writes extended map | CURIE expansion, SHACL, microdata |\n| `content_predicate` | optional | unset — no body literals in graph | writes when `--graph-content-predicate` | SPARQL full-text |\n| `include_file_extension` | optional | `false` | omits (commented) | document URI generation |\n| `implicit_types` | optional | `[]` | omits (commented) | default `rdf:type` on untyped pages |\n| `implicit_types_policy` | optional | `fallback` | omits (commented) | `fallback` or `append` (SHACL shapes skip append) |\n\nWhen `implicit_types_policy` is `append`, frontmatter types are unioned with `implicit_types` (deduped by resolved URI).\n\n## Site (`site:`)\n\nDefault page layout and routing for `wiki build` / `wiki serve`. Branding and chrome → [Page layout](#page-layout).\n\n```yaml\nsite: # optional block\n layout: index.html # unset → built-in minimal fallback layout\n base_url: /wiki # default /wiki; init writes\n url_style: dir # default dir; init writes\n```\n\n| Key | Required | Default | Init | Audited by |\n| ----------- | ---------------------- | ------------------------------------- | ------ | ----------------------------------------------------------------------------------- |\n| `layout` | optional (recommended) | unset — packaged minimal `index.html` | writes | `wiki build`, `wiki serve`; `check.missing_layout_file` for per-page `wazoo:layout` |\n| `base_url` | optional | `/wiki` (`\"\"` allowed for site root) | writes | routes, layout `%wiki.base_url%` |\n| `url_style` | optional | `dir` (`file` → `slug.html`) | writes | output paths; overridable per CLI run |\n\n`site:` does not carry site name, theme color, favicon, or sidebar logo. If you want custom styling, write a custom layout template file and place custom assets under the `wiki.assets` directory, then configure `site.layout` to point to it.\n\nCLI flags on `wiki build` and `wiki serve` can override `site.base_url` and `site.url_style` for a single run.\n\n## Link (`link:`)\n\nSettings for the `wiki link` command family (separate from `lint.link_style` severity).\n\n```yaml\nlink: # optional block\n style: standard # default standard; init writes\n renames: {} # default {}; init omits (commented example)\n```\n\n| Key | Required | Default | Init | Audited by |\n| --------- | -------- | ------------------------------------- | ----------------- | ------------------------ |\n| `style` | optional | `standard` (`wikilink` for wikilinks) | writes | `wiki link --apply` only |\n| `renames` | optional | `{}` | commented example | `wiki link --fix-broken` |\n\n`wiki link --fix-broken` preserves the existing link kind in each file; only `--apply` uses `link.style`.\n\n**Retired spellings.** `markdown` and `obsidian` are still accepted as values for `style`, and `wiki init --link-style` accepts them too. Each prints a deprecation warning and rewrites the value to `standard` or `wikilink`:\n\n```text\nlink.style: 'obsidian' is deprecated, use 'wikilink' instead (edit config file link.style and re-run)\n```\n\nThey are accepted but never advertised: an invalid `--link-style` value lists only `standard` and `wikilink`. Rename the value in your config file to silence the warning.\n\n## Integrity checks (`check:`)\n\nUnder `check`, each rule is `error`, `warning`, or `off`:\n\n```yaml\ncheck: # optional block\n missing_layout_file: error # default error; init writes\n frontmatter_schema: error # default error; init writes\n missing_schema_ref: error # default error; init writes\n shape_definition: error # default error\n shape_unused: warning # default warning\n```\n\n| Key | Required | Default | Init | Audited by |\n| --------------------- | -------- | --------- | ------ | ------------------------------------ |\n| `missing_layout_file` | optional | `error` | writes | `wazoo:layout` paths missing on disk |\n| `frontmatter_schema` | optional | `error` | writes | JSON Schema validation failures |\n| `missing_schema_ref` | optional | `error` | writes | unloadable `wazoo:jsonSchema` refs |\n| `shape_definition` | optional | `error` | — | ill-formed SHACL shape pages |\n| `shape_unused` | optional | `warning` | — | node shapes that validate nothing |\n\nBuild-safety rules (unsafe URL characters, spaces in routes) and output URL collision detection always apply regardless of `check` settings.\n\n### JSON Schema frontmatter (`wazoo:jsonSchema`)\n\n`wiki check` validates frontmatter against JSON Schema in parallel with SHACL. Bind schemas on shape documents with **`wazoo:jsonSchema`** beside **`sh:targetClass`**; every page whose effective `type` matches that class must pass the bound schema(s). Individual pages may append extra schemas with their own `wazoo:jsonSchema` key (scalar or YAML list). Schema refs are local paths under the wiki config root (`.json` only) or remote `http(s)` URLs.\n\nShape binding documents are not validated as instances — only their schema refs are checked for loadability. Authoring detail: [SHACL](SHACL.md), [Style Guide](Style_Guide.md).\n\n## Convention audits (`lint:`)\n\nUnder `lint`, each rule is `error`, `warning`, or `off`:\n\n```yaml\nlint: # optional block\n broken_links: warning # default warning; init writes\n filename_pattern: warning # default warning; init writes\n headings: off # default off; init omits\n heading_levels: off # default off; init omits\n duplicate_headings: off # default off; init omits\n thematic_breaks: off # default off; init omits\n link_style: warning # default warning; init writes\n redundant_frontmatter: off # default off; init omits\n```\n\n| Key | Required | Default | Init | Audited by |\n| ----------------------- | -------- | --------- | ------ | --------------------------------------------------------------------------------- |\n| `broken_links` | optional | `warning` | writes | wikilinks, markdown links, fragments, assets, `wiki:` CURIEs |\n| `filename_pattern` | optional | `warning` | writes | full filename vs `wiki.filename_pattern` |\n| `headings` | optional | `off` | omits | ATX syntax, sentence-case H2+, numbered headings |\n| `heading_levels` | optional | `off` | omits | heading level gaps (for example H1 then H3) |\n| `duplicate_headings` | optional | `off` | omits | duplicate heading text on one page |\n| `thematic_breaks` | optional | `off` | omits | horizontal rules in body prose |\n| `link_style` | optional | `warning` | writes | Obsidian `[[wikilinks]]` when `link.style` is `standard` |\n| `redundant_frontmatter` | optional | `off` | omits | frontmatter that repeats a derived headline or Git date ([wiki fix](wiki_fix.md)) |\n\nATX heading syntax is also enforced by **`wiki fmt`**, the Deno Markdown formatter; Setext underlines are converted on format.\n\nWhen `link.style` is `standard`, set `lint.link_style: off` to allow wikilinks in prose, or set `link.style: wikilink` for an Obsidian-style wiki.\n\n## External data sources (`sources:`)\n\n<!-- wiki:anchor external-data-sources-sources -->\n\nDeclare external git repositories that contribute wiki pages or RDF data to the graph. After adding a source, run `wiki install` to clone it and pin the resolved commit in `wiki.lock`.\n\nSources are read-only inputs during graph construction. Wiki composes root content and installed sources into one default query view, while preserving each installed source as a stable RDF named graph for provenance and SPARQL `GRAPH` clauses.\n\n```yaml\nsources: # optional block\n - name: solar-system\n type: git\n url: https://github.com/EthanThatOneKid/solar-system-wiki.git\n ref: v0.1.0 # optional — branch, tag, or commit\n path: wiki # optional — subdirectory within the repo\n```\n\n| Key | Required | Default | Init | Command(s) |\n| ------ | -------- | --------- | ----------------- | -------------- |\n| `name` | required | — | omits (commented) | `wiki install` |\n| `type` | required | `git` | omits (commented) | `wiki install` |\n| `url` | required | — | omits (commented) | `wiki install` |\n| `ref` | optional | `HEAD` | omits (commented) | `wiki install` |\n| `path` | optional | repo root | omits (commented) | `wiki install` |\n\nEach source must have a unique `name`. The `type` field is currently limited to `git`. Unknown keys and unsupported types are rejected at config load time.\n\nRun `wiki install` to fetch all declared sources and write `wiki.lock`. Check `wiki.lock` into version control for reproducible builds. The resolved source paths are automatically appended to `wiki.input` so the existing graph, check, and build pipeline picks them up.\n\nUse `wiki graph list` to inspect the root graph and installed source graph URIs. Source graph URIs are derived from `graph.context.wiki`:\n\n- Root corpus: `{graph.context.wiki}graphs/root`\n- Installed source: `{graph.context.wiki}graphs/source/{source-name}`\n\nRequested refs, resolved commits, source URLs, cache paths, and direct/transitive dependency metadata remain source metadata; they are not embedded in graph URIs.\n\n**Transitive dependencies** are resolved recursively. After cloning each source, `wiki install` reads the source's own `wiki.yml` (or `wiki.yaml`/`wiki.json`) to discover its `sources:` block. Those transitive sources are fetched and locked too, forming a dependency tree. Circular dependency chains are detected and reported as errors. If two sources declare the same dependency name with different URLs or refs, install fails with a conflict error.\n\nWhen a source is removed with `wiki remove`, transitive sources that are no longer needed by any remaining top-level source are automatically cleaned up (cache and lockfile entry removed).\n\nAfter `wiki update`, newly declared transitive sources are installed, and orphaned sources are reported (but not auto-removed — run `wiki remove` to clean up).\n\nThe `.wiki/` source cache directory is not committed — `wiki init` scaffolds a `.gitignore` that excludes it (alongside the `_site/` build output).\n\nTo add a source without editing the config file by hand:\n\n```bash\nwiki install https://github.com/EthanThatOneKid/solar-system-wiki.git\n# GitHub shorthand also works:\nwiki install EthanThatOneKid/solar-system-wiki\n```\n\nThe name is inferred from the URL (`solar-system`). To remove it:\n\n```bash\nwiki remove solar-system\n```\n\nSee [wiki install](wiki_install.md) and [wiki remove](wiki_remove.md).\n\n### Contributing changes to a source\n\nAn installed source is a read-only input. To change one, change its upstream repository and pull the result back in; never edit the installed copy.\n\n- **Local resolution** (`wiki install`) is a cache: a shallow clone under `.wiki/sources/<name>/repo/`, pinned by `wiki.lock`. It is not committed and is not a place to author.\n- **Vendoring** (copying the pages into your own repository) makes them yours: they are then ordinary root pages and no longer track upstream. Wiki has no vendoring command or config yet ([#150](https://github.com/wazootech/wiki/issues/150)); copy the files and remove the source with `wiki remove`.\n- **Upstream contribution** keeps the source a dependency and sends the change to its owner:\n\n1. Clone the source's repository normally, outside `.wiki/`, and branch (fork it first when you cannot push). It is a wiki in its own right, so use its `wiki file` verbs and its own checks there.\n2. Open a pull request upstream.\n3. Until it merges, point your wiki at the branch: set the source's `url` to your fork (if you forked) and `ref` to the branch, then run `wiki update <name>`. This moves the `wiki.lock` entry to the branch's head.\n4. After it merges, set `url` and `ref` back and run `wiki update <name>` again. Commit `wiki.yml` and `wiki.lock`.\n\nTo follow upstream without contributing, run `wiki update` (or `wiki update <name>`); `wiki update --dry-run` shows what would move.\n\nDo not edit files in `.wiki/sources/`. The edit verbs (`wiki file set`, `patch`, `mv`, `rm`, and `wiki edit`) refuse any path under `.wiki/`. A hand edit there survives `wiki install`, stays uncommitted, and is not in `wiki.lock`, so nobody else sees it. It also breaks `wiki update`: when upstream changes the same file, the update fails with git's \"local changes would be overwritten\" error until you discard the edit (`git -C .wiki/sources/<name>/repo checkout -- .`).\n\nSPARQL Update and in-place writes to sources are not supported; see [Recursive Semantic Datasets](Recursive_Semantic_Datasets.md).\n\nFor the product framing behind recursive source composition, see [Recursive Semantic Datasets](Recursive_Semantic_Datasets.md). For what happens when a source describes the same entity as your root wiki, see [Cross-Wiki Identity](Cross_Wiki_Identity.md).\n\n## Serve API\n\nOpt-in read-only SPARQL HTTP endpoint on `wiki serve`:\n\n```yaml\nsparql_service: # optional block\n enabled: false # default false; init omits (commented)\n path: /api/sparql # default /api/sparql; init omits (commented)\n```\n\n| Key | Required | Default | Init | Audited by |\n| --------- | -------- | ------------- | ----------------- | ---------------------------- |\n| `enabled` | optional | `false` | commented example | `wiki serve` SPARQL endpoint |\n| `path` | optional | `/api/sparql` | commented example | reserved route on serve |\n\n`sparql_service.enabled` accepts YAML booleans and normalizes common string forms such as `true`, `false`, `on`, `off`, `yes`, `no`, `1`, and `0`; prefer native YAML booleans.\n\nExample when enabled:\n\n```yaml\nsparql_service:\n enabled: true\n path: /api/sparql\n```\n\nThe endpoint reuses the same SPARQL engine as `wiki query`. It is read-only and intended for local or development-oriented use. HTTP request forms, supported query types, and `Accept` negotiation are documented in [wiki serve](wiki_serve.md#sparql-endpoint).\n\nIt is **opt-in by default** because enabling it exposes raw graph-query access in addition to HTML preview.\n\n`sparql_service.path` must not collide with the effective `site.base_url` page routes or the watch endpoint. Invalid values such as `/`, `/wiki`, `/wiki/foo`, or `/wiki/__watch` are rejected when `wiki serve` starts.\n\n## Formatting (`fmt`)\n\nTop-level **`fmt`** configures Wiki's in-process `dprint-plugin-markdown` formatter. The inline mapping uses native Deno/dprint option names:\n\n```yaml\nfmt:\n textWrap: never\n lineWidth: 80\n newLineKind: lf\n```\n\n| Option | Values | Default | Effect |\n| ------------- | ----------------------------- | ------- | ------------------------------------------------------------------------ |\n| `textWrap` | `always`, `maintain`, `never` | `never` | Whether prose wraps to the configured width or preserves/avoids wrapping |\n| `lineWidth` | Positive integer | `80` | Target width when `textWrap` is `always` |\n| `newLineKind` | `auto`, `crlf`, `lf` | `lf` | Line ending emitted by the formatter |\n\nOnly an inline mapping is supported. TOML pointers, `.mdformat.toml` discovery, and mdformat-only keys such as `wrap`, `end_of_line`, and `extensions` are not supported. Existing values must be removed or rewritten using the native options above. Omitting `fmt` or using `fmt: {}` selects the Wiki CLI defaults. See [wiki fmt](wiki_fmt.md) for details.\n\n## Page layout\n\nWhen `site.layout` is set, the CLI renders every page through that page layout (`.html`). Per-page overrides use `wazoo:layout` in frontmatter; see [Wiki Page Layouts](Wiki_Page_Layouts.md).\n\n### Layout strategy\n\nThe first-class presentation contract in this repository is layout files referenced from `site.layout` (for example `index.html`).\n\n- The [wiki](wiki.md) owns the semantic markdown-to-HTML pipeline and layout slot contract.\n- Wiki page layout files are the primary built-in extension point for presentation.\n- Advanced themes or framework-specific sites such as Next.js, Mintlify, or other external docs stacks are treated as downstream integrations or separate layout/template repositories.\n\n### Minimal fallback\n\nWithout a configured layout file (or when the path is missing), every page is rendered with the built-in minimal fallback layout (`index.html`), which outputs plain, unstyled HTML containing only `<h1>` and content. It does not link any default CSS or assets and does not include a sidebar, tabs, infobox, table of contents, backlinks, or categories out-of-the-box.\n\n### Layout slots\n\nLayout files use `%wiki.*%` slot substitution (not Jinja). On each page render, the CLI builds a slot map from the current page context and replaces every known slot in your layout file. Unknown `%wiki.*%` spellings are left unchanged.\n\nLayout settings and the supported slots are documented in [Wiki Page Layouts](Wiki_Page_Layouts.md).\n\nCanonical slot list (3 slots):\n\n| Slot | Source | Substitution |\n| ----------------- | ---------------------- | ------------------------------------------------------------- |\n| `%wiki.base_url%` | `site.base_url` | HTML-escaped text (`/wiki`, or `\"\"` for site root) |\n| `%wiki.head%` | built per page | `<title>{page title} - Wiki CLI</title>` (title HTML-escaped) |\n| `%wiki.body%` | rendered markdown body | Pre-built HTML (not escaped) |\n\n**Packaged layouts**\n\n| File | When used | Typical slots |\n| ------------ | ----------------------------------- | ---------------------------- |\n| `index.html` | `site.layout` unset or missing file | `%wiki.head%`, `%wiki.body%` |\n\nExample excerpt (`index.html`):\n\n```html\n<!DOCTYPE html>\n<html lang=en>\n <head>\n<meta charset=UTF-8>\n<meta name=viewport content=width=device-width,initial-scale=1.0>\n%wiki.head%\n </head>\n <body>\n%wiki.body%\n </body>\n</html>\n```\n\n### Custom CSS\n\nThe Wiki CLI does not copy or link a default stylesheet out-of-the-box. To add styling to your pages:\n\n1. **Edit the layout file** — set `site.layout` in `wiki.yml` to a custom layout file. Link stylesheets in `<head>`, or write inline styles.\n1. **Link wiki assets** — place `.css` files under a directory listed in `wiki.assets`, then reference them from the layout, for example `<link rel=\"stylesheet\" href=\"%wiki.base_url%/assets/site.css\">`. Built assets are served at `%wiki.base_url%/assets/…` during `wiki serve` and copied into the build output.\n\n### Custom logos and icons\n\nTo customize site logos, icons, favicons, or touch icons:\n\n1. Place your asset files (such as `logo.svg`, `logo.png`, `favicon.ico`) under a directory listed in `wiki.assets`.\n1. Reference the assets from your custom layout file, for example:\n\n```html\n<img src=\"%wiki.base_url%/assets/logo.svg\" alt=\"\" width=\"80\" height=\"80\">\n```\n\nYou can also add `<link rel=\"icon\">`, `<link rel=\"apple-touch-icon\">`, or other `<head>` tags directly in your custom layout file.\n\nBuilt assets are served at `%wiki.base_url%/assets/…` during `wiki serve` and copied into the build output.\n\nSee also [Wiki Page Layouts](Wiki_Page_Layouts.md) for `site.layout`, `wazoo:layout`, and packaged layout files.\n\nThe metadata pane uses the same RDF serialization path as `wiki export` (compacted JSON-LD, Turtle, N3, N-Triples, TriG, and N-Quads). A compact **Format** chip row switches views without JavaScript. In `wiki serve`, set the initial chip with `?metadata_format=FORMAT` (for example `turtle` or `json-ld`). In `wiki build`, all supported format views are embedded in the page HTML so the picker works offline. RDF/XML output is deferred and is not offered.\n\n### Built-in CSS classes and IDs\n\nThe wiki builder generates these selectors in the rendered page content:\n\n| Selector | Where |\n| --------------------------- | ------------------------------------------------------------------------------------------------- |\n| `#article-top` | Read-view `<article>` wrapper around rendered markdown body. |\n| `#firstHeading` | Read-view page title `<h1>`; also Talk / Source / Metadata pane headings. TOC “(Top)” links here. |\n| `#siteSub` | Subtitle under Talk / Source / Metadata pane headings. |\n| `article` | Wrapper around the rendered markdown body (`#article-top`). |\n| `.layout-label` | Uppercase type or custom-layout badge in read view. |\n| `.toc` / `#toc` | Table of contents container. |\n| `#catlinks` / `.catlinks` | Category links box. |\n| `.backlinks` / `#backlinks` | Backlinks section. |\n| `.catlinks-label` | Categories heading label. |\n| `.catlinks-list` | Categories `<ul>`. |\n| `.infobox` | Typed frontmatter property table. |\n| `.page-meta` | Infobox class (used for styling). |\n| `.template-SLUG` | Per-template class on infobox (e.g. `template-person`). |\n| `toclevel-N` / `lN` | TOC list item classes for heading level N. |\n| `.wikilink` | Internal wiki page links. |\n| `pre[data-copy]` | Block code with raw source for clipboard copy. |\n| `.code-block` | Wrapper injected around copyable pre blocks. |\n| `.code-copy-btn` | Copy button shown on code-block hover/focus. |\n\n### JavaScript hooks\n\nCustom layout files can utilize standard JavaScript hooks or customize their own. In premium layouts (such as template repositories), the following JavaScript features can be implemented:\n\n| Function | Purpose |\n| ------------------------------ | ---------------------------------------------------- |\n| `switchTab(viewName)` | Switch between read / talk / source / metadata tabs. |\n| `loadTalkNotes()` | Load per-page local-storage notes. |\n| `saveTalkNotes()` | Save per-page notes to localStorage. |\n| `clearTalkNotes()` | Clear per-page notes. |\n| `copySourceCode()` | Copy markdown source to clipboard. |\n| `copyPreContent()` | Copy a `pre[data-copy]` block to clipboard. |\n| `initCodeCopyButtons()` | Wrap copyable pre blocks and inject copy buttons. |\n| `toggleToc()` | Show/hide table of contents. |\n| `goToRandomArticle()` | Navigate to a random page. |\n| `triggerSearch()` | Execute search and navigate to first match. |\n| `onSearchInput(e)` | Live search suggestions. |\n| `handleSearchKey(e)` | Keyboard navigation for search suggestions. |\n| `navigateSearch(slug)` | Navigate to a search result. |\n| `applyCategoryFilterFromUrl()` | Filter index page by `?category=` URL parameter. |\n\nIf the configured page layout file does not exist, the packaged minimal `index.html` layout is used silently — no error.\n\n## Filename conventions\n\nThe CLI does not hard-code kebab-case. Projects choose a convention with **`wiki.filename_pattern`**, matched against the **full filename** (including `.md`) on markdown files only.\n\n**Wikipedia-style (recommended):** preserved capitalization and underscores — `Gregory_Davidson.md`, `Pokemon_Diamond_(copy_1).md`, `LLM_Wiki_CLI.md`. Use a pattern such as:\n\n```yaml\nwiki:\n filename_pattern: \"[A-Za-z0-9_()-]+\\\\.md\"\n```\n\n**Kebab-case (optional):** if you prefer `gregory-house.md`, set an explicit pattern (for example `[a-z0-9-]+\\\\.md`) and enforce it via `lint.filename_pattern`. Wikipedia-style and kebab-case should not be mixed in one wiki.\n\nPage routes keep the casing from the filename; GitHub Pages URLs are case-sensitive.\n\n`wiki link --fix-broken` preserves the existing link kind in each file; only `--apply` uses `link.style`.\n\nWhen `link.style` is `standard`, `lint.link_style` (default `warning`) flags Obsidian wikilinks (`[[Page]]`) in body prose. Set `lint.link_style: off` to allow wikilinks while keeping standard links as the apply format, or set `link.style: wikilink` for an Obsidian-style wiki.\n\n## Formatting (`fmt`)\n\n`wiki fmt` uses native Deno/dprint options under an inline `fmt:` mapping. The accepted options, defaults, and removed mdformat/TOML behavior are documented in [wiki fmt](wiki_fmt.md).\n\n## Integrity checks (`check`)\n\nUnder `check`, each rule is `error`, `warning`, or `off`:\n\n| Rule key | Default | What it audits |\n| --------------------- | --------- | ------------------------------------------------------------------------------------------ |\n| `missing_layout_file` | `error` | `wazoo:layout` paths that do not resolve to a readable `.html` file |\n| `frontmatter_schema` | `error` | Frontmatter that fails JSON Schema validation |\n| `missing_schema_ref` | `error` | `wazoo:jsonSchema` paths or URLs that cannot be loaded |\n| `shape_definition` | `error` | Ill-formed SHACL shape pages (see [wiki check](wiki_check.md#shape-definitions)) |\n| `shape_unused` | `warning` | Node shape pages that validate nothing (see [wiki check](wiki_check.md#shape-definitions)) |\n| `remote_schema_refs` | `allow` | Policy for remote `http(s)` schema refs: `allow`, `deny`, or `allowlist` |\n| `remote_schema_hosts` | `[]` | Hostnames permitted when `remote_schema_refs` is `allowlist` |\n\nBuild-safety rules (unsafe URL characters, spaces in routes) and output URL collision detection always apply regardless of `check` settings.\n\n### JSON Schema frontmatter (`wazoo:jsonSchema`)\n\n`wiki check` validates frontmatter against JSON Schema in parallel with SHACL. Bind schemas on shape documents with **`wazoo:jsonSchema`** beside **`sh:targetClass`**; every page whose effective `type` matches that class must pass the bound schema(s). Individual pages may append extra schemas with their own `wazoo:jsonSchema` key (scalar or YAML list). Schema refs are local paths under the wiki config root (`.json` only) or remote `http(s)` URLs. Remote refs can trigger outbound network requests; set `check.remote_schema_refs: deny` in CI over untrusted wikis, or `allowlist` with `check.remote_schema_hosts` for trusted hosts only.\n\nShape binding documents are not validated as instances — only their schema refs are checked for loadability. Authoring detail: [SHACL](SHACL.md), [Style Guide](Style_Guide.md).\n\n## Convention audits (`lint`)\n\nUnder `lint`, each rule is `error`, `warning`, or `off`:\n\n| Rule key | Default | What it audits |\n| ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `broken_links` | `warning` | Wikilinks, internal markdown links, heading fragments, assets, `wiki:` CURIEs |\n| `filename_pattern` | `warning` | Full filename vs `wiki.filename_pattern` regex |\n| `headings` | `off` | ATX `#` headings only (no Setext underlines), sentence-case H2+, H1 title case conventional, numbered headings |\n| `thematic_breaks` | `off` | Horizontal rules (`---`, `***`, `___`) in body prose |\n| `link_style` | `warning` | Obsidian wikilinks (`[[Page]]`) in body prose when `link.style` is `standard` |\n| `redundant_frontmatter` | `off` | A `headline`, `dateCreated`, or `dateModified` that repeats the value the graph derives from the H1 or Git history; remove with [wiki fix](wiki_fix.md) |\n\n`redundant_frontmatter` is `off` by default because many wikis follow the convention of repeating the H1 as `headline`: as a default warning it would fail every such page under `lint --strict`. Turn it on once the redundant keys are removed with `wiki fix --apply`, as this wiki does in `docs/wiki.yml`.\n\n### What `broken_links` accepts\n\n`broken_links` reports a link only when its target is missing. It accepts everything CommonMark allows:\n\n- **Titled and angle-bracket destinations** — `[a](Page.md \"Title\")` and `[a](<Page.md>)` resolve like `[a](Page.md)`; `wiki file mv` keeps the title when it rewrites them.\n- **URLs with a scheme** — `https://`, `ftp://`, `obsidian://`, and `//host` are external and never checked.\n- **Site-root-relative links** — `[a](/wiki/Guides/Setup/)` is resolved against `site.base_url` and `site.url_style` and checked against the page that route maps to. A missing route or heading is still reported; a link outside `site.base_url`, or to a non-page file, is checked as before.\n- **`#top`** — scrolls to the top of the page and needs no matching heading.\n- **Fenced and commented-out links** — links inside backtick or `~~~` fences and HTML comments are skipped.\n\n## This repository\n\n`docs/wiki.yml` is the dogfood wiki config for this repository. It follows the same block order as the packaged scaffold, but with project-specific overrides — `graph.context.wiki` for GitHub Pages and `graph.content_predicate: schema:articleBody` for SPARQL full-text.\n\n## Related\n\n- [wiki](wiki.md#global-options) — `-c` and `--input` global options\n- [wiki init](wiki_init.md) — scaffold a new wiki project\n- [wiki check](wiki_check.md) — integrity checks\n- [wiki lint](wiki_lint.md) — convention audits\n- [wiki query](wiki_query.md) — ad-hoc SPARQL\n- [wiki render](wiki_render.md) — inline SPARQL tables\n- [wiki serve](wiki_serve.md#sparql-endpoint) — `#serve-api` config block\n- [Graph Cache](Graph_Cache.md) — `--cache` and graph reuse\n- [Style Guide](Style_Guide.md) — shapes and frontmatter";
schema:headline "Wiki Configuration";
schema:dateCreated "2026-10-31T23:19:03Z"^^xsd:dateTime;
schema:dateModified "2026-10-31T23:19:03Z"^^xsd:dateTime.
<https://wazootech.github.io/wiki/Wiki_Configuration> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://schema.org/TechArticle> .
<https://wazootech.github.io/wiki/Wiki_Configuration> <https://schema.org/description> "Reference for wiki.yaml, wiki.yml, and wiki.json (Config)." .
<https://wazootech.github.io/wiki/Wiki_Configuration> <https://schema.org/articleBody> """# Wiki Configuration
The CLI loads **Config** from `wiki.yml`, `wiki.yaml`, or `wiki.json` in the working directory (or from `-c path`).
The in-memory **Config** model uses the same nested blocks as the file (`wiki`, `graph`, `site`, `link`, `check`, `lint`, `fmt`, `sparql_service`). There is no separate flat runtime shape. `Config.load()` validates the file, injects `config_root` (the directory containing the config file), and resolves relative paths under `wiki` and `site`. Library and test code can construct configs with `Config(wiki={...}, config_root=path)` or `Config.for_root(path, wiki={...})`.
Config files are validated strictly by the TypeScript schema in [`src/wiki/schemas/wiki_config.ts`](https://github.com/wazootech/wiki/blob/main/src/wiki/schemas/wiki_config.ts), which forbids extra keys on every block. Unknown keys, removed aliases, wrong nested keys under `check`, `lint`, or `sparql_service`, invalid syntax, or a non-mapping top level all fail immediately instead of being ignored. An unknown key is reported by name against the accepted surface; the engine does not guess which key you meant.
JSON configs may use `graph.context` or `graph.@context` for prefix maps (JSON-LD compatible).
## Overview
### Terminology
| Label | Meaning |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Schema optional** | Key or block may be omitted; the schema applies a default. No yaml key is strictly required for `Config.load()` to succeed. |
| **Init** | Written by `wiki init` ([`wiki.yml`](https://github.com/wazootech/wiki/blob/main/src/wiki/templates/wiki.yml)); omitting an Init key is the same as the schema default. |
| **Recommended** | Not enforced by schema, but you typically set it for a real wiki (for example `graph.context.wiki`, `wiki.filename_pattern`, `site.layout`). |
| **Always on** | Behavior not gated by yaml severities (route safety, URL collisions, built-in RDF prefixes). |
### Audit lanes
Three audit lanes map to three commands:
| Lane | Command | YAML block | Purpose |
| ---------- | ------------ | ---------- | ------------------------------------------------------------------------------------------------------ |
| Integrity | `wiki check` | `check:` | SHACL, JSON Schema frontmatter, layout file existence |
| Convention | `wiki lint` | `lint:` | Links, filename pattern severity, headings, link style in prose |
| Formatting | `wiki fmt` | `fmt:` | Mechanical Markdown via the Deno formatter's native `textWrap`, `lineWidth`, and `newLineKind` options |
**Rule placement:** Mechanical markdown belongs under **`fmt:`**. Wiki policy and link conventions belong under **`lint:`**. SHACL, JSON Schema, and layout keys belong under **`check:`** — never under `lint:`. See [Style Guide](Style_Guide.md) for the full matrix.
- Putting a regex under `check.filename_pattern` fails at load with a hint.
- `check.filename_pattern` and `check.headings` fail at load — use `lint.filename_pattern` and `lint.headings`.
Relative **`--input`** paths on the CLI resolve against the config file directory (same as paths in yaml), not the shell cwd.
### Blocks
Top-level blocks follow a **compile pipeline** plus **audit lanes**, not arbitrary grouping. `wiki init` and [docs/wiki.yml](https://github.com/wazootech/wiki/blob/main/docs/wiki.yml) use the same order as the packaged scaffold [`wiki.yml`](https://github.com/wazootech/wiki/blob/main/src/wiki/templates/wiki.yml).
| Block | Role | Command(s) | Schema | Init scaffold |
| ----------------- | ----------------------------------------------------- | --------------------------------- | -------- | ----------------- |
| `wiki:` | Corpus on disk — inputs, assets, filename regex | `check`, `lint`, `build`, `serve` | optional | yes |
| `graph:` | RDF compile — prefixes, document IRIs, body literals | `check`, `query`, `render` | optional | yes |
| `site:` | Publish routing — layout path, URL prefix, path style | `build`, `serve` | optional | yes |
| `link:` | `wiki link` apply format and rename repair map | `wiki link` | optional | yes |
| `check:` | Integrity severities | `wiki check` | optional | yes |
| `lint:` | Convention severities | `wiki lint` | optional | yes |
| `sources:` | External data sources (git repos) | `wiki install`, `wiki remove` | optional | commented example |
| `sparql_service:` | Opt-in SPARQL HTTP on `wiki serve` | `wiki serve` | optional | commented example |
| `fmt:` | Mechanical Markdown via the Deno formatter | `wiki fmt` | optional | inline mapping |
**Order in the file:** source and semantics first (`wiki`, `graph`), then publish and authoring (`site`, `link`), then severity tables (`check`, `lint`), optional serve (`sparql_service`), then `fmt` last.
**Split keys** — policy lives in one block, severity or tooling in another:
- **`wiki.filename_pattern`** — the regex string. **`lint.filename_pattern`** — how strictly to flag violations (`error`, `warning`, or `off`).
- **`link.style`** — what `wiki link --apply` inserts (`standard` page links or `wikilink`). **`lint.link_style`** — whether Obsidian `[[wikilinks]]` in body prose are flagged when `link.style` is `standard`. `style` also still accepts the retired spellings `markdown` and `obsidian`, with a deprecation warning (see `link:` settings below).
For why `check`, `lint`, `fmt`, and `wiki link` are separate commands, see [Design philosophies](Design_Philosophies.md#check-lint-fmt-and-link).
### Always on
These apply regardless of yaml severities:
- **Route safety** — unsafe URL characters and spaces in routes (`wiki check`).
- **Output URL collisions** — duplicate built routes (`wiki check`).
- **SHACL** — when shape documents exist in the corpus (`wiki check`).
- **Built-in RDF prefixes** — `schema`, `wiki`, `foaf`, `rdf`, `rdfs`, `xsd`, `owl`, `dc`, `dcterms`, `sh`, `wazoo` are always merged at runtime; yaml `graph.context` entries override or add.
## Wiki (`wiki:`)
```yaml
wiki: # optional block
input: [wiki] # default [wiki]; init writes
assets: [assets] # default [assets] if assets/ exists, else []; init omits
exclude: [] # default []; init omits
filename_pattern: "[A-Za-z0-9_()-]+\\\\.md" # no default; recommended; init writes
allow_unknown_keys: false # default false; init omits
```
| Key | Required | Default | Init | Audited by |
| -------------------- | ---------------------- | ------------------------------------------- | ------ | ------------------------------------------ |
| `input` | optional | `[wiki]` | writes | indexing (`build`, `check`, `lint`, `fmt`) |
| `assets` | optional | `[assets]` when `assets/` exists, else `[]` | omits | `wiki build` (static copy) |
| `exclude` | optional | `[]` | omits | indexing (skipped paths) |
| `filename_pattern` | optional (recommended) | unset — no regex check until set | writes | `wiki lint` (`lint.filename_pattern`) |
| `allow_unknown_keys` | optional | `false` | omits | config load |
Page URLs come from paths under `wiki.input`: `wiki/Alice.md` → `/wiki/Alice/` with default `site.base_url` and `site.url_style: dir`. `index.md` in a folder owns that folder’s route (for example `wiki/index.md` → `/wiki/`).
See [Filename conventions](#filename-conventions) for regex patterns.
Unknown top-level keys fail at load, so a typo such as `lnit:` is caught. Set `wiki.allow_unknown_keys: true` to accept them instead. Unknown keys inside a wiki block (`site:`, `lint:`, ...) are still rejected.
## Graph (`graph:`)
RDF and document URI settings for graph build, `wiki query`, microdata, and SHACL.
```yaml
graph: # optional block
# base_iri: unset → graph.context.wiki → https://wiki.example.org/
content_predicate: schema:articleBody # unset by default; init writes when flagged
include_file_extension: false # default false; init omits (commented)
implicit_types: [] # default []; init omits (commented)
implicit_types_policy: fallback # default fallback; init omits (commented)
context: # merges with built-in prefixes; init writes
schema: https://schema.org/
wiki: https://example.org/wiki/ # recommended
wazoo: https://schema.wazoo.dev/
foaf: http://xmlns.com/foaf/0.1/
dc: http://purl.org/dc/elements/1.1/
dcterms: http://purl.org/dc/terms/
sh: http://www.w3.org/ns/shacl#
xsd: http://www.w3.org/2001/XMLSchema#
```
| Key | Required | Default | Init | Audited by |
| ------------------------ | ------------------------------ | ---------------------------------------------------------- | --------------------------------------- | ------------------------------------------------- |
| `base_iri` | optional | unset → `graph.context.wiki` → `https://wiki.example.org/` | commented example | document IRIs, `wiki query` |
| `context` / `@context` | optional (recommended: `wiki`) | built-in prefixes only when unset | writes extended map | CURIE expansion, SHACL, microdata |
| `content_predicate` | optional | unset — no body literals in graph | writes when `--graph-content-predicate` | SPARQL full-text |
| `include_file_extension` | optional | `false` | omits (commented) | document URI generation |
| `implicit_types` | optional | `[]` | omits (commented) | default `rdf:type` on untyped pages |
| `implicit_types_policy` | optional | `fallback` | omits (commented) | `fallback` or `append` (SHACL shapes skip append) |
When `implicit_types_policy` is `append`, frontmatter types are unioned with `implicit_types` (deduped by resolved URI).
## Site (`site:`)
Default page layout and routing for `wiki build` / `wiki serve`. Branding and chrome → [Page layout](#page-layout).
```yaml
site: # optional block
layout: index.html # unset → built-in minimal fallback layout
base_url: /wiki # default /wiki; init writes
url_style: dir # default dir; init writes
```
| Key | Required | Default | Init | Audited by |
| ----------- | ---------------------- | ------------------------------------- | ------ | ----------------------------------------------------------------------------------- |
| `layout` | optional (recommended) | unset — packaged minimal `index.html` | writes | `wiki build`, `wiki serve`; `check.missing_layout_file` for per-page `wazoo:layout` |
| `base_url` | optional | `/wiki` (`""` allowed for site root) | writes | routes, layout `%wiki.base_url%` |
| `url_style` | optional | `dir` (`file` → `slug.html`) | writes | output paths; overridable per CLI run |
`site:` does not carry site name, theme color, favicon, or sidebar logo. If you want custom styling, write a custom layout template file and place custom assets under the `wiki.assets` directory, then configure `site.layout` to point to it.
CLI flags on `wiki build` and `wiki serve` can override `site.base_url` and `site.url_style` for a single run.
## Link (`link:`)
Settings for the `wiki link` command family (separate from `lint.link_style` severity).
```yaml
link: # optional block
style: standard # default standard; init writes
renames: {} # default {}; init omits (commented example)
```
| Key | Required | Default | Init | Audited by |
| --------- | -------- | ------------------------------------- | ----------------- | ------------------------ |
| `style` | optional | `standard` (`wikilink` for wikilinks) | writes | `wiki link --apply` only |
| `renames` | optional | `{}` | commented example | `wiki link --fix-broken` |
`wiki link --fix-broken` preserves the existing link kind in each file; only `--apply` uses `link.style`.
**Retired spellings.** `markdown` and `obsidian` are still accepted as values for `style`, and `wiki init --link-style` accepts them too. Each prints a deprecation warning and rewrites the value to `standard` or `wikilink`:
```text
link.style: 'obsidian' is deprecated, use 'wikilink' instead (edit config file link.style and re-run)
```
They are accepted but never advertised: an invalid `--link-style` value lists only `standard` and `wikilink`. Rename the value in your config file to silence the warning.
## Integrity checks (`check:`)
Under `check`, each rule is `error`, `warning`, or `off`:
```yaml
check: # optional block
missing_layout_file: error # default error; init writes
frontmatter_schema: error # default error; init writes
missing_schema_ref: error # default error; init writes
shape_definition: error # default error
shape_unused: warning # default warning
```
| Key | Required | Default | Init | Audited by |
| --------------------- | -------- | --------- | ------ | ------------------------------------ |
| `missing_layout_file` | optional | `error` | writes | `wazoo:layout` paths missing on disk |
| `frontmatter_schema` | optional | `error` | writes | JSON Schema validation failures |
| `missing_schema_ref` | optional | `error` | writes | unloadable `wazoo:jsonSchema` refs |
| `shape_definition` | optional | `error` | — | ill-formed SHACL shape pages |
| `shape_unused` | optional | `warning` | — | node shapes that validate nothing |
Build-safety rules (unsafe URL characters, spaces in routes) and output URL collision detection always apply regardless of `check` settings.
### JSON Schema frontmatter (`wazoo:jsonSchema`)
`wiki check` validates frontmatter against JSON Schema in parallel with SHACL. Bind schemas on shape documents with **`wazoo:jsonSchema`** beside **`sh:targetClass`**; every page whose effective `type` matches that class must pass the bound schema(s). Individual pages may append extra schemas with their own `wazoo:jsonSchema` key (scalar or YAML list). Schema refs are local paths under the wiki config root (`.json` only) or remote `http(s)` URLs.
Shape binding documents are not validated as instances — only their schema refs are checked for loadability. Authoring detail: [SHACL](SHACL.md), [Style Guide](Style_Guide.md).
## Convention audits (`lint:`)
Under `lint`, each rule is `error`, `warning`, or `off`:
```yaml
lint: # optional block
broken_links: warning # default warning; init writes
filename_pattern: warning # default warning; init writes
headings: off # default off; init omits
heading_levels: off # default off; init omits
duplicate_headings: off # default off; init omits
thematic_breaks: off # default off; init omits
link_style: warning # default warning; init writes
redundant_frontmatter: off # default off; init omits
```
| Key | Required | Default | Init | Audited by |
| ----------------------- | -------- | --------- | ------ | --------------------------------------------------------------------------------- |
| `broken_links` | optional | `warning` | writes | wikilinks, markdown links, fragments, assets, `wiki:` CURIEs |
| `filename_pattern` | optional | `warning` | writes | full filename vs `wiki.filename_pattern` |
| `headings` | optional | `off` | omits | ATX syntax, sentence-case H2+, numbered headings |
| `heading_levels` | optional | `off` | omits | heading level gaps (for example H1 then H3) |
| `duplicate_headings` | optional | `off` | omits | duplicate heading text on one page |
| `thematic_breaks` | optional | `off` | omits | horizontal rules in body prose |
| `link_style` | optional | `warning` | writes | Obsidian `[[wikilinks]]` when `link.style` is `standard` |
| `redundant_frontmatter` | optional | `off` | omits | frontmatter that repeats a derived headline or Git date ([wiki fix](wiki_fix.md)) |
ATX heading syntax is also enforced by **`wiki fmt`**, the Deno Markdown formatter; Setext underlines are converted on format.
When `link.style` is `standard`, set `lint.link_style: off` to allow wikilinks in prose, or set `link.style: wikilink` for an Obsidian-style wiki.
## External data sources (`sources:`)
<!-- wiki:anchor external-data-sources-sources -->
Declare external git repositories that contribute wiki pages or RDF data to the graph. After adding a source, run `wiki install` to clone it and pin the resolved commit in `wiki.lock`.
Sources are read-only inputs during graph construction. Wiki composes root content and installed sources into one default query view, while preserving each installed source as a stable RDF named graph for provenance and SPARQL `GRAPH` clauses.
```yaml
sources: # optional block
- name: solar-system
type: git
url: https://github.com/EthanThatOneKid/solar-system-wiki.git
ref: v0.1.0 # optional — branch, tag, or commit
path: wiki # optional — subdirectory within the repo
```
| Key | Required | Default | Init | Command(s) |
| ------ | -------- | --------- | ----------------- | -------------- |
| `name` | required | — | omits (commented) | `wiki install` |
| `type` | required | `git` | omits (commented) | `wiki install` |
| `url` | required | — | omits (commented) | `wiki install` |
| `ref` | optional | `HEAD` | omits (commented) | `wiki install` |
| `path` | optional | repo root | omits (commented) | `wiki install` |
Each source must have a unique `name`. The `type` field is currently limited to `git`. Unknown keys and unsupported types are rejected at config load time.
Run `wiki install` to fetch all declared sources and write `wiki.lock`. Check `wiki.lock` into version control for reproducible builds. The resolved source paths are automatically appended to `wiki.input` so the existing graph, check, and build pipeline picks them up.
Use `wiki graph list` to inspect the root graph and installed source graph URIs. Source graph URIs are derived from `graph.context.wiki`:
- Root corpus: `{graph.context.wiki}graphs/root`
- Installed source: `{graph.context.wiki}graphs/source/{source-name}`
Requested refs, resolved commits, source URLs, cache paths, and direct/transitive dependency metadata remain source metadata; they are not embedded in graph URIs.
**Transitive dependencies** are resolved recursively. After cloning each source, `wiki install` reads the source's own `wiki.yml` (or `wiki.yaml`/`wiki.json`) to discover its `sources:` block. Those transitive sources are fetched and locked too, forming a dependency tree. Circular dependency chains are detected and reported as errors. If two sources declare the same dependency name with different URLs or refs, install fails with a conflict error.
When a source is removed with `wiki remove`, transitive sources that are no longer needed by any remaining top-level source are automatically cleaned up (cache and lockfile entry removed).
After `wiki update`, newly declared transitive sources are installed, and orphaned sources are reported (but not auto-removed — run `wiki remove` to clean up).
The `.wiki/` source cache directory is not committed — `wiki init` scaffolds a `.gitignore` that excludes it (alongside the `_site/` build output).
To add a source without editing the config file by hand:
```bash
wiki install https://github.com/EthanThatOneKid/solar-system-wiki.git
# GitHub shorthand also works:
wiki install EthanThatOneKid/solar-system-wiki
```
The name is inferred from the URL (`solar-system`). To remove it:
```bash
wiki remove solar-system
```
See [wiki install](wiki_install.md) and [wiki remove](wiki_remove.md).
### Contributing changes to a source
An installed source is a read-only input. To change one, change its upstream repository and pull the result back in; never edit the installed copy.
- **Local resolution** (`wiki install`) is a cache: a shallow clone under `.wiki/sources/<name>/repo/`, pinned by `wiki.lock`. It is not committed and is not a place to author.
- **Vendoring** (copying the pages into your own repository) makes them yours: they are then ordinary root pages and no longer track upstream. Wiki has no vendoring command or config yet ([#150](https://github.com/wazootech/wiki/issues/150)); copy the files and remove the source with `wiki remove`.
- **Upstream contribution** keeps the source a dependency and sends the change to its owner:
1. Clone the source's repository normally, outside `.wiki/`, and branch (fork it first when you cannot push). It is a wiki in its own right, so use its `wiki file` verbs and its own checks there.
2. Open a pull request upstream.
3. Until it merges, point your wiki at the branch: set the source's `url` to your fork (if you forked) and `ref` to the branch, then run `wiki update <name>`. This moves the `wiki.lock` entry to the branch's head.
4. After it merges, set `url` and `ref` back and run `wiki update <name>` again. Commit `wiki.yml` and `wiki.lock`.
To follow upstream without contributing, run `wiki update` (or `wiki update <name>`); `wiki update --dry-run` shows what would move.
Do not edit files in `.wiki/sources/`. The edit verbs (`wiki file set`, `patch`, `mv`, `rm`, and `wiki edit`) refuse any path under `.wiki/`. A hand edit there survives `wiki install`, stays uncommitted, and is not in `wiki.lock`, so nobody else sees it. It also breaks `wiki update`: when upstream changes the same file, the update fails with git's "local changes would be overwritten" error until you discard the edit (`git -C .wiki/sources/<name>/repo checkout -- .`).
SPARQL Update and in-place writes to sources are not supported; see [Recursive Semantic Datasets](Recursive_Semantic_Datasets.md).
For the product framing behind recursive source composition, see [Recursive Semantic Datasets](Recursive_Semantic_Datasets.md). For what happens when a source describes the same entity as your root wiki, see [Cross-Wiki Identity](Cross_Wiki_Identity.md).
## Serve API
Opt-in read-only SPARQL HTTP endpoint on `wiki serve`:
```yaml
sparql_service: # optional block
enabled: false # default false; init omits (commented)
path: /api/sparql # default /api/sparql; init omits (commented)
```
| Key | Required | Default | Init | Audited by |
| --------- | -------- | ------------- | ----------------- | ---------------------------- |
| `enabled` | optional | `false` | commented example | `wiki serve` SPARQL endpoint |
| `path` | optional | `/api/sparql` | commented example | reserved route on serve |
`sparql_service.enabled` accepts YAML booleans and normalizes common string forms such as `true`, `false`, `on`, `off`, `yes`, `no`, `1`, and `0`; prefer native YAML booleans.
Example when enabled:
```yaml
sparql_service:
enabled: true
path: /api/sparql
```
The endpoint reuses the same SPARQL engine as `wiki query`. It is read-only and intended for local or development-oriented use. HTTP request forms, supported query types, and `Accept` negotiation are documented in [wiki serve](wiki_serve.md#sparql-endpoint).
It is **opt-in by default** because enabling it exposes raw graph-query access in addition to HTML preview.
`sparql_service.path` must not collide with the effective `site.base_url` page routes or the watch endpoint. Invalid values such as `/`, `/wiki`, `/wiki/foo`, or `/wiki/__watch` are rejected when `wiki serve` starts.
## Formatting (`fmt`)
Top-level **`fmt`** configures Wiki's in-process `dprint-plugin-markdown` formatter. The inline mapping uses native Deno/dprint option names:
```yaml
fmt:
textWrap: never
lineWidth: 80
newLineKind: lf
```
| Option | Values | Default | Effect |
| ------------- | ----------------------------- | ------- | ------------------------------------------------------------------------ |
| `textWrap` | `always`, `maintain`, `never` | `never` | Whether prose wraps to the configured width or preserves/avoids wrapping |
| `lineWidth` | Positive integer | `80` | Target width when `textWrap` is `always` |
| `newLineKind` | `auto`, `crlf`, `lf` | `lf` | Line ending emitted by the formatter |
Only an inline mapping is supported. TOML pointers, `.mdformat.toml` discovery, and mdformat-only keys such as `wrap`, `end_of_line`, and `extensions` are not supported. Existing values must be removed or rewritten using the native options above. Omitting `fmt` or using `fmt: {}` selects the Wiki CLI defaults. See [wiki fmt](wiki_fmt.md) for details.
## Page layout
When `site.layout` is set, the CLI renders every page through that page layout (`.html`). Per-page overrides use `wazoo:layout` in frontmatter; see [Wiki Page Layouts](Wiki_Page_Layouts.md).
### Layout strategy
The first-class presentation contract in this repository is layout files referenced from `site.layout` (for example `index.html`).
- The [wiki](wiki.md) owns the semantic markdown-to-HTML pipeline and layout slot contract.
- Wiki page layout files are the primary built-in extension point for presentation.
- Advanced themes or framework-specific sites such as Next.js, Mintlify, or other external docs stacks are treated as downstream integrations or separate layout/template repositories.
### Minimal fallback
Without a configured layout file (or when the path is missing), every page is rendered with the built-in minimal fallback layout (`index.html`), which outputs plain, unstyled HTML containing only `<h1>` and content. It does not link any default CSS or assets and does not include a sidebar, tabs, infobox, table of contents, backlinks, or categories out-of-the-box.
### Layout slots
Layout files use `%wiki.*%` slot substitution (not Jinja). On each page render, the CLI builds a slot map from the current page context and replaces every known slot in your layout file. Unknown `%wiki.*%` spellings are left unchanged.
Layout settings and the supported slots are documented in [Wiki Page Layouts](Wiki_Page_Layouts.md).
Canonical slot list (3 slots):
| Slot | Source | Substitution |
| ----------------- | ---------------------- | ------------------------------------------------------------- |
| `%wiki.base_url%` | `site.base_url` | HTML-escaped text (`/wiki`, or `""` for site root) |
| `%wiki.head%` | built per page | `<title>{page title} - Wiki CLI</title>` (title HTML-escaped) |
| `%wiki.body%` | rendered markdown body | Pre-built HTML (not escaped) |
**Packaged layouts**
| File | When used | Typical slots |
| ------------ | ----------------------------------- | ---------------------------- |
| `index.html` | `site.layout` unset or missing file | `%wiki.head%`, `%wiki.body%` |
Example excerpt (`index.html`):
```html
<!DOCTYPE html>
<html lang=en>
<head>
<meta charset=UTF-8>
<meta name=viewport content=width=device-width,initial-scale=1.0>
%wiki.head%
</head>
<body>
%wiki.body%
</body>
</html>
```
### Custom CSS
The Wiki CLI does not copy or link a default stylesheet out-of-the-box. To add styling to your pages:
1. **Edit the layout file** — set `site.layout` in `wiki.yml` to a custom layout file. Link stylesheets in `<head>`, or write inline styles.
1. **Link wiki assets** — place `.css` files under a directory listed in `wiki.assets`, then reference them from the layout, for example `<link rel="stylesheet" href="%wiki.base_url%/assets/site.css">`. Built assets are served at `%wiki.base_url%/assets/…` during `wiki serve` and copied into the build output.
### Custom logos and icons
To customize site logos, icons, favicons, or touch icons:
1. Place your asset files (such as `logo.svg`, `logo.png`, `favicon.ico`) under a directory listed in `wiki.assets`.
1. Reference the assets from your custom layout file, for example:
```html
<img src="%wiki.base_url%/assets/logo.svg" alt="" width="80" height="80">
```
You can also add `<link rel="icon">`, `<link rel="apple-touch-icon">`, or other `<head>` tags directly in your custom layout file.
Built assets are served at `%wiki.base_url%/assets/…` during `wiki serve` and copied into the build output.
See also [Wiki Page Layouts](Wiki_Page_Layouts.md) for `site.layout`, `wazoo:layout`, and packaged layout files.
The metadata pane uses the same RDF serialization path as `wiki export` (compacted JSON-LD, Turtle, N3, N-Triples, TriG, and N-Quads). A compact **Format** chip row switches views without JavaScript. In `wiki serve`, set the initial chip with `?metadata_format=FORMAT` (for example `turtle` or `json-ld`). In `wiki build`, all supported format views are embedded in the page HTML so the picker works offline. RDF/XML output is deferred and is not offered.
### Built-in CSS classes and IDs
The wiki builder generates these selectors in the rendered page content:
| Selector | Where |
| --------------------------- | ------------------------------------------------------------------------------------------------- |
| `#article-top` | Read-view `<article>` wrapper around rendered markdown body. |
| `#firstHeading` | Read-view page title `<h1>`; also Talk / Source / Metadata pane headings. TOC “(Top)” links here. |
| `#siteSub` | Subtitle under Talk / Source / Metadata pane headings. |
| `article` | Wrapper around the rendered markdown body (`#article-top`). |
| `.layout-label` | Uppercase type or custom-layout badge in read view. |
| `.toc` / `#toc` | Table of contents container. |
| `#catlinks` / `.catlinks` | Category links box. |
| `.backlinks` / `#backlinks` | Backlinks section. |
| `.catlinks-label` | Categories heading label. |
| `.catlinks-list` | Categories `<ul>`. |
| `.infobox` | Typed frontmatter property table. |
| `.page-meta` | Infobox class (used for styling). |
| `.template-SLUG` | Per-template class on infobox (e.g. `template-person`). |
| `toclevel-N` / `lN` | TOC list item classes for heading level N. |
| `.wikilink` | Internal wiki page links. |
| `pre[data-copy]` | Block code with raw source for clipboard copy. |
| `.code-block` | Wrapper injected around copyable pre blocks. |
| `.code-copy-btn` | Copy button shown on code-block hover/focus. |
### JavaScript hooks
Custom layout files can utilize standard JavaScript hooks or customize their own. In premium layouts (such as template repositories), the following JavaScript features can be implemented:
| Function | Purpose |
| ------------------------------ | ---------------------------------------------------- |
| `switchTab(viewName)` | Switch between read / talk / source / metadata tabs. |
| `loadTalkNotes()` | Load per-page local-storage notes. |
| `saveTalkNotes()` | Save per-page notes to localStorage. |
| `clearTalkNotes()` | Clear per-page notes. |
| `copySourceCode()` | Copy markdown source to clipboard. |
| `copyPreContent()` | Copy a `pre[data-copy]` block to clipboard. |
| `initCodeCopyButtons()` | Wrap copyable pre blocks and inject copy buttons. |
| `toggleToc()` | Show/hide table of contents. |
| `goToRandomArticle()` | Navigate to a random page. |
| `triggerSearch()` | Execute search and navigate to first match. |
| `onSearchInput(e)` | Live search suggestions. |
| `handleSearchKey(e)` | Keyboard navigation for search suggestions. |
| `navigateSearch(slug)` | Navigate to a search result. |
| `applyCategoryFilterFromUrl()` | Filter index page by `?category=` URL parameter. |
If the configured page layout file does not exist, the packaged minimal `index.html` layout is used silently — no error.
## Filename conventions
The CLI does not hard-code kebab-case. Projects choose a convention with **`wiki.filename_pattern`**, matched against the **full filename** (including `.md`) on markdown files only.
**Wikipedia-style (recommended):** preserved capitalization and underscores — `Gregory_Davidson.md`, `Pokemon_Diamond_(copy_1).md`, `LLM_Wiki_CLI.md`. Use a pattern such as:
```yaml
wiki:
filename_pattern: "[A-Za-z0-9_()-]+\\\\.md"
```
**Kebab-case (optional):** if you prefer `gregory-house.md`, set an explicit pattern (for example `[a-z0-9-]+\\\\.md`) and enforce it via `lint.filename_pattern`. Wikipedia-style and kebab-case should not be mixed in one wiki.
Page routes keep the casing from the filename; GitHub Pages URLs are case-sensitive.
`wiki link --fix-broken` preserves the existing link kind in each file; only `--apply` uses `link.style`.
When `link.style` is `standard`, `lint.link_style` (default `warning`) flags Obsidian wikilinks (`[[Page]]`) in body prose. Set `lint.link_style: off` to allow wikilinks while keeping standard links as the apply format, or set `link.style: wikilink` for an Obsidian-style wiki.
## Formatting (`fmt`)
`wiki fmt` uses native Deno/dprint options under an inline `fmt:` mapping. The accepted options, defaults, and removed mdformat/TOML behavior are documented in [wiki fmt](wiki_fmt.md).
## Integrity checks (`check`)
Under `check`, each rule is `error`, `warning`, or `off`:
| Rule key | Default | What it audits |
| --------------------- | --------- | ------------------------------------------------------------------------------------------ |
| `missing_layout_file` | `error` | `wazoo:layout` paths that do not resolve to a readable `.html` file |
| `frontmatter_schema` | `error` | Frontmatter that fails JSON Schema validation |
| `missing_schema_ref` | `error` | `wazoo:jsonSchema` paths or URLs that cannot be loaded |
| `shape_definition` | `error` | Ill-formed SHACL shape pages (see [wiki check](wiki_check.md#shape-definitions)) |
| `shape_unused` | `warning` | Node shape pages that validate nothing (see [wiki check](wiki_check.md#shape-definitions)) |
| `remote_schema_refs` | `allow` | Policy for remote `http(s)` schema refs: `allow`, `deny`, or `allowlist` |
| `remote_schema_hosts` | `[]` | Hostnames permitted when `remote_schema_refs` is `allowlist` |
Build-safety rules (unsafe URL characters, spaces in routes) and output URL collision detection always apply regardless of `check` settings.
### JSON Schema frontmatter (`wazoo:jsonSchema`)
`wiki check` validates frontmatter against JSON Schema in parallel with SHACL. Bind schemas on shape documents with **`wazoo:jsonSchema`** beside **`sh:targetClass`**; every page whose effective `type` matches that class must pass the bound schema(s). Individual pages may append extra schemas with their own `wazoo:jsonSchema` key (scalar or YAML list). Schema refs are local paths under the wiki config root (`.json` only) or remote `http(s)` URLs. Remote refs can trigger outbound network requests; set `check.remote_schema_refs: deny` in CI over untrusted wikis, or `allowlist` with `check.remote_schema_hosts` for trusted hosts only.
Shape binding documents are not validated as instances — only their schema refs are checked for loadability. Authoring detail: [SHACL](SHACL.md), [Style Guide](Style_Guide.md).
## Convention audits (`lint`)
Under `lint`, each rule is `error`, `warning`, or `off`:
| Rule key | Default | What it audits |
| ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `broken_links` | `warning` | Wikilinks, internal markdown links, heading fragments, assets, `wiki:` CURIEs |
| `filename_pattern` | `warning` | Full filename vs `wiki.filename_pattern` regex |
| `headings` | `off` | ATX `#` headings only (no Setext underlines), sentence-case H2+, H1 title case conventional, numbered headings |
| `thematic_breaks` | `off` | Horizontal rules (`---`, `***`, `___`) in body prose |
| `link_style` | `warning` | Obsidian wikilinks (`[[Page]]`) in body prose when `link.style` is `standard` |
| `redundant_frontmatter` | `off` | A `headline`, `dateCreated`, or `dateModified` that repeats the value the graph derives from the H1 or Git history; remove with [wiki fix](wiki_fix.md) |
`redundant_frontmatter` is `off` by default because many wikis follow the convention of repeating the H1 as `headline`: as a default warning it would fail every such page under `lint --strict`. Turn it on once the redundant keys are removed with `wiki fix --apply`, as this wiki does in `docs/wiki.yml`.
### What `broken_links` accepts
`broken_links` reports a link only when its target is missing. It accepts everything CommonMark allows:
- **Titled and angle-bracket destinations** — `[a](Page.md "Title")` and `[a](<Page.md>)` resolve like `[a](Page.md)`; `wiki file mv` keeps the title when it rewrites them.
- **URLs with a scheme** — `https://`, `ftp://`, `obsidian://`, and `//host` are external and never checked.
- **Site-root-relative links** — `[a](/wiki/Guides/Setup/)` is resolved against `site.base_url` and `site.url_style` and checked against the page that route maps to. A missing route or heading is still reported; a link outside `site.base_url`, or to a non-page file, is checked as before.
- **`#top`** — scrolls to the top of the page and needs no matching heading.
- **Fenced and commented-out links** — links inside backtick or `~~~` fences and HTML comments are skipped.
## This repository
`docs/wiki.yml` is the dogfood wiki config for this repository. It follows the same block order as the packaged scaffold, but with project-specific overrides — `graph.context.wiki` for GitHub Pages and `graph.content_predicate: schema:articleBody` for SPARQL full-text.
## Related
- [wiki](wiki.md#global-options) — `-c` and `--input` global options
- [wiki init](wiki_init.md) — scaffold a new wiki project
- [wiki check](wiki_check.md) — integrity checks
- [wiki lint](wiki_lint.md) — convention audits
- [wiki query](wiki_query.md) — ad-hoc SPARQL
- [wiki render](wiki_render.md) — inline SPARQL tables
- [wiki serve](wiki_serve.md#sparql-endpoint) — `#serve-api` config block
- [Graph Cache](Graph_Cache.md) — `--cache` and graph reuse
- [Style Guide](Style_Guide.md) — shapes and frontmatter""" .
<https://wazootech.github.io/wiki/Wiki_Configuration> <https://schema.org/headline> "Wiki Configuration" .
<https://wazootech.github.io/wiki/Wiki_Configuration> <https://schema.org/dateCreated> "2026-10-31T23:19:03Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .
<https://wazootech.github.io/wiki/Wiki_Configuration> <https://schema.org/dateModified> "2026-10-31T23:19:03Z"^^<http://www.w3.org/2001/XMLSchema#dateTime> .