CHAPTR - Markdown document builder

NAME
    chaptr - combine a document project's Markdown chapters into one output file

SYNOPSIS
    chaptr --help
    chaptr help
    chaptr init [DIRECTORY]
    chaptr init --help
    chaptr build [--config PATH] [--format {markdown,html,pdf}] [--theme NAME]
    chaptr build --help
    chaptr themes list
    chaptr themes info THEME
    chaptr themes add THEME
    chaptr themes check
    chaptr themes update THEME

DESCRIPTION
    Install the CLI once and use it with any number of document projects.
    Each project contains a YAML configuration and Markdown source files.

COMMANDS
    init
        Create an editable copy of chaptr's documentation in DIRECTORY or the current
        directory if omitted. Missing directories are created automatically.
        The default project contains the documentation sections, README.md,
        document.yaml, styles.css and a .gitignore excluding build output.
        Read README.md or build the documentation, then adapt it to your content.
        No output is rendered during init. Template selection is not supported
        yet; see the copied roadmap section for future plans.

        Existing starter files are never overwritten. Conflicts are checked
        before writing; unrelated files are kept. If a starter file already
        exists, choose a different directory. No --force option is provided.
        Initialization is noninteractive and needs no PDF dependencies.

    build
        Read the configuration, substitute variables and combine chapters in
        the listed order. HTML and PDF use CSS themes; Markdown is unstyled.
        A successful build prints the absolute path of the generated file.

    help
        Print this manual. No document project or PDF dependencies are needed.

    themes
        Browse the public catalog, install a theme into the current document
        project, check installed theme versions and update a selected theme.
        Catalog commands need an internet connection. Theme files are copied
        into themes/ under the current directory; add sets the downloaded files
        up but does not edit document.yaml. Set the theme field to use it.
        Updating replaces the downloaded theme directory. Keep personal CSS in
        the project's separate stylesheet file.

OPTIONS
    -h, --help
        Show a short command overview. Use chaptr init --help or chaptr build --help
        for command-specific usage.

    DIRECTORY (init only)
        Optional project directory to create or use. Default: current directory.
        Quote paths containing spaces.

    --config PATH
        YAML configuration to load. Default: document.yaml in the current
        directory. Paths inside it are relative to the configuration file,
        regardless of where you run chaptr.

    --format {markdown,html,pdf}
        Output format. Default: html.
        markdown produces merged source, html produces a styled browser
        document and pdf produces a printable document via WeasyPrint.

    --theme NAME
        Override the configured theme for this build. Applies to HTML and PDF
        only; ignored for Markdown. The only bundled theme is base.

CONFIGURATION
    Minimal document.yaml:

        files:
          - notes.md

    Extended document.yaml:

        title: Product Guide
        language: en
        page_size: A4
        theme: base
        stylesheet: styles.css
        output: build
        files:
          - chapters/introduction.md
          - chapters/requirements.md
        variables:
          product_name: Field Notes
          version: "1.0"

    files       Required, nonempty list of source paths in chapter order.
    title       HTML document title; default: Document.
    language    Document language tag; default: en. Polish tags enable word spacing.
    page_size   Portrait paper: A3, A4, A5, Letter or Legal; default: A4.
    theme       Named CSS theme; default: base.
    stylesheet  Optional extra CSS path, applied after the theme.
    output      Output directory; default: build.
    variables   Optional mapping of names to text, numbers or booleans.
    title_page  Generate a title page; default: false.
    subtitle    Plain-text title-page subtitle; default: empty.
    author      Plain-text title-page author; default: empty.
    front_cover Markdown or single-page PDF front cover; default: none.
    author_section Markdown file for author details; default: none.
    table_of_contents Generate linked contents; default: false.
    toc_depth   Contents heading depth, 1 to 6; default: 2.
    back_cover  Markdown or single-page PDF back cover; default: none.

DOCUMENT FEATURES
    Put Table: Caption text in a standalone paragraph directly above or below
    a Markdown table. Captioned tables are numbered across the document in source
    order. Tables without captions remain unnumbered. Use one caption per table.

    Use [^label] references and [^label]: Note text definitions for footnotes.
    Labels are document-wide. Numbered notes appear at the end with return links.

    Optional page order: front cover, title page, author section, contents,
    chapters, notes and back cover. Cover and author files use ordinary Markdown.
    Do not list them again in files. Contents include only chapter headings.
    HTML contents are linked; PDF contents include page numbers.

    Printed page numbers appear at the bottom right, starting at 1 on the author
    section. Without authors, numbering starts on contents or the first chapter.
    Front covers and title pages do not count; back covers have no generated
    number. Contents links have no underline and use printed page numbers.
    Set --page-number-content in the project stylesheet to customize the footer;
    use none to hide it. PDF page positions may differ from printed numbers.

    Title pages, contents and numbered captions are generated for HTML/PDF only.
    Merged Markdown includes authored covers and author sections and preserves
    caption and footnote source syntax.

PAPER SIZE AND LANGUAGE
    page_size sets PDF paper dimensions and the continuous HTML preview's width.
    The base uses 20mm margins; HTML includes matching padding on wide screens
    and fits smaller viewports. It does not simulate PDF page boundaries.

    Set language: pl or language: pl-PL to keep Polish single-letter words
    a, i, o, u, w and z with the following word using nonbreaking spaces.
    Uppercase forms, opening quotes and brackets and inline formatting work.
    The rule applies only to rendered text, including tables, notes and generated
    title pages and contents. Code, image descriptions and URL targets are unchanged.
    Explicit hard line breaks are preserved. Markdown output is unchanged.
    Other languages currently have no automatic single-letter spacing rule.
    language also sets the HTML lang attribute.

PDF COVERS
    Configure front_cover: covers/front.pdf or back_cover: covers/back.pdf.
    PDF builds attach those pages around the generated content using pypdf.
    Artwork and fonts are preserved without scaling or generated page margins.
    Either cover is optional and Markdown and PDF covers can be mixed.

    Each PDF cover must be unencrypted, contain exactly one page and match the
    adjacent generated page's size within one PDF point. Invalid covers fail
    before existing output is replaced. Cover files cannot be the output file.

    Inserted PDF covers do not change printed page numbering. Existing artwork
    and any numbers already in it are preserved, as are links and bookmarks.
    HTML and Markdown builds omit PDF covers. Bleed and trim setup is not provided.

VARIABLES
    Write $product_name in Markdown to insert its configured value.
    Write $$ for a literal dollar sign, for example $$20 becomes $20.
    Names contain letters, digits or underscores and cannot start with a digit.
    Undefined names stop the build with a source filename and line number.
    Values are inserted as Markdown.
    Code blocks and ordinary inline code are left unchanged.

THEMES
    CSS is applied in this order:
        1. Bundled base styling.
        2. Project themes/NAME.css or themes/NAME/NAME.css, if selected.
        3. The optional stylesheet specified in the configuration.

    To create a theme, add themes/company.css or
    themes/company/company.css and set theme: company.
    Base is the only bundled theme: black Helvetica/sans-serif text, 12pt size
    and 1.5 line spacing. Omit theme or set theme: base to use it. A local
    themes/base.css adds rules after the shared foundation. For small changes,
    use stylesheet: styles.css without creating a named theme.
    The bundled modern and vintage themes have been removed; select base or
    supply a project-local theme instead.
    Use @media print for PDF-specific rules and @page for size and margins.
    The base print layout defaults to A4, 20mm margins and a new page per chapter.
    Use page_size to change paper size and HTML preview width together.
    Relative CSS asset URLs currently resolve from the project root.

LAYOUT BLOCKS
    Classed containers wrap ordinary Markdown without enabling raw HTML:

        :::: columns columns-2-1
        ::: column
        Main text in the wider column.
        :::

        ::: column
        Reference text in the narrower column.
        :::
        ::::

    Use columns for two equal columns, columns columns-3 for three equal
    columns, columns columns-2-1 for 2/3 + 1/3 or columns columns-1-2 for
    1/3 + 2/3. Include one column block per column. Text stays in its own
    block rather than automatically flowing between columns. Narrow screens
    stack columns; print preserves their widths. Check long blocks in PDF.

    Containers align-left, align-center, align-right and align-justify align
    text. Left, center and right also position images. These classes can be
    combined, for example: ::: column align-right.
    Images fit the available width. Markdown table alignment is preserved.
    Merged Markdown output keeps the container source syntax.

COMMUNITY THEMES
    chaptr themes list          List catalog themes and current versions.
    chaptr themes info THEME    Show description, license and requirements.
    chaptr themes add THEME     Install a theme in the current project.
    chaptr themes check         Report available updates for installed themes.
    chaptr themes update THEME  Replace one installed theme with its latest version.

    Installed versions are recorded in each theme directory. Updates replace
    downloaded files, so keep local overrides in the project's stylesheet.
    Themes copied into a project by hand are not managed by these commands.
    The catalog is hosted at github.com/clkjunk/chaptr-themes. Builds work
    offline after the theme files have been installed.

OUTPUT
    The selected output directory receives one file per build:
        document.md     --format markdown
        document.html   --format html
        document.pdf    --format pdf

    Rebuilding a format replaces its existing file. Other formats are untouched.
    Open HTML directly in a browser.

PDF REQUIREMENTS
    The pdf extra includes WeasyPrint and pypdf for PDF cover assembly.
    Developer installation from the application repository:
        python -m pip install -e ".[pdf]"

    WeasyPrint also requires native libraries, including Pango. Installing the
    Python package alone may not be sufficient. Platform installation guide:
        https://doc.courtbouillon.org/weasyprint/stable/first_steps.html#installation

    If native libraries are missing, PDF builds fail; HTML and Markdown still
    work. Install and update chaptr through pip.

EXAMPLES
    Create a document project and build its documentation:
        chaptr init my-document
        cd my-document
        chaptr build

    Initialize an existing directory or a path containing spaces:
        chaptr init
        chaptr init "My Document"

    Build HTML from the current document project:
        chaptr build

    Build its PDF:
        chaptr build --format pdf

    Build a project from another directory, including a path with spaces:
        chaptr build --config "C:/Documents/Product Guide/document.yaml" --format pdf
        chaptr build --config /home/user/product-guide/document.yaml --format pdf

    Export merged Markdown or select another theme:
        chaptr build --format markdown
        chaptr build --theme base

    Browse and install community themes from a document project directory:
        chaptr themes list
        chaptr themes add roleplaying
        chaptr themes check

EXIT STATUS
    0   Success, including help output.
    1   Initialization or build failure, such as existing starter files, invalid
        configuration, missing files or variables, unknown themes or missing
        PDF renderer dependencies.
    2   Invalid command-line usage, such as an unknown option or format.

LIMITATIONS
    Build trusted local projects only: PDF rendering may read files or fetch URLs.
    Raw source HTML and mathematical notation are not supported.
    Substitution does not yet preserve multiline inline code.
    Cross-file Markdown links are not converted into internal document links.
    Footnotes are collected at the document's end, not at each PDF page's bottom.
    HTML/PDF resolve relative image and link paths against their source chapter.
    HTML uses local file references, which must remain available. Merged Markdown
    retains source link paths, which may require adjustment after merging.
    Browser and WeasyPrint CSS support differ; test print styling in actual PDF.