Semiotic Markdown

This specification describes how Markdown files in this vault carry semantic structure. Every .md file is a sign that carries claims at two levels:

• Level 1 (frontmatter): Typed relations and properties declared in YAML. These are computationally checkable: the predicate graph extracts them as triplets and the satisfaction checker evaluates them against domain axioms.
• Level 2 (body text): Natural-language claims expressed in Markdown. Every sentence in a definition’s body IS a claim about the thing defined. Every step in a proof IS a claim about logical entailment. These claims are not yet machine-extractable but they are the content that Level 1 relations point to.

The combination of both levels produces a semantic fragment within the vault’s overall structure.

The specification is grounded in the Semiotic Universe formalism and the Agential Semioverse Repository directory organization. It describes what is normative about the vault’s Markdown conventions.

Normative statements use “MUST”, “SHOULD”, and “MAY” in the conventional requirements-language sense.

1. File model

A vault file is a UTF-8 .md file under the content/ directory. Each file is parsed as:

• An optional YAML frontmatter block delimited by --- at the top.
• A Markdown body.

One file corresponds to one concept. The file’s location within the directory hierarchy determines its discipline context, and its frontmatter determines its identity and classification.

2. Identification

2.1 Handles

Every vault file’s identity is its handle: the file’s path relative to content/. For example, mathematics/concepts/heyting-algebra/index.md. The handle is the node identifier in the predicate graph: it is persistent, external to the file’s semantic content, and determines which node a typed relation points to.

Handles are not arbitrary identifiers — they carry structure. The path segments encode:

• Discipline: the first path component (e.g., mathematics/, sociology/). Determines which domain axiom registry applies.
• Subdirectory type: the second component (e.g., concepts/, terms/, texts/, specifications/). Carries implicit classification.
• File stem: the filename without extension, used as the concept’s slug.

2.2 Slugification

When a string is used as an identifier (in wikilinks, aliases, or paths), slugification applies:

• Convert to lowercase and trim whitespace.
• Replace path separators with -.
• Replace characters not in [a-z0-9_-] with -.
• Collapse consecutive - into one.
• Trim leading and trailing -.

3. Frontmatter schema

Frontmatter fields divide into two categories. Metadata fields identify the page as a document artifact: who wrote it, when, what it is called. Predicates establish relations between the page and other things (concepts, pages, types) and contribute triplets to the predicate graph.

3.1 Metadata fields (required)

Every vault file MUST include:

title: "Human-readable title"
date-created: 2025-01-01T00:00:00

• title (string): the concept’s display name.
• date-created (ISO 8601 string): when the concept was created.

3.2 Metadata fields (recommended)

• aliases (list of strings): alternate names for the concept. Used by link resolution and search. SHOULD include at least a lowercase variant of the title.
• description (string): brief summary for metadata and search indexing.

3.3 Metadata fields (optional)

• date-updated (ISO 8601 string): last substantive edit.
• license (string): license declaration. If absent, the site’s default policy applies.
• status (string): editorial status (e.g. draft, stable). Optional; include when editorially meaningful.

3.4 Predicate fields

Predicate fields generate triplets. The base predicates defined by this specification:

• type (string): the content type. Values: term, concept, lesson, index, person, school, text, babble, letter, topic, skill, question, definition, theorem, proof, and others defined by domain ASR specs. The type field is the most-used predicate in the repository (2722 of 2991 pages). It determines which axiom registry applies to the page.
• authors (list of strings): who wrote the content. Produces triplets (page, authors, name).
• tags (list of strings): topical classification. Produces triplets (page, tagged, tag-name).

Additional typed relation predicates (defines, requires, cites, teaches, extends, questions, addresses, and domain-specific predicates) are specified in semantic frontmatter.

3.5 Deprecated fields

The following fields appear in older content but SHOULD be replaced:

4. Body syntax

4.1 General Markdown

The body is CommonMark-compatible Markdown. Headings, paragraphs, lists, code blocks, and inline emphasis are rendered as-is.

4.2 Wikilinks

Syntax: [[target|Target]] or [[target|Display text]]

Wikilinks are the primary internal reference mechanism. The target is resolved by matching against:

1. File stems (exact match).
2. Title fields.
3. Aliases.

Resolution is case-insensitive. The link resolution strategy (shortest path, relative path, or absolute path) is configured at the site level.

Wikilinks create semantic connections between concepts. Each wikilink from file A to file B establishes a directed relation.

4.3 Markdown links

Syntax: [text](relative/path.md) or [text](relative/path)

Internal links (those without a URI scheme) are resolved relative to the current file. External links (those with http://, https://, etc.) are rendered as-is.

4.4 Citations

Syntax: [@citekey] or [@key1; @key2]

Citations reference entries in the repository’s bibliography file (bibliography.bib, BibTeX format) using pandoc-citeproc syntax. Inline citations mark specific claims; the cites: frontmatter relation declares document-level intellectual dependencies. See the full citation specification.

4.5 LaTeX mathematics

Inline math uses $...$. Display math uses $$...$$. The renderer processes these through KaTeX or MathJax as configured.

5. Semantic structure

5.1 Directory as classification

The file’s position in the directory hierarchy carries semantic weight:

• Files in concepts/ are concept notes.
• Files in terms/ are glossary entries.
• Files in texts/ are papers and essays.
• Files in specifications/ are formal specifications.
• Files in curricula/ are lesson sequences.

This classification is implicit from the path. The type: predicate field makes the same classification explicit in frontmatter, which allows the predicate graph to route pages to their domain axiom registries.

5.2 Index files

Each directory SHOULD contain an index.md whose title describes the directory’s purpose. The index file serves as the interaction surface for the directory as a concept.

5.3 Fragment structure

A vault file’s semantic fragment consists of:

• Its handle (path relative to content/).
• Its interaction surface (the set of triplets from its predicate fields).
• Its body claims (natural-language assertions in the body text).
• Its metadata (title, dates, description).

The interaction surface is Level 1: computable, extractable, checkable against axioms. The body claims are Level 2: human-readable, not yet machine-extractable.

The closure of a file’s typed relations (following requires:, extends:, proven-by: transitively) defines its semantic neighborhood within the predicate graph.

5.4 Body-level claims

Every statement in a page’s body is a claim. A definition’s body claims what the defined term means. A theorem’s body claims what is true. A lesson’s body claims what the reader should learn.

These claims are not currently extractable by machine. Extracting them would require:

• Link analysis: which handles does the body reference (via wikilinks, markdown links, or named concepts) that do not appear in frontmatter? These are implicit requires: or cites: relations.
• Claim parsing: which sentences assert properties of the defined concept? These are implicit defines: content.
• Dependency extraction: which concepts does a proof invoke? These are implicit members of the requires: chain.

Body-level claim extraction is the path from Level 1 (frontmatter verification) to real semantic verification. The formal target is a system where every claim in the body can be traced to either a frontmatter relation or a gap that needs one.

6. Conventions

6.1 No loose files at discipline roots

Files MUST NOT be placed directly at a discipline root (e.g., mathematics/my-note.md). Create the appropriate subdirectory first.

6.2 One concept per file

Each file addresses one concept. If a file covers multiple distinct ideas, it should be split.

6.3 Cross-references

When a concept mentions another concept that exists in the vault, it SHOULD use a wikilink. First mentions of people SHOULD use full names.