mkdocs.yml

site_name: teach
site_description: "Educational materials: lessons and reference guides for self-study"
# Without this, every `<loc>` in sitemap.xml is written as "None" and no page
# gets a canonical link, so the seven locales compete as duplicates of each
# other. The theme emits no per-page hreflang tags either way; the sitemap
# carries the alternates.
site_url: https://tokencemetery.github.io/teach/
repo_url: https://github.com/TokenCemetery/teach
# The theme footer links each page back to its source. MkDocs guesses
# `edit/master/docs/` for a GitHub repository, and this one has neither that
# branch nor that directory, so every link would 404.
edit_uri: edit/main/learning/
copyright: Copyright &copy; 2026 Token Cemetery
docs_dir: learning
site_dir: site

theme:
  name: primer
  # The footer's social row, on this site so that the option is exercised by
  # every build rather than only described in the reference.
  social:
    - service: github
      link: https://github.com/TokenCemetery/teach

# Corrects mkdocs-section-index: drops one false-positive warning so
# `--strict` stays usable, stops the plugin folding the first page of a
# section that has no overview page to fold, and keeps a folded page's own
# front-matter title. See the docstrings in hooks.py.
hooks:
  - hooks.py

markdown_extensions:
  # Lessons collapse their answer keys into `<details markdown="1">`. Without
  # this, Python-Markdown passes the block through raw and the answer renders
  # as literal markdown: backticks, bold and all.
  - md_in_html
  # A `<details>` block interrupts the surrounding ordered list, so every
  # Practice item restarted at "1.". This carries the number across the break.
  - sane_lists
  # GitHub renders a single newline as a line break; Python-Markdown folds it
  # into the paragraph. That collapsed every lesson's header block, every
  # glossary definition and the worked calculations in answer keys. Match
  # GitHub, since the same files are read in both places. Safe here because no
  # prose in `learning/` is hard-wrapped, checked before enabling.
  - nl2br
  # The theme ships Pygments stylesheets but nothing was emitting Pygments
  # markup, so every code block rendered unhighlighted.
  - pymdownx.highlight
  # Without the custom fence, superfences claims every ```mermaid block and
  # hands it to Pygments, so the diagram ships as highlighted source. The
  # `div` formatter is the one for a non-Material theme, and the class it
  # emits is what the theme's own `.markdown-body .mermaid` rules style.
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:mermaid2.fence_mermaid
  # GitHub puts a hover anchor beside every heading, and the same files are
  # read there. The theme draws the octicon itself, so the permalink text
  # stays empty and no stray glyph reaches the search index.
  - toc:
      permalink: ""
      permalink_class: anchor
      permalink_leading: true

plugins:
  - search:
      # MkDocs does not ship wordcut.js, required by its Hindi Lunr adapter.
      # Keep Hindi pages in the shared index without loading the broken adapter.
      # lang: [en, es, zh, pt, ru, fr]
  # Nav comes from learning/.nav.yml. Must run before section-index, which
  # rewrites the nav it produces.
  - awesome-nav
  - i18n:
      docs_structure: suffix
      # Do not let i18n re-add Hindi to the search adapter list above.
      reconfigure_search: false
      # `theme.locale` per language is what switches the theme's own chrome
      # (Search, Back to top, Previous/Next) to that language. The plugin sets
      # it automatically only for the themes MkDocs itself ships, so a
      # third-party theme needs it spelled out.
      #
      # `en` is listed last on purpose. One build pass runs per language, and
      # the two pages that exist once for the whole site, 404.html and
      # search.html, are rewritten by every pass, so the last language wins
      # them. Putting the default language last leaves those two in English.
      # The theme sorts the language selector itself, so this does not affect
      # its order.
      languages:
        # No translated content exists yet (no *.es.md etc. files), so these
        # locales only re-render the English pages once per language at ~9x
        # the build cost for no translation value. Commented out, not
        # removed: uncomment a locale once its content is actually
        # translated.
        # - locale: es
        #   name: Spanish
        #   build: true
        #   theme:
        #     locale: es
        # - locale: zh
        #   name: Chinese
        #   build: true
        #   theme:
        #     locale: zh
        # - locale: hi
        #   name: Hindi
        #   build: true
        #   theme:
        #     locale: hi
        # - locale: pt
        #   name: Portuguese
        #   build: true
        #   theme:
        #     locale: pt
        # - locale: ru
        #   name: Russian
        #   build: true
        #   theme:
        #     locale: ru
        # - locale: fr
        #   name: French
        #   build: true
        #   theme:
        #     locale: fr
        - locale: en
          default: true
          name: English
          build: true
          theme:
            locale: en
  # Every workspace's overview lives in its README.md. Without this the
  # section label and the overview are two separate nav rows; with it the
  # label itself links to the overview.
  - section-index
  # Sets page.meta.git_revision_date_localized, which the theme footer prints
  # as "Last updated". Nothing in `learning/` carries a hand-written date.
  - git-revision-date-localized:
      # A shallow clone has no log for a page; fall back rather than fail.
      fallback_to_build_date: true
      enable_creation_date: true
  # Draws the ```mermaid fences. Listed last because it injects its loader in
  # `on_post_page`, and i18n rebuilds the page once per language above.
  #
  # The version is pinned for the same reason the theme is: mermaid changes
  # its default layout between releases, and the diagrams here are checked
  # against one of them. The plugin fetches this exact build from unpkg and
  # verifies the URL resolves at build time, so a bump is a visible change.
  - mermaid2:
      version: 10.4.0

  # Last: it rewrites the HTML every other plugin produced.
  - minify:
      minify_html: true
      minify_js: true
      minify_css: true

exclude_docs: |
  **/NOTES.md
  **/learning-records/