Skip to content

Wiki Structure and Conventions

Jump to bottom
Chris Sweet edited this page Jul 14, 2026 · 1 revision

type: reference up: "What-is-the-llm-wiki-Template" related:

Wiki Structure and Conventions

The files, frontmatter, and link conventions that make a template wiki navigable and queryable. This page is grounded in the generated SCHEMA_<project>.md, wiki/init-wiki.sh, and Edge-Types.md; defer to your project's own SCHEMA_<project>.md when in doubt, since it is the authoritative reference.

What files exist in a new wiki after init-wiki.sh?

wiki/init-wiki.sh scaffolds a namespaced wiki. In this bundle the files are:

  • Home_<project>.md — the human-facing entry point.
  • Home.md — a GitHub-wiki redirect to Home_<project>.md (never edited).
  • index_<project>.md — the catalog of all pages.
  • log_<project>.md — the append-only chronological record.
  • SCHEMA_<project>.md — the authoritative conventions reference.
  • Edge-Types.md — the typed-edge vocabulary.

The <project> suffix (here llm-wiki-KB) namespaces the special files so multiple wikis can be aggregated into a single Obsidian vault without index.md/log.md name collisions. init-wiki.sh is idempotent and auto-detects create-vs-update mode: on a fresh repo it scaffolds; on an existing wiki it patches the SCHEMA and CLAUDE.md up to current conventions. Execute it, do not reimplement it.

What is Home_<project>.md for?

The human-facing entry point: a project description plus a ## Categories section that mirrors the top-level categories in the index, with one to three representative links per category. It is a curated navigation surface, not a comprehensive catalog (that is the index's job). Update it when a new top-level category emerges or when a page significant enough to be a category's representative link lands; routine additions inside an existing category are index-only.

What is index_<project>.md for?

The content-oriented catalog: every page listed with a one-line description, organized by category. The LLM updates it on every ingest, and reads it first when answering a query to find which pages are relevant, then drills in. At moderate scale this index-first navigation replaces the need for embedding-based RAG infrastructure.

What is log_<project>.md for and how do I append to it?

The chronological, append-only record of wiki activity: ingests, queries, lint passes, updates. Each entry is a heading ## [YYYY-MM-DD] <verb> | <Subject> (verbs: ingest, query, lint, update, create), and the first bullet is always the attribution line - by: <human> via <agent>, where <human> is git config user.name in the wiki repo (read it, do not invent it). Then two to five bullets of substance. Discipline: one commit per log entry, committed separately from the page/index changes, so git blame on the log stays a faithful per-entry record. See Everyday-Operations.

What is SCHEMA_<project>.md and what does it define?

The authoritative conventions reference: page format, required and optional frontmatter, the two structured page types (analysis, decision) and their required sections, naming, cross-reference styles, the edges-as-interface-operations model, the topology-vs-content retrieval guidance, log attribution, and the Ingest/Query/Lint procedures. When any other document (including this bundle) disagrees with your SCHEMA_<project>.md, the SCHEMA wins for your project.

What is Edge-Types.md and how do I use it?

The canonical list of typed-edge predicates available in the wiki (16 forward predicates: up, source, extends, supports, criticizes, concept, partOf, dependsOn, defines, resolvedBy, incorporatedInto, outOfScopeFor, precedes, feedsInto, related, mentions). You reference it in two ways: by choosing predicates for your frontmatter, and by inline "Variant 1" annotations on body links (a content link followed by a parenthesized italic link to the predicate's anchor, e.g. [Theory X](Theory-X) ([*extends*](Edge-Types#extends))). Forward predicates are author-facing; inverse predicates (extendedBy, supportedBy, ...) are materialized by the KG pipeline, never authored by hand. See Knowledge-Graph.

What frontmatter fields are standard?

Required on every page: type: and up:. Optional and commonly used: tags: and the typed edges source:, extends:, supports:, criticizes:, related: (plus derived_from: for analysis pages and decided_at: for decision pages). The seed question also names an area: field; in this template area is not a standard authored field, tags: plays the topical-clustering role, though the KG pipeline does materialize an "area inheritance" relation derived from the LA3D ontology. Treat type, up, tags, and the typed edges as the authoring vocabulary. Rule: every page gets frontmatter, no exceptions; use type: untyped rather than skipping it.

What node (page) types are recognized?

The SCHEMA's type: vocabulary: concept, entity, source-summary, synthesis, analysis, decision, index, comparison, and untyped. Most types have no required structure beyond the general page format. Two are query-driven and do have required sections:

  • analysis — a fileable synthesis answer. Requires Question / Context / Analysis / Conclusion / Open follow-ups and a derived_from: frontmatter field.
  • decision — a design choice with rationale. Requires Question / Options considered / Decision / Rejected alternatives / Revisit triggers and a decided_at: field.

(The KG ontology's node vocabulary includes near-equivalents like Concept, Synthesis, Entity, Index, SourceSummary; the SCHEMA type: values are what you author.)

How do I link between pages?

Two notations, deliberately different by location:

  • Body text: [Display Text](Page-Name) (GitHub-wiki style). Emits a mentions edge in the graph.
  • Frontmatter edge fields: [[Page-Name]] wikilinks (Obsidian-graph compatible). Emits the typed edge named by the field.

Link concepts on first mention within a page, aim for at least two inbound and two outbound links per page, and keep links bidirectional: if A links to B, B should link back to A (typically in B's See also).

Does the difference between a wikilink and a body cross-reference matter for the graph?

Yes. The KG extractor treats them differently. A [[Page-Name]] in a frontmatter edge field carries the typed predicate of that field (extends, supports, etc.). A [Display](Page-Name) in the body emits a generic mentions edge (weighted via RDF-star). So frontmatter edges are the semantically rich, queryable relationships; body links are the navigational mesh. The inline Variant 1 annotation lets a body link also carry a typed predicate when one clearly fits. See Knowledge-Graph.

What is a hub page and how does one become a hub?

A hub is a page with many inbound links: a page others repeatedly reference. Category indexes, foundational concept pages, and heavily-cited findings become hubs naturally as the wiki grows. The KG pipeline materializes a hub flag so topology queries can find them ("which pages are the hubs of this wiki?"). You do not declare a hub; it emerges from how often other pages link to it.

What is an orphan page and how do I fix one?

An orphan is a page with no inbound links from any other page or from the index: it exists but is invisible to the wiki's normal navigation and to retrieval. Fix it by linking it in from a relevant parent or sibling page (and adding its index entry), or, if it no longer belongs, flag it for archival. Orphan detection is one of the standard lint checks.

See also

Clone this wiki locally