# Markdown Format Schema — File Format Specification
# KNO Schema Version: 0.0.6
#
# Describes Markdown as a file format for plain text formatting.
# Markdown is a lightweight markup language for creating formatted text.
#
# OFFICIAL SPECS:
#   - Original: https://daringfireball.net/projects/markdown/
#   - CommonMark: https://commonmark.org/
#   - GFM: https://github.github.com/gfm/
#
# This schema enables .kno systems to understand, process, and render Markdown.

# =============================================================================
# SCHEMA DECLARATION
# =============================================================================
$schema: kno@0.0.9

# =============================================================================
# BASIC TIER
# =============================================================================
id: 01KGK3V73KQEQ43J8FY3ANWAJD
slug: markdown-format
type: spec
version: 0.1.0

# =============================================================================
# STANDARD TIER
# =============================================================================
title: "Markdown Format Schema"
purpose: |
  Define Markdown as a file format for .kno systems.

  **What is Markdown?** Markdown is a lightweight markup language created
  by John Gruber in 2004, with significant contributions from Aaron Swartz.
  It allows you to write using an easy-to-read, easy-to-write plain text
  format, then convert it to structurally valid HTML.

  **Why .kno?** Understanding Markdown as a format enables:
  - **Content separation** — Metadata in .kno, content in .md
  - **Rendering** — Convert Markdown to HTML for display
  - **Transformation** — Extract structure (headings, links, code blocks)
  - **Validation** — Ensure Markdown follows CommonMark spec
  - **Provenance** — Track document lineage and authorship

  **Dialect Hierarchy:**
  ```
  Original Markdown (Gruber, 2004)
      └── CommonMark (standardization effort, 2014+)
              ├── GitHub Flavored Markdown (GFM)
              ├── GitLab Flavored Markdown
              └── Other extensions (MDX, Obsidian, etc.)
  ```

# =============================================================================
# RICH TIER — Relationships
# =============================================================================
provenance:
  origin:
    id: 01KGK3V73KQEQ43J8FY3ANWAJD
    timestamp: "2026-02-04T01:47:56Z"
    tool: manual-migration
taxonomy:
  topics:
    - file-formats
    - markup-languages
    - documentation
    - web-standards
  keywords:
    - markdown
    - commonmark
    - gfm
    - plain-text
    - formatting
    - documentation

relationships:
  depends_on:
    - xri: "kno://specs/kno-spec"
      reason: "Conforms to KNO format specification"

  produces:
    # Per bedrock § Bi-directional Produces Relationships:
    # Format schemas declare `produces` to their domain schema.
    # "Parsing Markdown PRODUCES a document entity"
    - xri: "kno://specs/document-schema"
      reason: "Parsing Markdown source produces document content"

  related_to:
    - xri: "kno://specs/kaml-spec"
      reason: "KAML uses YAML (related plain-text format)"
    - xri: "kno://concepts/html"
      reason: "Markdown compiles to HTML"

  enables:
    - xri: "kno://capabilities/document-rendering"
      reason: "Render .md content as HTML"
    - xri: "kno://capabilities/content-extraction"
      reason: "Extract headings, links, code blocks"
    - xri: "kno://capabilities/readme-parsing"
      reason: "Parse README.md files"

quality:
  completeness: 0.9
  last_reviewed: "2026-01-14"
  review_status: draft
  reviewed_by: "claude"

# =============================================================================
# HISTORY
# =============================================================================
_history:
  retention: full
  format: changelog

  changelog:
    - version: "0.1.0"
      date: "2026-01-14"
      author: "claude"
      summary: "Initial markdown format schema"
      changes:
        - "Created from first principles"
        - "Referenced official specs (Gruber, CommonMark, GFM)"
        - "Defined dialect hierarchy"
        - "Added format specification with elements"

# =============================================================================
# SPECIFICATION CONTENT
# =============================================================================
spec:
  status: Draft

  # ---------------------------------------------------------------------------
  # Official Standards References
  # ---------------------------------------------------------------------------
  standards:
    - name: "Original Markdown"
      url: "https://daringfireball.net/projects/markdown/"
      author: "John Gruber"
      year: 2004
      description: |
        The original Markdown syntax documentation. Defines the core
        philosophy: "Markdown is intended to be as easy-to-read and
        easy-to-write as is feasible."

    - name: "CommonMark"
      url: "https://commonmark.org/"
      spec_url: "https://spec.commonmark.org/"
      year: 2014
      description: |
        A strongly defined, highly compatible specification of Markdown.
        Resolves ambiguities in the original spec with a comprehensive
        test suite. The de facto standard for new implementations.

    - name: "GitHub Flavored Markdown (GFM)"
      url: "https://github.github.com/gfm/"
      extends: "CommonMark"
      year: 2017
      description: |
        GitHub's extension of CommonMark adding tables, task lists,
        strikethrough, autolinks, and disallowed raw HTML.

    - name: "CommonMark Spec"
      url: "https://spec.commonmark.org/0.31.2/"
      version: "0.31.2"
      description: |
        The formal specification document with examples and edge cases.
        Includes comprehensive test suite for implementers.

  # ---------------------------------------------------------------------------
  # Format Definition
  # ---------------------------------------------------------------------------
  format:
    name: "Markdown"
    mime_type: "text/markdown"
    extensions:
      - ".md"
      - ".markdown"
      - ".mdown"
      - ".mkd"
    encoding: "UTF-8"
    line_endings:
      - "LF" # Unix (preferred)
      - "CRLF" # Windows (accepted)

  # ---------------------------------------------------------------------------
  # Core Elements (CommonMark)
  # ---------------------------------------------------------------------------
  elements:
    block:
      - name: "Headings"
        syntax:
          - "# H1"
          - "## H2"
          - "### H3 ... ###### H6"
        alt_syntax: |
          H1
          ==
          H2
          --

      - name: "Paragraphs"
        syntax: "Plain text separated by blank lines"

      - name: "Block Quotes"
        syntax: "> Quoted text"

      - name: "Lists"
        syntax:
          - "- Unordered item"
          - "* Unordered item"
          - "+ Unordered item"
          - "1. Ordered item"

      - name: "Code Blocks"
        syntax:
          - "    Indented code (4 spaces)"
          - "```language\nFenced code\n```"

      - name: "Thematic Breaks"
        syntax:
          - "---"
          - "***"
          - "___"

    inline:
      - name: "Emphasis"
        syntax:
          - "*italic* or _italic_"
          - "**bold** or __bold__"
          - "***bold italic***"

      - name: "Links"
        syntax:
          - "[text](url)"
          - '[text](url "title")'
          - "[reference][id]"

      - name: "Images"
        syntax: "![alt](url)"

      - name: "Code Spans"
        syntax: "`inline code`"

      - name: "Hard Line Breaks"
        syntax: "Two spaces at line end  "

  # ---------------------------------------------------------------------------
  # GFM Extensions
  # ---------------------------------------------------------------------------
  extensions:
    gfm:
      - name: "Tables"
        syntax: |
          | Header | Header |
          | ------ | ------ |
          | Cell   | Cell   |

      - name: "Task Lists"
        syntax: |
          - [ ] Unchecked
          - [x] Checked

      - name: "Strikethrough"
        syntax: "~~deleted text~~"

      - name: "Autolinks"
        syntax: "URLs and emails auto-linked"

      - name: "Disallowed Raw HTML"
        description: "Certain HTML tags filtered for security"

  # ---------------------------------------------------------------------------
  # Usage in .kno
  # ---------------------------------------------------------------------------
  kno_integration:
    description: |
      In the .kno ecosystem, Markdown serves as the primary content format
      for documents. The separation of concerns is:

      - **Metadata** → .kno file (YAML/KAML)
      - **Content** → .md file (Markdown)

      The .kno file's `source.xri` field references the Markdown content,
      or the `content` field embeds it directly for self-contained entities.

    patterns:
      - name: "External Content Reference"
        example: |
          source:
            xri: "kno://content/docs/readme.md"
            format: markdown

      - name: "Embedded Content"
        example: |
          content: |
            # Document Title

            This is embedded Markdown content.

      - name: "Content Extraction"
        description: |
          Parse Markdown to extract:
          - Title (first H1)
          - Sections (heading hierarchy)
          - Links (for relationship inference)
          - Code blocks (for syntax highlighting)

  # ---------------------------------------------------------------------------
  # Implementation Notes
  # ---------------------------------------------------------------------------
  implementation:
    recommended_parsers:
      - name: "marked"
        url: "https://marked.js.org/"
        language: "JavaScript"
        notes: "Fast, CommonMark-compatible"

      - name: "remark"
        url: "https://remark.js.org/"
        language: "JavaScript"
        notes: "AST-based, plugin ecosystem (used by Astro)"

      - name: "markdown-it"
        url: "https://markdown-it.github.io/"
        language: "JavaScript"
        notes: "CommonMark compliant, extensible"

      - name: "pulldown-cmark"
        url: "https://github.com/raphlinus/pulldown-cmark"
        language: "Rust"
        notes: "Fast, CommonMark compliant"

    validation:
      - "Use CommonMark spec test suite for compliance"
      - "Validate UTF-8 encoding"
      - "Check for broken links (optional)"
      - "Lint for style consistency (markdownlint)"

# =============================================================================
# ANNOTATIONS
# =============================================================================
annotations:
  design_notes: |
    **Why reference official standards?**

    The ontological chain requires that format schemas trace back to
    authoritative sources. For Markdown:

    1. **Gruber's original** — Defines the philosophy and basic syntax
    2. **CommonMark** — Provides unambiguous specification
    3. **GFM** — Documents common extensions we support

    This enables:
    - Validation against known specifications
    - Clear upgrade paths as specs evolve
    - Interoperability with other Markdown tools

  historical_context: |
    Markdown was created in 2004 by John Gruber with help from Aaron Swartz.
    The name is a play on "markup" — it's a simplified markup language.

    The lack of a formal specification led to fragmentation, with many
    incompatible implementations. CommonMark (2014) addressed this by
    creating a comprehensive, unambiguous specification with test suite.

    GFM (GitHub Flavored Markdown) became the de facto standard for
    developer documentation due to GitHub's ubiquity.