mkdocs.yml

site_name: HyperMarkDown
site_description: A strict, machine-checkable markdown dialect for project knowledge bases.

# The site's own domain, served from GitHub Pages with a custom domain rather
# than from the `ewiger.github.io/hypermarkdown/` project subpath it used
# before. The build does not need this — MkDocs emits relative links — but
# canonical URLs and `sitemap.xml` are wrong without it, and pointing them at
# the old host would keep telling search engines the subpath is canonical.
site_url: https://hypermarkdown.org/

# The header's repository link and its star count. `edit_uri` follows `main`,
# which is where the book lives now that `feat/mvp` has merged. It pointed at
# the feature branch for as long as `main` did not yet carry these files; an
# "edit this page" is only useful if it opens a file that exists on the branch
# it names, so this tracks whichever branch the site is built from.
repo_url: https://github.com/ewiger/hypermarkdown
repo_name: ewiger/hypermarkdown
edit_uri: edit/main/doc/

# No `copyright:` here on purpose. This site is `doc/`, which is CC BY 4.0,
# while the tools it documents are MIT — two claims, and `copyright:` is one
# string. The footer is `overrides/partials/copyright.html` instead, and keeping
# a setting here that the override ignores would be a second claim free to
# drift away from the first.

# The site covers the whole documentation tree, while the `[[…]]` namespace is
# restricted to `doc/wiki` by the plugin's `root` below. The book and the wiki
# build together; only the wiki is a namespace.
docs_dir: doc

# The working memory of the project, not part of the published book. `status/`
# is excluded for the same reason the issues are: it is where the work is
# argued, not what the book teaches. It holds one tracker per tool, plus one for
# the language and one for this site.
exclude_docs: |
  *.hmd
  models/
  issues/
  memory/
  status/
  proposals/TEMPLATE.md

# A card and its folder note share one URL, so directory URLs are required
# rather than merely preferred (HMD-0002 §1).
use_directory_urls: true

theme:
  name: material

  # Exactly one template is overridden: `partials/copyright.html`, which carries
  # the two-license footer. The directory is a sibling of `mkdocs.yml` rather
  # than anything under `docs_dir`, because these are theme sources and not
  # pages. Anything added here shadows a Material template of the same path, so
  # a new file is a fork of that template and has to be re-diffed on a theme
  # upgrade — worth doing rarely and on purpose.
  custom_dir: overrides

  # The bolt from the README, as a real asset rather than an emoji character —
  # `⚡` is drawn differently by every platform's font and cannot be a favicon
  # without becoming an image anyway.
  #
  # Both files carry the amber as an explicit `fill`, and neither may use
  # `currentColor`. Material references the logo as `<img src=…>` rather than
  # inlining it, and an externally-referenced SVG is an isolated document with
  # no parent to inherit from: `currentColor` there means black, which is
  # invisible on this header. Two files rather than one because they are sized
  # for different jobs, not because they are colored differently.
  logo: wiki/assets/logo.svg
  favicon: wiki/assets/favicon.svg

  font:
    text: Inter
    code: JetBrains Mono

  icon:
    repo: fontawesome/brands/github

  features:
    - navigation.sections
    - navigation.top
    - navigation.indexes
    - navigation.tracking
    # The nav is four sections, which is what a top bar is for. Each one holds
    # its pages rather than being one, so a tab is a subject and the sidebar
    # under it is that subject's chapters.
    - navigation.tabs
    - toc.follow
    - search.suggest
    - search.highlight
    - content.code.copy
    - content.tabs.link

  # Near-black chrome with an amber accent: the bolt's own color, which reads as
  # "electric" on the mark and the links without turning the site yellow.
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: black
      accent: amber
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: black
      accent: amber
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

plugins:
  - hypermarkdown:
      root: doc/wiki

# The authored nav wins everywhere except where it asks for the wiki by name.
# `hmd://wiki` is replaced by the section derived from the namespace tree, so
# the book keeps its own order and still says where the cards belong.
nav:
  - Home: index.md
  # Two subjects rather than seven pages. A flat nav made every chapter its own
  # tab, so the top bar was a table of contents and said nothing about which
  # pages belong together — a visitor had to read all seven titles to find the
  # one they wanted. `Learn` is the prose you read cold, in the order you read
  # it; `Language` is what you consult afterwards, led by the normative text.
  #
  # A section tab links to the first page beneath it, so these open on
  # `Introduction` and on the specification respectively.
  - Learn:
      - Introduction: public/introduction.md
      - Tutorial: wiki/hmd-tutorial.md
      - Features: public/features.md
      - Presentation: public/presentation.md
  - Language:
      - Language Specification: wiki/hmd-lang-spec.md
      - Namespaces: public/namespaces.md
      - Vision: public/vision.md
  - Wiki:
      - Overview: wiki/README.md
      - hmd://wiki
  # `tools/index.md` is the section's index page, under `navigation.indexes`, so
  # the tab and the sidebar heading both open it. This tab used to lead to a
  # GitHub tree listing four directories, which answers "where is the source"
  # for someone who already knows what to install and abandons everyone else.
  # The quick start is the answer to the other question: the extension, then the
  # package, and what each one gets you.
  #
  # Below it, one entry per directory under `tools/`, pointing at the source on
  # GitHub rather than at a page here. The tools document themselves in their own
  # READMEs, next to the code they describe, and a copy in the book would be a
  # second thing to keep true. Keep this list in step with `tools/` — the site
  # cannot check it, because MkDocs treats an external nav URL as opaque.
  #
  # The extension is the one exception, and deliberately: it is the only tool a
  # reader *installs* rather than reads, and an install page on GitHub is a page
  # nobody arrives at. `tools/vscode.md` is that landing page and nothing more —
  # what it is, the two install buttons, and links out. Everything that could go
  # stale stays in the extension's own README. The quick start sends installers
  # there and states nothing about the extension the page does not.
  - Tools:
      - tools/index.md
      - All tools: https://github.com/ewiger/hypermarkdown/tree/main/tools
      - hmd — Python: https://github.com/ewiger/hypermarkdown/tree/main/tools/hmd
      - hmd-ts-core — TypeScript core: https://github.com/ewiger/hypermarkdown/tree/main/tools/hmd-ts-core
      - hmd-vsc-ext — VS Code extension: tools/vscode.md
  - Roadmap: public/roadmap.md

# The numbered proposals are *internal* specifications: how the tools around the
# format are built, not what the language is. They used to occupy a
# "Specifications" tab, where they answered a question nobody visiting
# hypermarkdown.org was asking, and pushed the language's own specification out
# of sight.
#
# They stay in the build rather than being excluded, because the cover, every
# public chapter, and four wiki cards link to them with ordinary relative links.
# Excluding them would turn eighteen working links into 404s that
# `validation.links.not_found: info` below would not even report. Unlisted and
# reachable is the state that costs nothing; `not_in_nav` is how MkDocs is told
# the omission is deliberate, so it stops offering to add them.
not_in_nav: |
  proposals/

# `generator: false` drops Material's own footer credit so the license line in
# `overrides/partials/copyright.html` is the only one there — the footer is
# small enough that two claims on it read as clutter. The override keeps the
# branch this setting controls, so it still does something.
extra:
  generator: false
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/ewiger/hypermarkdown
      name: HyperMarkDown on GitHub
    - icon: fontawesome/brands/python
      link: https://pypi.org/project/hypermarkdown/
      name: HyperMarkDown on PyPI

extra_css:
  - wiki/assets/hmd.css

# Arithmatex emits `\(…\)` and typesets nothing itself, so math needs MathJax to
# be present or every formula renders as its own source. This is the only
# runtime dependency the site has on a network; the build itself stays offline.
extra_javascript:
  - wiki/assets/mathjax.js
  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js

# Cards link out to the repository — proposals, styles, source — with ordinary
# relative markdown links, by the convention in `hypermarkdown.hmd`. Those
# targets are real files but they are not site pages, so a miss is reported
# rather than fatal. Wikilinks are checked by `hmd lint`, not by MkDocs.
validation:
  links:
    not_found: info

# The "free" half of the syntax: everything the format does not own itself
# (HMD-0001 §9).
markdown_extensions:
  - admonition
  # Lets a heading carry a class, which is how the cover marks itself as the
  # one page that gets the hero treatment. There is a `custom_dir` above now,
  # but this stays authored rather than templated: a class on `<body>` would
  # mean forking `main.html` and re-diffing it on every theme upgrade, which is
  # a standing cost for a marker one page uses once.
  - attr_list
  - footnotes
  - tables
  - toc:
      permalink: true
  - pymdownx.arithmatex:
      generic: true
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde