lhtml-site 1.0.0__py3-none-any.whl

lhtml_site/browser.py

@@ -0,0 +1,59 @@
+"""The headless browser of the generator: the Chromium of Playwright for
+Python, run by the PDF export (lhtml_site/pdf_export.py), the layout report
+and --render (lhtml_site/layout/measure.py).
+
+Playwright comes with the extra `lhtml-site[pdf]`, its browser from
+`python -m playwright install --only-shell chromium`; the configuration key
+'chrome' runs another Chrome instead.
+"""
+import importlib.util
+from contextlib import asynccontextmanager
+
+from lhtml_site.doctor import playwright_browser_command, playwright_install_command
+
+PLAYWRIGHT_MISSING = '{feature} needs {modules}: {install}, then {browser}'
+CHROMIUM_MISSING = ('The Chromium of Playwright is not installed: {browser} '
+                    '(or the configuration key chrome)')
+
+
+def installed(modules=('playwright',)):
+    return all(importlib.util.find_spec(module) for module in modules)
+
+
+def require(feature, modules=('playwright',)):
+    """Raise a RuntimeError saying how to install `modules` when one of them
+    is missing (`feature`: 'The layout report', ...)."""
+    if installed(modules):
+        return
+    raise RuntimeError(missing(feature, modules))
+
+
+def missing(feature, modules=('playwright',)):
+    """What to install for `feature`, for the way lhtml-site is installed
+    (the extra lhtml-site[pdf]: playwright and pypdf, then the browser)."""
+    return PLAYWRIGHT_MISSING.format(feature=feature, modules=' and '.join(modules),
+                                     install=playwright_install_command(), browser=playwright_browser_command())
+
+
+@asynccontextmanager
+async def chromium(chrome_path=None, args=()):
+    """A headless Chromium: the one of Playwright, or the executable
+    `chrome_path` (the configuration key 'chrome')."""
+    from playwright.async_api import Error, async_playwright
+
+    async with async_playwright() as playwright:
+        try:
+            browser = await playwright.chromium.launch(executable_path=chrome_path or None, args=list(args))
+        except Error as error:
+            if "Executable doesn't exist" in str(error):
+                raise RuntimeError(CHROMIUM_MISSING.format(browser=playwright_browser_command())) from None
+            raise
+        try:
+            yield browser
+        finally:
+            await browser.close()
+
+
+def first_line(error):
+    """The first line of what a Playwright error says (the rest is its call log)."""
+    return (str(error).strip().splitlines() or [type(error).__name__])[0]

lhtml_site/build_output.py

@@ -0,0 +1,80 @@
+"""Publish a completed build while keeping the previous output on failure."""
+from contextlib import contextmanager
+from pathlib import Path
+import os
+import shutil
+import tempfile
+import uuid
+
+
+def links_out_of(site):
+    """The links of a site a build that writes in it (--only) would write
+    through: a symbolic link leading out of it, a file with another hard
+    link (a file of the sources, `cp -al`, `rsync -H`). As (path, what it
+    reaches)."""
+    site = Path(site)
+    if not site.is_dir():
+        return []
+    real = site.resolve()
+    found = []
+    for directory, dirs, files in os.walk(site):
+        for name in dirs + files:
+            path = Path(directory) / name
+            if path.is_symlink():
+                target = path.resolve()
+                if target != real and real not in target.parents:
+                    found.append((path, target))
+            elif name in files and os.lstat(path).st_nlink > 1:
+                found.append((path, 'another hard link to the same file'))
+    return found
+
+
+@contextmanager
+def staged_site(meta, copy=False):
+    """The build in a staging directory, published when it completes.
+    `copy`: the staging directory starts as a copy of the site (a partial
+    build that must publish nothing if it is refused: --only --strict)."""
+    target = Path(meta['site_directory']).resolve()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    staging = Path(tempfile.mkdtemp(prefix='.site-build-', dir=target.parent))
+    if copy and target.is_dir():
+        shutil.copytree(target, staging, symlinks=True, dirs_exist_ok=True)
+    original = meta['site_directory']
+    meta['published_site_directory'] = target
+    meta['site_directory'] = staging
+    try:
+        yield
+        # A target may publish something else than the site it rendered: the
+        # PDF export keeps <deck>.pdf and images/, and asks for the HTML it
+        # used as an intermediate not to be published. It says so rather
+        # than deleting the directory under whatever runs next. In a project
+        # of decks or targets, the directory of the target is its own: a site
+        # published there before (--debug keeps it) goes too, it would be
+        # stale. A project of one site may have published something else
+        # there, which is kept.
+        if not meta.get('publish_site', True):
+            shutil.rmtree(staging, ignore_errors=True)
+            if meta.get('build_scope'):
+                shutil.rmtree(target, ignore_errors=True)
+        if staging.is_dir():
+            backup = target.with_name('.site-backup-' + uuid.uuid4().hex)
+            had_target = target.exists()
+            if had_target:
+                target.rename(backup)
+            try:
+                staging.rename(target)
+            except BaseException:
+                if had_target:
+                    backup.rename(target)
+                raise
+            if had_target:
+                shutil.rmtree(backup)
+    except BaseException:
+        if meta['debug'] and staging.exists():
+            meta['log'].warning(f'Failed build kept for inspection: {staging}')
+        else:
+            shutil.rmtree(staging, ignore_errors=True)
+        raise
+    finally:
+        meta['site_directory'] = original
+        meta.pop('published_site_directory', None)

lhtml_site/configuration.py

@@ -0,0 +1,354 @@
+"""User configuration, its validation, and the meta of a build."""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+import difflib
+import os
+import re
+
+from lhtml_site.filesystem import read_yaml
+from lhtml_site.structure import PRIVATE_KEYS
+
+GENERATOR_DIRECTORY = Path(__file__).resolve().parent     # the package: its code, themes/, plugins/, example/
+RENAMED_DIRECTORIES = {'theme_templates': 'themes', 'src_site_example': 'example'}   # in 3.0
+
+
+# Keys of meta set by the generator during a build (never by the configuration)
+# Plugins of the previous version that the build now runs itself: the name of
+# the file, and what it became.
+CORE_STAGES = {
+    'menu.py': "the theme's menu",
+    'title_submenu.py': 'the heading ids (configuration key title_id:)',
+    'auto_wrap.py': 'the wrapping of a page in the template of its theme',
+    'auto-wrap.py': 'the wrapping of a page in the template of its theme',
+    'redirection_first_page.py': 'the index of a site that has none',
+    'cache_video.py': "the transcoded videos (set 'cache_video_directory:' to ask for them)",
+    'generate_pdf.py': "the PDF export, a target now (targets: pdf: {theme: slides-pdf})",
+}
+
+RUNTIME_KEYS = frozenset((
+    'args', 'log', 'plugin_paths', 'config_file', 'config_directory', 'lib_directory',
+    'published_site_directory',     # the site, while the build is made in a staging directory
+    'exported',                     # the file an export wrote (lhtml_site/pdf_export.py)
+    'only',                         # --only: the build is made in the site, for some pages
+    'structure', 'built',           # all the pages of the site / those generated (lhtml_site/structure.py)
+    'previous_pages',               # --only: HTML of the pages before the build (restored if they fail)
+    'strict',                       # --strict: the check of the warnings, before the pages are kept
+    'loaded_design', 'macros',      # the design (lhtml_site/design.py) and its macros for LHTML
+    'heading_ids', 'heading_summary',   # the ids of each page / its headings (lhtml_site/headings.py)
+    'lint_findings',                # {source path: [finding]} of the generated pages (lhtml_site/lint.py)
+    'measure',                      # --only: the pages the layout report measures again
+    'source_roots',                 # the sources read by each page (lhtml_site/tracking.py)
+    'dependency_contexts', 'dependency_store', 'dependency_measure',
+    'template_dependencies',        # what each page depends on (lhtml_site/dependencies.py)
+    '_dependency_engine', '_dependency_theme_scopes',   # the same for all its pages: read once
+    'analyse_layout',               # --layout: the build runs the layout analysis (lhtml_site/layout/build.py)
+    'publish_site',                 # a target asks for its intermediate site not to be published
+    'source_map', 'feedback',       # builds for development (lhtml_site/source_map.py, lhtml_site/feedback.py)
+    'planned_slides',               # entries of the deck without a source yet
+    'export_name',                  # the name of the PDF of a deck (lhtml_site/pdf_export.py)
+    'build_scope',                  # <deck>/<target>: where its state is kept (lhtml_site/project.py)
+))
+
+
+class ConfigError(ValueError):
+    """An actionable configuration error, displayed without a traceback."""
+
+
+@dataclass(frozen=True)
+class Config:
+    # Directories: as written in the YAML, absolute Paths once load_config resolved them
+    source_directory: Path | str = 'src_site'
+    site_directory: Path | str = '.site'
+    theme: Path | str = str(GENERATOR_DIRECTORY / 'themes/webpage-frame')
+    # Extensions, and nothing else: everything a bundled theme needs to
+    # render a project written in LHTML is a stage of the build now
+    # (lhtml_site/wrap.py, lhtml_site/headings.py, lhtml_site/menu.py, lhtml_site/index_page.py), so the
+    # default is empty and a project lists only what is its own.
+    plugin: list[str] = field(default_factory=list)
+    debug: bool = False
+    title_id: bool = True
+    keywords: dict = field(default_factory=dict)
+    use_tidy: bool = False
+    line_breaks: bool = False       # 'line-breaks:' in the YAML, as LHTML spells it
+    # Page settings a custom theme needs in the site, beyond the ones the
+    # bundled themes display (lhtml_site/structure.py, PUBLIC_KEYS). Everything else
+    # an author writes in a config.yaml or a deck entry stays out of the site.
+    public_page_keys: list[str] = field(default_factory=list)
+    plugin_arg: dict = field(default_factory=dict)
+    layout: dict = field(default_factory=dict)      # options of the layout analysis (--layout)
+    cache_video_directory: Path | str | None = None
+    chrome: str | None = None
+    design: dict | str | None = None
+    deck: list | dict | str | None = None
+    # A project of several decks, each built to several targets (lhtml_site/project.py):
+    # 'directories' (each directory of the sources is a deck), and
+    # {name: {theme: directory}}, the themes resolved to Paths by load_config
+    decks: str | None = None
+    targets: dict | None = None
+
+    def to_meta(self):
+        values = asdict(self)
+        for key in ('cache_video_directory', 'chrome', 'design', 'deck', 'decks', 'targets'):
+            if values[key] is None:
+                del values[key]
+        return values
+
+
+@dataclass
+class BuildContext:
+    config: Config
+    config_file: Path
+    args: Any
+    log: Any
+    plugin_paths: list[str] = field(default_factory=list)
+    meta: dict = field(init=False)
+
+    def __post_init__(self):
+        # The state of a build: a copy, which never changes the configuration
+        self.meta = self.config.to_meta()
+        self.meta.update(config_file=str(self.config_file),
+                         config_directory=self.config_file.parent,
+                         lib_directory=GENERATOR_DIRECTORY,
+                         args=self.args, log=self.log,
+                         plugin_paths=self.plugin_paths)
+
+
+def _file_or_inline(values, key, inline_types, inline_text, config_directory):
+    """A key given as the path of a YAML file (resolved from the configuration
+    directory, must exist) or inline (mapping with string keys / list)."""
+    value = values.get(key)
+    if value is None:
+        return
+    if isinstance(value, str) and value.strip():
+        file = Path(value).expanduser()
+        if not file.is_absolute():
+            file = config_directory / file
+        if not file.is_file():
+            raise ConfigError(f"'{key}' file not found: '{file}'")
+        values[key] = str(file.resolve())
+    elif not isinstance(value, inline_types) or (isinstance(value, dict)
+                                                 and any(not isinstance(k, str) for k in value)):
+        raise ConfigError(f"'{key}' must be {inline_text} or the path of a YAML file")
+
+
+def _chrome_executable(values, config_directory):
+    """'chrome': the Chrome executable the browser runs (layout report,
+    PDF export, --render), instead of the Chromium of Playwright. A
+    relative path is resolved from the configuration directory; a macOS
+    bundle ('.app') is resolved to the executable it contains."""
+    value = values.get('chrome')
+    if value is None:
+        return
+    if not isinstance(value, str) or not value.strip():
+        raise ConfigError("'chrome' must be the path of the Chrome executable")
+    file = Path(value.strip()).expanduser()
+    if not file.is_absolute():
+        file = config_directory / file
+    if file.suffix == '.app' and file.is_dir():                 # macOS bundle
+        inside = file / 'Contents/MacOS' / file.stem
+        if not inside.is_file():
+            candidates = sorted(p for p in (file / 'Contents/MacOS').glob('*') if p.is_file())
+            if not candidates:
+                raise ConfigError(f"'chrome': no executable in the bundle '{file}'")
+            inside = candidates[0]
+        file = inside
+    if not file.is_file():
+        raise ConfigError(f"'chrome' executable not found: '{file}'")
+    if not os.access(file, os.X_OK):
+        raise ConfigError(f"'chrome' is not executable: '{file}'")
+    values['chrome'] = str(file.resolve())
+
+
+TARGET_NAME = re.compile(r'[A-Za-z][A-Za-z0-9_-]*$')
+
+
+def in_package(path):
+    """A path into a checkout of the generator as the projects write it
+    (a submodule): its themes/, plugins/ and example/ were at the root of the
+    repository, and are in its package now (src/lhtml_site/). The same path
+    in the package when it exists there, else the path unchanged."""
+    path = Path(path)
+    if path.exists():
+        return path
+    for i, part in enumerate(path.parts):
+        if part in ('themes', 'plugins', 'example'):
+            moved = Path(*path.parts[:i], 'src', 'lhtml_site', *path.parts[i:])
+            if moved.exists():
+                return moved
+    return path
+
+
+def theme_directory(value, config_directory):
+    """A theme given as a directory (relative to the configuration) or as the
+    name of a theme of the generator ('slides')."""
+    directory = Path(value).expanduser()
+    if not directory.is_absolute():
+        directory = config_directory / directory
+    if not directory.is_dir() and (GENERATOR_DIRECTORY / 'themes' / value).is_dir():
+        directory = GENERATOR_DIRECTORY / 'themes' / value
+    return in_package(directory).resolve()
+
+
+def _decks_and_targets(values, data, config_directory):
+    """'decks' and 'targets' (lhtml_site/project.py), checked, the themes resolved."""
+    if values.get('decks') is not None and values['decks'] != 'directories':
+        raise ConfigError("'decks' must be 'directories' (each directory of the sources is a deck)")
+    targets = values.get('targets')
+    if targets is None:
+        return
+    if not isinstance(targets, dict) or not targets:
+        raise ConfigError("'targets' must map a name to its settings, e.g. html: {theme: slides}")
+    if 'theme' in data:
+        raise ConfigError("'theme' and 'targets' together: give the theme of each target")
+    resolved = {}
+    for name, spec in targets.items():
+        if not isinstance(name, str) or not TARGET_NAME.match(name):
+            raise ConfigError(f"'targets': invalid name {name!r} (letters, digits, - and _)")
+        if name == 'images':
+            raise ConfigError("'targets': 'images' is where the PDF export writes the slide images; "
+                              "choose another name")
+        if not isinstance(spec, dict) or set(spec) != {'theme'} or not isinstance(spec['theme'], str):
+            raise ConfigError(f"'targets': {name}: expected {{theme: <theme>}}")
+        # its existence is checked by validate_paths, as the one of the
+        # sources: --clean needs neither
+        resolved[name] = {'theme': theme_directory(spec['theme'], config_directory)}
+    values['targets'] = resolved
+
+
+def load_config(filename, debug_override=None):
+    path = Path(filename).expanduser().resolve()
+    warnings = []
+    if not path.exists() and path.name == 'configure_default.yaml':
+        raise ConfigError("'configure_default.yaml' was renamed 'configure_example.yaml' (lhtml-site 1.0): "
+                          "update your command")
+    if not path.exists():
+        raise ConfigError(f"Configuration not found: '{path}' (run lhtml-site in the "
+                          f"directory of a project; lhtml-site init creates one)")
+    try:
+        data = read_yaml(path)
+    except ValueError as exc:                       # the message names the file
+        raise ConfigError(str(exc)) from None
+    if data is None:
+        data = {}
+    if not isinstance(data, dict) or any(not isinstance(k, str) for k in data):
+        raise ConfigError('Configuration must contain named key: value pairs')
+
+    if 'line-breaks' in data:                       # the spelling of LHTML
+        data['line_breaks'] = data.pop('line-breaks')
+    if 'plugin_post' in data:
+        raise ConfigError("'plugin_post' was removed (lhtml-site 1.0): list its plugins under 'plugin' "
+                          "(all their hooks are run)")
+    if 'level_print' in data:
+        raise ConfigError("'level_print' was removed (lhtml-site 1.0): the build prints no indented log "
+                          "(-v shows its stages)")
+    if 'include_head' in data:
+        raise ConfigError("'include_head' was removed (lhtml-site 1.0): it was read nowhere; a theme "
+                          "places what goes in <head>")
+
+    defaults = Config().to_meta()
+    known = set(defaults) | {'cache_video_directory', 'chrome', 'design', 'deck', 'decks', 'targets'}
+    for key in sorted(set(data) - known):
+        if key in RUNTIME_KEYS:
+            raise ConfigError(f"'{key}' is runtime state and cannot be set in YAML")
+        suggestion = difflib.get_close_matches(key, sorted(known), n=1)
+        hint = f" Did you mean '{suggestion[0]}'?" if suggestion else ''
+        warnings.append(f"Unknown configuration key '{key}', ignored.{hint} "
+                        f"(A plugin reads its options in 'plugin_arg'.)")
+    values = {**defaults, **{k: v for k, v in data.items() if k in known}}
+    for key in ('debug', 'title_id', 'use_tidy', 'line_breaks'):
+        if type(values[key]) is not bool:
+            raise ConfigError(f"'{key}' must be a boolean (true or false)")
+    for key in ('keywords', 'plugin_arg', 'layout'):
+        if not isinstance(values[key], dict) or any(not isinstance(k, str) for k in values[key]):
+            raise ConfigError(f"'{key}' must be a mapping with string keys")
+    for name in sorted({'params', 'page', 'credit', 'credits'} & set(values['keywords'])):
+        raise ConfigError(f"'keywords': '{name}' is reserved (Jinja variable of the generator: "
+                          f"params, the deck parameters of a page; page, its metadata; credit, credits)")
+    plugins = values['plugin']
+    if isinstance(plugins, str):
+        plugins = [plugins]
+    elif plugins is None:
+        plugins = []
+    values['plugin'] = plugins
+    for key in ('plugin', 'public_page_keys'):
+        if not isinstance(values[key], list) or any(not isinstance(v, str) or not v.strip() for v in values[key]):
+            raise ConfigError(f"'{key}' must be a list of non-empty strings")
+    for name in sorted(set(values['public_page_keys']) & set(PRIVATE_KEYS)):
+        raise ConfigError(f"'public_page_keys': '{name}' is never written into the site "
+                          f"(it is the path of the source on this machine)")
+    # The layout analysis is part of the generator, not a plugin: it is
+    # selected by --layout and configured by 'layout:'. A configuration of
+    # the previous version says so here, before the build, naming the fix.
+    for entry in plugins:
+        if entry.endswith('layout_report.py'):
+            raise ConfigError("'plugin': the layout report is no longer a plugin. Remove "
+                              f"'{entry}' from 'plugin:' and run the build with --layout")
+    if isinstance(values['plugin_arg'], dict) and 'layout_report' in values['plugin_arg']:
+        raise ConfigError("'plugin_arg': the options of the layout report moved to the "
+                          "configuration key 'layout:'. Move the content of "
+                          "'plugin_arg: layout_report:' under 'layout:'")
+    # Stages the build always runs: a project does not list them, and cannot
+    # know whether its theme has a menu - the theme declares that (theme.yaml).
+    for entry in plugins:
+        name = entry.rsplit('/', 1)[-1]
+        if name in CORE_STAGES:
+            raise ConfigError(f"'plugin': {CORE_STAGES[name]} is a stage of the build, not a "
+                              f"plugin. Remove '{entry}' from 'plugin:'")
+    if isinstance(values['plugin_arg'], dict) and 'menu' in values['plugin_arg']:
+        raise ConfigError("'plugin_arg': the extra page settings of the menu are declared by "
+                          "the theme. Move the content of 'plugin_arg: menu: keys:' to "
+                          "'toc: keys:' in the theme.yaml of your theme")
+
+    _chrome_executable(values, path.parent)
+    _decks_and_targets(values, data, path.parent)
+
+    _file_or_inline(values, 'design', dict, 'a mapping (tokens, macros)', path.parent)
+    _file_or_inline(values, 'deck', (list, dict), 'a list of slides', path.parent)
+
+    for key in ('source_directory', 'site_directory', 'theme', 'cache_video_directory'):
+        if key not in values:
+            continue
+        value = values[key]
+        if not isinstance(value, str) or not value.strip():
+            raise ConfigError(f"'{key}' must be a non-empty directory path")
+        directory = Path(value).expanduser()
+        if not directory.is_absolute():
+            directory = path.parent / directory
+        if key == 'theme':          # a directory, or the name of a theme of the generator
+            directory = theme_directory(value, path.parent)
+        elif key == 'source_directory':
+            directory = in_package(directory)
+        if key in ('source_directory', 'theme') and not directory.is_dir():
+            # the new name as the configuration writes it (a checkout: found in its package)
+            renamed = Path(*[RENAMED_DIRECTORIES.get(part, part) for part in directory.parts])
+            if in_package(renamed).is_dir():
+                raise ConfigError(f"'{key}': '{directory.as_posix()}' was renamed "
+                                  f"'{renamed.as_posix()}' (lhtml-site 1.0): update '{key}'")
+        values[key] = directory.resolve()
+    if debug_override is not None:
+        values['debug'] = debug_override
+    return Config(**values), path, warnings
+
+
+def validate_paths(config, config_file, require_inputs=True):
+    output = Path(config.site_directory).resolve()
+    inputs = [('source_directory', config.source_directory)]
+    inputs += [(f'targets: {name}: theme', spec['theme']) for name, spec in (config.targets or {}).items()] \
+        or [('theme', config.theme)]
+    for key, directory in inputs:
+        directory = Path(directory).resolve()
+        if output == directory or output in directory.parents or directory in output.parents:
+            raise ConfigError(f"Unsafe 'site_directory': output and '{key}' must not overlap ({output}, {directory})")
+        if require_inputs and not directory.is_dir():
+            raise ConfigError(f"'{key}' directory not found: {directory}")
+    protected = [config_file.resolve(), GENERATOR_DIRECTORY.resolve()]
+    if config.cache_video_directory:
+        protected.append(Path(config.cache_video_directory).resolve())
+    for path in protected:
+        if output == path or output in path.parents:
+            raise ConfigError(f"Unsafe 'site_directory': deleting '{output}' would remove '{path}'")
+    if output.exists() and not output.is_dir():
+        raise ConfigError(f"'site_directory' is not a directory: {output}")

lhtml_site/configure_example.yaml

@@ -0,0 +1,113 @@
+# configure.yaml: the configuration of a site built by lhtml-site.
+#
+# Run from this directory:
+#   lhtml-site                   build into .site/ (open .site/index.html in a browser)
+#   lhtml-site --watch           build, and rebuild on each save
+#   lhtml-site --serve --watch   the same, and a preview on http://127.0.0.1:8000/
+#   lhtml-site --check-config    check this file, without building
+#
+# Relative paths are read from this directory. A line starting with # is a
+# comment: remove the # in front of an option to use it. The options of the
+# command line (--debug, ...) take precedence over this file. Every option is
+# described in the section Configuration of the reference of lhtml-site:
+# https://github.com/drohmer/lhtml-site/blob/main/src/lhtml_site/docs/reference.md
+
+# ---------------------------------------------------------------------------
+# Essentials
+# ---------------------------------------------------------------------------
+
+# Where the pages are. A page is a file .html.j2 (LHTML) or .md.j2 (Markdown),
+# usually <name>/index.html.j2 with its images and videos next to it; the
+# pages follow the order of their paths (01_..., 02_...) unless a deck says.
+source_directory: 'src/'
+
+# Where the site is written. It is replaced at each build: never edit it.
+site_directory: '.site/'
+
+# The look of the site: a theme of the generator, or the directory of yours.
+#   webpage-frame  web pages with a navigation menu
+#   slides         slides shown in the browser (1920x1080)
+#   slides-pdf     the same slides, exported to a PDF (needs Playwright, lhtml-site[pdf]: lhtml-site doctor)
+theme: 'webpage-frame'
+
+# ---------------------------------------------------------------------------
+# Common options
+# ---------------------------------------------------------------------------
+
+# The order of the pages (of the slides of a talk): a file listing them, see
+# the section Deck of the reference. Without it, the order of their paths.
+# deck: 'deck.yaml'
+
+# Values every page can show, as Jinja variables: {{ author }}, {{ year }}.
+# keywords:
+#   author: 'Your Name'
+#   year: 2026
+
+# Your own macros and design tokens, added to those of the theme (the slides
+# themes have a design: .structure/design.md lists it after a build).
+# design:
+#   tokens:
+#     font: {small: 80%}
+#   macros:
+#     note:
+#       class: note
+#       doc: 'A remark in gray: note:: ... ::'
+#       css: '.note { color: gray; }'
+
+# The videos of the pages, converted to the formats every browser reads
+# (needs ffmpeg, and ffpb: pip install ffpb). The converted files are kept
+# in this directory.
+# cache_video_directory: 'cache_video/'
+
+# The headings get an id, so that a section can be linked, and the theme
+# lists them. Default: true.
+# title_id: true
+
+# A line break in a source is a line break in the page. Default: false (the
+# lines of a paragraph are joined).
+# line-breaks: false
+
+# ---------------------------------------------------------------------------
+# Several decks, in the browser and as a PDF
+# ---------------------------------------------------------------------------
+
+# Each directory of source_directory is a deck, built once for each target,
+# into <site_directory>/<deck>/<target>/. Takes the place of 'theme:' above
+# (remove that line).
+# decks: directories
+# targets:
+#   html: {theme: slides}
+#   pdf: {theme: slides-pdf}
+
+# ---------------------------------------------------------------------------
+# Extensions
+# ---------------------------------------------------------------------------
+
+# Transformations of the pages, in the order they run. The menu, the heading
+# ids and the template of the theme are part of the build: list only your
+# own here. Paths are relative to this file, then to the generator, which
+# comes with two:
+#   plugins/pre_include.py   text at the top of every page (shared Jinja macros)
+#   plugins/code_include.py  code of a git repository inserted in the pages
+# plugin: ['plugins/pre_include.py']
+# plugin_arg:                      # the options of each extension, by its name
+#   pre_include: ['macros.html']
+
+# ---------------------------------------------------------------------------
+# Tools
+# ---------------------------------------------------------------------------
+
+# The layout report (lhtml-site --layout, needs Playwright, lhtml-site[pdf]): where it is
+# written. The theme says which part of the page it measures.
+# layout:
+#   output: '.layout/'
+
+# The Chrome run by the PDF export, the layout report and --render, instead of
+# the Chromium of Playwright (a macOS .app is accepted).
+# chrome: '/Applications/Google Chrome.app'
+
+# Keep the intermediate files and show the tracebacks (as --debug).
+# debug: false
+
+# Clean the HTML of the pages with tidy (needs the tidy library).
+# use_tidy: false