pandoc-para 0.2.0__tar.gz

pandoc_para-0.2.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+*.py[cod]
+__pycache__/
+*.egg-info/
+build/
+dist/
+
+# environments
+.pixi/
+.venv/
+venv*/
+.env
+
+# tools' caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.dmypy.json
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.benchmarks/
+
+# editors and OS
+.idea/
+.vscode/
+.DS_Store
+*~
+.*.sw[po]
+*.bak
+
+# the docs' build (docs/output/, docs/.para/) is ignored by docs/.gitignore

pandoc_para-0.2.0/AUTHORS.rst

@@ -0,0 +1,5 @@
+
+Authors
+=======
+
+* Kolen Cheung - https://github.com/ickc

pandoc_para-0.2.0/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Revision history for `para`
+
+## v0.2.0
+
+A rewrite around records, output profiles and incremental builds. The package is
+`para` (on PyPI as `pandoc-para`), the site generator `para.site` (`from para.site
+import Config, cli`); the command is `parasite`.
+
+- **Configuration:** a site is configured by `parasite.toml`, merged over
+  `para/defaults.toml`, which documents every key. A site's `run.py` is no longer
+  needed (see the docs' migration page).
+- **Pipeline:** sources are read into records (URL, title, dates, category, tags,
+  description, search text, links, citations, outputs, media). Listings, feeds, the
+  sitemap, search and the post graph come from records, and every file goes through one
+  output tree. That tree refuses two producers of one path, writes only changed bytes,
+  and reports or prunes (`--prune`) what the build no longer produces.
+- **Incremental builds:** a record store (`.para/store.sqlite`). A source is read again
+  only when its bytes, the site's code, pandoc, config, or a file its read touched
+  changed; `--full` ignores the store.
+- **Output profiles:** a source has an output per profile (`format: [html, slides]`).
+  Content for some outputs uses Quarto's `.content-visible`/`.content-hidden`, and an
+  output can have its own metadata (`format: NAME: metadata:`) and pandoc variables.
+  Also `output-file`, and `format-links` with a profile's `label`.
+- **PDF output:** a `pdf` profile, Typst by default, dated by the page, so a PDF is the
+  same from build to build.
+- **Languages:** BCP 47 tags, with lookups from the most specific to the least.
+  Translations: `x.LANG.md` beside `x.md`, or made by OpenCC
+  (`pandoc-para[opencc]`), linked with `hreflang`.
+- **Filters by name:** Python (`module:function`) or installed Lua filters, chosen per
+  document with `filters: [name, -name]`.
+- **Media:** copied by reference (`[media.folders]`): only what pages use. After the
+  build, lychee checks every link offline, and the build fails on broken ones.
+- **Search:** Pagefind (`pandoc-para[search]`), indexing the records in the site's
+  language, with tags and categories as filters, deterministic from build to build.
+- **Post graph:** `graph.json`, a local graph on each page, and `/graph/` (needs
+  `pandoc-para[graph]`, paragraphic ≥ 0.2).
+- **Listings:** `description` instead of teasers, falling back to `subtitle`. The front
+  page shows the newest posts, with an archive by year. Categories form a tree, and
+  feeds carry the newest posts. Copyright years come from the pages' own dates.
+- **Removed:** parsl (now a thread pool, `--jobs`), urlpath, tipuesearch,
+  previous/next links, and the retired front-matter keys (`status`, `previewimage`,
+  `slug`, …; para.site warns).
+- **Output:** well-formed XHTML; pandoc ≥ 3.11's `--math-method`.
+- **Requirements:** Python ≥ 3.12 and pandoc ≥ 3.1.
+
+## v0.1.0
+
+First release and proof of concept.

pandoc_para-0.2.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2021, Kolen Cheung
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pandoc_para-0.2.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.5
+Name: pandoc-para
+Version: 0.2.0
+Summary: para.site: a pandoc-first static site generator
+Project-URL: Homepage, https://github.com/ickc/parasite
+Project-URL: Repository, https://github.com/ickc/parasite
+Author-email: Kolen Cheung <christian.kolen@gmail.com>
+License-Expression: BSD-3-Clause
+License-File: AUTHORS.rst
+License-File: LICENSE
+Keywords: pandoc,static site generator
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.12
+Requires-Dist: custom-inherit>=2.4
+Requires-Dist: defopt>=7
+Requires-Dist: feedgen>=1
+Requires-Dist: panflute<2.4,>=2.3.1
+Provides-Extra: extras
+Requires-Dist: coloredlogs>=14; extra == 'extras'
+Requires-Dist: livereload>=2; extra == 'extras'
+Requires-Dist: watchdog>=2; extra == 'extras'
+Provides-Extra: graph
+Requires-Dist: paragraphic<0.3,>=0.2; extra == 'graph'
+Provides-Extra: opencc
+Requires-Dist: opencc>=1.1; extra == 'opencc'
+Provides-Extra: search
+Requires-Dist: pagefind[bin]>=1.5; extra == 'search'
+Provides-Extra: tests
+Requires-Dist: coverage; extra == 'tests'
+Requires-Dist: pytest; extra == 'tests'
+Requires-Dist: pytest-cov; extra == 'tests'
+Description-Content-Type: text/markdown
+
+# para.site
+
+A pandoc-first static site generator: websites from documents pandoc can read, with
+listings, categories and tags, feeds, a sitemap, search, a graph of how the pages link,
+and builds that redo only what changed. A site is configured by one file,
+`parasite.toml`.
+
+The Python package is `para` (on PyPI as `pandoc-para` for now: `pip install
+pandoc-para`), the site generator its module `para.site`, and the command `parasite`:
+
+```python
+from para import site
+```
+
+Documentation: <https://ickc.github.io/parasite/> (its source is `docs/`, built with
+para.site).
+
+## Develop
+
+```sh
+pixi run test
+make docs
+```
+
+## Licence
+
+BSD-3-Clause.

pandoc_para-0.2.0/README.md

@@ -0,0 +1,27 @@
+# para.site
+
+A pandoc-first static site generator: websites from documents pandoc can read, with
+listings, categories and tags, feeds, a sitemap, search, a graph of how the pages link,
+and builds that redo only what changed. A site is configured by one file,
+`parasite.toml`.
+
+The Python package is `para` (on PyPI as `pandoc-para` for now: `pip install
+pandoc-para`), the site generator its module `para.site`, and the command `parasite`:
+
+```python
+from para import site
+```
+
+Documentation: <https://ickc.github.io/parasite/> (its source is `docs/`, built with
+para.site).
+
+## Develop
+
+```sh
+pixi run test
+make docs
+```
+
+## Licence
+
+BSD-3-Clause.

pandoc_para-0.2.0/docs/makefile

@@ -0,0 +1,15 @@
+# para.site's documentation, built with para.site (pandoc, and para with its search extra)
+
+.PHONY: docs serve clean
+docs: pages/reference.md
+	parasite
+
+# every key, from para.site's own defaults
+pages/reference.md: ../src/para/defaults.toml
+	python -c 'import sys; src = open(sys.argv[1]).read(); open(sys.argv[2], "w").write("---\ntitle: Every key\ndescription: para.site\x27s defaults.toml, which a site\x27s parasite.toml is merged over.\n---\n\n<!-- written by docs/makefile from src/para/defaults.toml: do not edit -->\n\nA site\x27s `parasite.toml` is merged over this file (see [parasite.toml](../configuration/)).\n\n```toml\n" + src + "```\n")' $< $@
+
+serve: docs
+	python -m http.server --directory output 8000
+
+clean:
+	rm -rf output .para

pandoc_para-0.2.0/docs/pages/builds.md

@@ -0,0 +1,89 @@
+---
+title: How it builds
+description: Read, record, derive, render, write; and only what changed.
+---
+
+# The steps
+
+1. **Discover** the sources of each collection.
+2. **Read** each into a pandoc document, with the read filters.
+3. **Record** it: a small summary of the page (URL, title, dates, category, tags,
+   description, search text, links, citations, its outputs, the media it uses).
+4. **Derive** what crosses pages from the records alone: listings, categories, tags,
+   the archive, feeds, the sitemap, search, the graph, the site's copyright years.
+5. **Render** each page in each of its profiles, and the derived pages. A page's
+   document is dropped once rendered.
+6. **Write**: every file through one output tree.
+
+Pages are read and rendered in a thread pool: most of the work is pandoc, in its own
+processes.
+
+# Only what changed
+
+The records are kept in `.para/store.sqlite` (ignore it in git). A build reads a source
+again only when its **read key** changed, and renders a page again only when its
+**render key** changed or a file it produced is gone:
+
+- the **site key**: the code (the Python modules loaded, the installed packages,
+  para's own files), pandoc and its data folder, the configuration, and the files
+  the configuration names for every page (`[read]`'s `--metadata-file` and the like,
+  the profiles' own templates, `pandoc-crossref.yaml`). Any change here reads everything
+  again;
+- a **read key**: the site key and the source's bytes. And a record is used only while
+  the files its read touched are unchanged: its links' and images' files (or that they
+  were missing), the media it references and what those reference, its bibliography and
+  style if it cites, a translation's primary, and the files and folders its text names
+  (a table's CSV, a gallery's folder). So a bibliography edit reads again the pages that
+  cite, and a new photo the page whose gallery has it. A filter that reads a file the
+  document does not name can say so with `para.deps.touch(path)`;
+- a **render key**: the read key, the page's copyright years, its link to a report and
+  its translations.
+
+A derived page is rendered again when its document changed. `parasite --full` ignores
+the store. A rebuild with nothing changed takes about a third of a second for a site of a
+hundred pages.
+
+# The output tree
+
+Every file has one producer: a page, a derived page, a copied folder, a minified bundle,
+a medium, a site-wide file. Two producers of one path is an error. A file is written
+only when its bytes change, so an unchanged page keeps its modification time. Files in
+the output folder that no step produced (a deleted page's) are reported, and removed
+with `parasite --prune`.
+
+# Media
+
+`[media.folders]` are copied **by reference**: only the files the pages use, from their
+images and links, raw HTML (`src`, `href`, `data`, `poster`, `url(…)`), their `image`,
+and what those files use in turn (an HTML plot's scripts, an SVG's images, a style
+sheet's). `[files]` are copied whole.
+
+Media in a source itself (a notebook's outputs) are written next to the page; a PDF
+image becomes SVG, which a browser can show.
+
+# Search
+
+With `[search] enabled` and `pandoc-para[search]` installed, para.site indexes the
+records with [Pagefind](https://pagefind.app/) and makes the search page (`[search]
+page`). The index is sharded: one more page changes a few of its files. The search box
+in the navigation sends `?q=` to it. Every page is indexed in the site's language
+(Pagefind searches the index of the search page's language only). Tags and categories
+are its filters, and a page's tags are searched as its words.
+
+# Links
+
+With [lychee](https://lychee.cli.rs) installed, para.site checks the output's links when
+the build is done, offline: every link and media reference from the site's files to its
+files must resolve, or the build fails (the output is written either way; a build that
+serves or watches only logs them). This guards the media copied by reference: a
+reference para.site did not see would be a broken link here. lychee reads the HTML, raw
+HTML and `<style>` elements included, but not `style` attributes or CSS files.
+
+Links known to be broken are excluded by `[check] exclude`, regular expressions of
+URLs (a site's file is a `file://` URL); `[check] links = false` turns the check off.
+
+# The post graph
+
+With `[graph] enabled` and `pandoc-para[graph]` installed, para.site writes `graph.json`
+from the records (links, citations, external links, a page's other outputs) and the
+`/graph/` page; every page gets a graph of its neighbours.

pandoc_para-0.2.0/docs/pages/configuration.md

@@ -0,0 +1,57 @@
+---
+title: parasite.toml
+description: A site's configuration, as data.
+---
+
+A site is a folder with a `parasite.toml`. `parasite` builds the site in the working
+directory from it.
+
+# Merged over the defaults
+
+para.site has a `defaults.toml`, which documents every key: see [every key](../reference/).
+A site's `parasite.toml` is merged over it:
+
+- tables, key by key: a site writes only what differs;
+- anything else (strings, numbers, lists) replaced whole;
+- `[files]`, `[media.folders]`, `[minify.css]` and `[minify.js]` replaced whole too, as
+  they list a site's own entries;
+- `[filters]` in the site's order: its filters first, then the defaults it does not
+  mention.
+
+# The parts
+
+| table | what |
+|---|---|
+| `[site]` | URL, title, description, author, language, time zone, logo, copyright, output folder, drafts |
+| `[listing]` | the front page, categories, tags and the archive, or none |
+| `[feeds]`, `[sitemap]`, `[search]`, `[graph]` | what else is written |
+| `[[sources]]` | collections: folders of sources, their extensions, whether they are listed posts, their output profiles |
+| `[read]`, `[read.EXT]` | pandoc's options for reading, for every source and per input format |
+| `[filters.NAME]` | the filters a site may use (see [filters](../filters/)) |
+| `[profiles.NAME]` | output profiles: writer, template, URL rule, options, filters, the page's parts (see [output profiles](../profiles/)) |
+| `[files]` | folders of site files, copied whole |
+| `[media.folders]` | folders of media, copied by reference: only what pages use |
+| `[minify.css]`, `[minify.js]` | style sheets and scripts bundled and minified |
+| `[mathjax]` | MathJax's configuration, as a table |
+
+# In strings
+
+`{root}` becomes the relative path from the page to the site's root (`..`, `../..`, or `.`
+at the top), and `{years}` the copyright years (a post's own, from its `date` to its
+`date-modified`; a page without dates has the site's). The footer also has `{author}`
+and `{email}`. No other braces are touched, so scripts need no escaping.
+
+# By language
+
+A string can instead be a table by language, used for the page's `lang`:
+
+```toml
+[site]
+lang = "zh_tw"
+title = { en = "KcIc", zh_tw = "祺" }
+```
+
+# On the command line
+
+The settings that are fields of the build (`parasite --help`) can be overridden there,
+for one build: `parasite --include-draft`, `parasite --full`, `parasite --prune`.

pandoc_para-0.2.0/docs/pages/filters.md

@@ -0,0 +1,67 @@
+---
+title: Filters
+description: The code a site runs, named in its parasite.toml.
+---
+
+A site lists the filters it may use in `[filters.NAME]`, in the order they run. A filter
+is code from something you installed, never a path in the site: Python, a function
+taking and returning a panflute document named as an importable `module:function`; or
+Lua, by name, found where packages install Lua filters (the environment's
+`share/pandoc/filters/`, as pandoc-forge's packages do) or in pandoc's user data
+directory.
+
+```toml
+[filters.amsthm]
+lua = "amsthm"
+default = true
+
+[filters.pannb]
+python = "pannb:main"
+inputs = ["ipynb"]
+default = true
+
+[filters.texp]
+python = "texp.panflute_filter:main"
+```
+
+| key | meaning |
+|---|---|
+| `python` | the function, `module:function` |
+| `lua` | the Lua filter's name (`amsthm` is `amsthm.lua`) |
+| `at` | `"read"` (the default): after reading, for every output; `"render"`: for an output whose profile names it in its `filters`, or of a document that names it |
+| `inputs` | a read filter for these input formats only (extensions without the dot) |
+| `default` | a read filter runs on every document |
+
+A document chooses among them with Quarto's key, by name:
+
+```yaml
+filters: [texp, -pantable]
+```
+
+turns `texp` on and `pantable` (a default) off. A name the site does not list fails that
+page, with a message saying where to add it; a path is refused. The filters run in the
+site's order, not the document's, so two documents with the same filters run them the
+same way.
+
+Read filters run after pandoc's own (the `--filter` and `--citeproc` of
+`[read] options`), Lua ones in a pandoc call of their own. A Lua render filter runs in
+the call that writes the output, after the Python ones, so that `FORMAT` is the
+output's.
+
+para.site's own: `lightgallery-from-dir` (read: a gallery from a folder of photos),
+`lightgallery` and `mathjax-bold-ell` (render: MathJax has no bold ℓ, so
+`\mathbf{\ell}` is written `\pmb{\ell}` in HTML).
+
+pandoc's JSON filters (pandoc-crossref) and citeproc are pandoc options: put them in
+`[read] options`. WebAssembly filters are planned.
+
+# From other tools
+
+Each has its own key for a document's filters; para.site reads none of them yet:
+
+| tool | key |
+|---|---|
+| Quarto | `filters:`, names or paths, with `at:` for the stage |
+| panflute | `panflute-filters:`, with `panflute-path:` |
+| panzer | `style:`, naming a set of filters defined elsewhere |
+| pandocomatic | `pandocomatic_:` |

pandoc_para-0.2.0/docs/pages/front-matter.md

@@ -0,0 +1,38 @@
+---
+title: Front matter
+description: The keys para.site reads from a document's metadata.
+---
+
+A document's metadata is pandoc's: YAML front matter in Markdown, the first raw cell of a
+notebook. pandoc's own keys keep pandoc's meaning; where Quarto has the same idea,
+para.site uses Quarto's name.
+
+| key | meaning |
+|---|---|
+| `title`, `subtitle`, `author`, `abstract` | pandoc's |
+| `lang` | the page's language, a BCP 47 tag (see [languages](../languages/)); a translation's comes from its file name |
+| `date` | when it was first published; a post needs one. An ISO 8601 date or date-time, in the site's time zone unless it says otherwise |
+| `date-modified` | when its content last changed, by hand. A post's copyright runs from `date` to `date-modified` |
+| `description` | one or two plain sentences, for listings, `<meta name="description">` and search; shown under the title. Without one, the `subtitle` is used |
+| `category` | one per post, a path (`so-uk/meetings`). It defaults to the source's folder, so it is rarely written; a category lists its subcategories' posts too |
+| `tags` | a list; each tag has a page |
+| `draft: true` | built only with `--include-draft`, and never listed |
+| `image`, `image-alt` | its thumbnail in listings, from the site's root, and the thumbnail's text (else the title) |
+| `format` | its output profiles (see [output profiles](../profiles/)) |
+| `format-links` | which of its other outputs an output links to, by each profile's `label`: `true` all, `false` none, or a list of profile names. Without it, slides link to the page beside them (Report) |
+| `output-file` | an output's file name, in its folder, as an exception to the URL rules: at the top level the first output's, under `format: NAME:` that output's |
+
+# Keys from parasite ≤ 0.1
+
+para.site warns about these and otherwise ignores them:
+
+| key | instead |
+|---|---|
+| `<!-- more -->` (a teaser) | `description` |
+| `status: draft` | `draft: true` |
+| `status: featured` | nothing: the front page shows the newest posts |
+| `previewimage` | `image` |
+| `slug`, `pretty_url`, `url_type` | the source's path |
+| `type` | nothing |
+| `sidebar_toc` | `toc` |
+| `temp` | nothing |

pandoc_para-0.2.0/docs/pages/index.md

@@ -0,0 +1,63 @@
+---
+title: para.site
+subtitle: A pandoc-first static site generator
+---
+
+para.site builds websites from documents pandoc can read: Markdown, Jupyter notebooks,
+and anything else pandoc has a reader for. Its documents, metadata and templates are
+pandoc's own. It adds what a site needs around them: listings, categories and tags, an
+archive, feeds, a sitemap, search, a graph of how the pages link, and builds that redo
+only what changed.
+
+The Python package is `para` (on PyPI as `pandoc-para` for now), the site generator is
+its module `para.site`, and the command is `parasite`:
+
+```python
+from para import site
+```
+
+# Why
+
+- **pandoc first.** No syntax of its own: no shortcodes, no extensions to Markdown.
+  A source is a pandoc document; its options are pandoc's options.
+- **Configured as data.** A site is described by one file, `parasite.toml`. Code runs
+  only as filters you named, from packages you installed.
+- **One source, several outputs.** A talk can be a page and its slides, from one file
+  (see [output profiles](profiles/)).
+- **Incremental.** A build reads and renders only what changed; a rebuild with nothing
+  changed takes a fraction of a second (see [how it builds](builds/)).
+- **Valid XHTML.** Every page is well-formed.
+
+# A site in a minute
+
+A folder with a `parasite.toml`:
+
+```toml
+[site]
+url = "https://example.org/"
+title = "My site"
+author = "Me"
+```
+
+and Markdown files under `posts/` (dated, listed) and `pages/` (not listed):
+
+```markdown
+---
+title: Hello
+date: 2026-10-11
+tags: [hello]
+---
+
+The first post.
+```
+
+Then, in that folder:
+
+```sh
+parasite
+```
+
+writes the site to `output/`. `parasite --help` lists what the command line can
+override.
+
+These pages are themselves built with para.site: see `docs/` in its repository.

pandoc_para-0.2.0/docs/pages/install.md

@@ -0,0 +1,46 @@
+---
+title: Install
+---
+
+::: note
+On PyPI the distribution is `pandoc-para` for now (the name `para` is requested); it
+installs the package `para` and the command `parasite`.
+:::
+
+para.site needs Python ≥ 3.12 and pandoc ≥ 3.1. pandoc is not on PyPI: install it from
+[pandoc.org](https://pandoc.org/installing.html) or conda-forge.
+
+# With pixi or conda
+
+```sh
+pixi add pandoc
+pixi add --pypi pandoc-para
+```
+
+# With pip
+
+```sh
+pip install pandoc-para
+```
+
+# Optional parts
+
+| extra | for |
+|---|---|
+| `pandoc-para[search]` | search, with [Pagefind](https://pagefind.app/) (its binary comes with it) |
+| `pandoc-para[extras]` | coloured logs; watching sources and serving the site while you write |
+| `pandoc-para[graph]` | the post graph, with [paragraphic](https://github.com/ickc/paragraphic) |
+
+The check of the output's links needs [lychee](https://lychee.cli.rs) (`pixi add
+lychee`; see [builds](../builds/)).
+
+Filters a site uses (pantable, pannb, …) are installed like any package, then named in
+its `parasite.toml` (see [filters](../filters/)).
+
+# From the source
+
+```sh
+git clone https://github.com/ickc/parasite
+cd parasite
+pixi run test
+```

pandoc_para-0.2.0/docs/pages/languages.md

@@ -0,0 +1,54 @@
+---
+title: Languages
+description: A site's language, a page's, and translations written beside each other or made by conversion.
+---
+
+# Language tags
+
+Languages are [BCP 47](https://www.rfc-editor.org/info/bcp47) tags, which name the
+written language: `en`, `zh-Hant` (Traditional Chinese), `zh-Hans` (Simplified), and if
+needed more specific ones, such as `zh-Hant-HK`. `[site] lang` is the site's; a page sets
+its own with `lang` in its front matter. Tags are written in any case, and `_` is read as
+`-`: Nikola's `zh_tw` is `zh-TW`, Chinese as used in Taiwan, a region rather than a
+script.
+
+A value by language, such as `title = { en = "…", zh-Hant = "…" }` or a profile's `nav`,
+is looked up from the most specific tag to the least: a page in `zh-Hant-HK` takes the
+`zh-Hant` value, then `zh`'s, then the site language's.
+
+# Translations
+
+Each of the site's other languages is a table of `[translations]`:
+
+```toml
+[site]
+lang = "zh-Hant"
+
+[translations.en]
+[translations.zh-Hans]
+convert = "hk2s"
+```
+
+**Written by hand.** `x.en.md` is the English translation of `x.md`, next to it. Its
+outputs are written beside the primary's, in the same folder: `x/index.html` and
+`x/index.en.html` (slides: `present.html` and `present.en.html`). So its relative links
+and media work as they are written in `x.md`. Front matter it does not set (the date,
+tags, category, image, `format`) is `x.md`'s; its title, description and body are its
+own. `x.en.md` without an `x.md` is a page in English, at `x/`.
+
+**Made by conversion.** With `convert`, an [OpenCC](https://github.com/BYVoid/OpenCC)
+conversion (`hk2s`, `t2s`, `tw2s`, `s2t`, `s2hk`, `s2tw`, …), each page in the site's
+language (or `from`) that has no written translation gets one: its text and metadata
+converted, its code, URLs and raw HTML left as they are. It needs `pandoc-para[opencc]`. A
+value by language the site does not give for that language (its title, the `nav`) is
+the source language's, converted.
+
+**Between them.** Each version of a page links to the others: `<link rel="alternate"
+hreflang>` in its head, and a line under the byline naming each language (`name` in its
+table, else its own name: 繁體中文, 简体中文, English, …). Listings, tag and category
+pages, feeds and the post graph show each page once, its primary version; the sitemap
+lists every version, and search every version but conversions (the same text in
+another script).
+
+Not yet: listings, feeds and search per language, as a site per language under its own
+folder; the theme's words for more languages than English and Chinese.