Semiotic Markdown

This specification describes how Markdown files in this vault carry semantic structure. Every .md file is a sign: its frontmatter declares identity and classification, its body carries content and internal references, and the combination 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 Identity from path

Every vault file has an identity derived from its path relative to content/. The path segments encode:

• Discipline: the first path component (e.g., mathematics/, sociology/).
• Subdirectory type: the second component (e.g., concepts/, terms/, text/, specifications/).
• 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

3.1 Required fields

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 Recommended fields

• 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.
• authors (list of strings): who wrote the content.
• tags (list of strings): topical classification.
• description (string): brief summary for metadata and search indexing.

3.3 Optional fields

• date-updated (ISO 8601 string): last substantive edit.
• license (string): license declaration. If absent, the site’s default policy applies.

3.4 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 vault’s bibliography file (bibliography.bib). They are rendered as linked references when the citekey resolves.

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 text/ are papers and essays.
• Files in specifications/ are formal specifications.
• Files in curricula/ are lesson sequences.

This classification is implicit from the path and does not need to be duplicated in frontmatter.

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 identity (from path and frontmatter).
• Its classification (from directory position).
• Its content (body text, including embedded math and code).
• Its relations (wikilinks, markdown links, citations).
• Its metadata (tags, authors, dates).

The closure of a file’s relations (following links transitively) defines its semantic neighborhood within the vault.

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.