Canonical Markdown and Structured Build Model

1. Status

This decision is Accepted. It governs how every canonical Ocean-Atlas document is authored and how builders/core discovers and validates that content.

2. Context

Ocean-Atlas needs one authoritative store for Ocean’s knowledge — DSL references, concepts, architecture, patterns, examples, decisions, and glossary terms — that can be validated by tooling, rendered by more than one presentation technology, and eventually consumed by search and retrieval systems, without becoming dependent on any one of those consumers.

That knowledge also needs to be easy for contributors to author and review using ordinary developer tools: a text editor, git diff, and a pull request — the same workflow already used for the DSL and generator source it documents.

3. Decision

Canonical knowledge is authored as plain Markdown files, each beginning with a single # title and a ## Metadata section that ends in a --- horizontal rule:

# <Title>

## Metadata

- **ID:** `<stable-id>`
- **Type:** <knowledge type>
- **Area:** <area>
- **Status:** <status>
- **Authority:** <authority>
- **Summary:** <one-sentence summary>
- **Relationships:**
  - type: <relationship-type>
    target: <stable-id>

---

<authored Markdown body>

builders/core (see adr.atlas-builder-boundary) discovers every Markdown file under the canonical knowledge directories, parses this metadata block, validates it, and normalizes it into a stable, technology-independent AtlasModel. No database, headless CMS, or bespoke document format sits between the authored file and that model.

The Markdown body remains authored prose — not HTML, not a component tree — so it stays readable and diffable independently of any renderer, and so builders/core can pass it through to different presentation adapters unchanged.

4. Alternatives Considered

4.1 A headless CMS or database-backed knowledge base

Rejected. A CMS would move canonical knowledge out of version control, away from pull-request review, and behind a runtime service that the static build would then depend on. It would also introduce its own identity, relationship, and versioning model, duplicating what Ocean-Atlas already needs to define for the DSL itself.

4.2 YAML or JSON documents instead of Markdown

Rejected as the primary authoring format. Structured data formats are easy to validate but poor for long-form prose, inline code samples, and diagrams, which make up most of Ocean-Atlas’s content. Markdown with a constrained metadata block keeps authoring close to prose while still giving the build a predictable block to parse.

4.3 YAML frontmatter instead of a ## Metadata section

Considered. Frontmatter is a common Markdown convention, but it is also the convention several static-site generators — including Starlight — attach framework-specific meaning to (layout, sidebar behavior, and so on). Using an explicit, plain-Markdown ## Metadata heading keeps the canonical metadata block visibly separate from any renderer’s frontmatter dialect, consistent with the presentation-independence goal already established by adr.atlas-builder-boundary.

4.4 Unstructured Markdown with no required metadata

Rejected. Without a required, parseable block, builders/core could not assign stable IDs, validate relationships, derive routes, or detect duplicates. Knowledge would remain human-readable but not reliably machine-consumable, which conflicts with the “Human and Machine Readability” principle in atlas.knowledge-architecture.

5. Consequences

Benefits

• Canonical knowledge is authored and reviewed with the same tools as code: a text editor, git diff, and pull requests.
• One parser (builders/core) owns metadata and relationship validation, so every presentation adapter sees already-validated input.
• The format has no dependency on any specific static-site generator, satisfying the separation established by adr.atlas-builder-boundary.
• Structured relationships make the knowledge graph explicit and machine-traversable without a separate database.

Trade-offs

• Every canonical document carries authoring overhead: a correctly formatted ## Metadata block is required before content is useful.
• Contributors must learn the metadata and relationship conventions documented in atlas.metadata-schema and atlas.identity-and-relationships.
• Richer structured queries (for example, “all Approved DSL references updated this quarter”) depend on builders/core’s normalized output rather than being answerable by reading files directly.

6. Implementation Implications

• builders/core’s parseMetadata function is the single source of truth for what counts as a valid metadata block; presentation adapters must not reimplement metadata parsing.
• New knowledge types or metadata fields are added by extending the parser and validator in builders/core, not by inventing a document-local convention.
• Generated content (builders/astro-starlight/src/content/docs/, dist/) is never hand-edited and never a source for builders/core; it is downstream output, not upstream input.

7. Validation and Compliance Rules

• A canonical document without a level-one title or a ## Metadata section terminated by --- fails the build.
• The required fields (id, type, area, status, authority, summary) must be present or the document fails validation.
• Relationship entries must resolve to an existing canonical document or published example ID, or the build fails with the offending source path and target.
• npm --prefix builders/core run audit runs this validation across the whole repository and must report zero issues before canonical content is considered complete.

8. Related Knowledge

• adr.atlas-builder-boundary — establishes the Core/adapter boundary that this decision’s parsing and validation rules serve.
• atlas.knowledge-architecture — the “Human and Machine Readability” and “Separation of Knowledge and Presentation” principles this decision implements.
• atlas.metadata-schema — the full field-level metadata contract.
• atlas.identity-and-relationships — the ID and relationship rules enforced by this build model.
• adr.search-today-structured-retrieval-tomorrow — the normalized model this build produces is what any future retrieval system must consume.

These semantic relationships are declared in the document metadata.