asciidoctor-nix(1)

Table of Contents

• Name
• Synopsis
• Description
• Usage
  • Development Environment
  • nix build
• Packages
• Examples
• See Also

Name

asciidoctor-nix - Reproducible and Deployable Asciidoctor Template

Synopsis

nix build [options] installables

Description

Reproducible and deployable Asciidoctor template based on Nix.

The latest release containing the defaultExternal package, the Gemfile.lock and gemset.nix files, and the flake.lock file are automatically updated by the .github/workflows/deploy.yml, .github/workflows/bundix_lock.yml, and .github/workflows/nix_flake_update.yml GitHub actions respectively.

If the slides are not required, feel free to revert the de19b8059c410dc49e036d681749c7f8db8d609a commit to reduce install size and compile time.

Usage

Development Environment

Enter the development environment with nix develop or direnv allow.

nix build

nix build builds the specified installables. Installables that resolve to derivations are built (or substituted if possible). Store path installables are substituted.

Unless --no-link is specified, after a successful build, it creates symlinks to the store paths of the installables. These symlinks have the prefix ./result by default; this can be overridden using the --out-link option. Each symlink has a suffix -<N>-<outname>, where N is the index of the installable (with the left-most installable having index 0), and outname is the symbolic derivation output name (e.g. bin, dev or lib). -<N> is omitted if N = 0, and -<outname> is omitted if outname = out (denoting the default output).

— nix3-build(1)
https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-build.html

Packages

Package	Description
default	Compiles the docbook, html, manpage, pdf, presentationExternal, and presentationLocal packages.
defaultExternal	Compiles the docbook, html, manpage, pdf, and presentationExternal packages.
defaultLocal	Compiles the docbook, html, manpage, pdf, and presentationLocal packages.
docbook	Compiles the DocBook at result/share/doc/main.xml.
html	Compiles the HTML at result/share/doc/index.html.
manpage	Compiles the manpage at result/share/man/man7/main.7.gz.
pdf	Compiles the PDF at result/share/doc/main.pdf.
presentationExternal	Compiles the presentation at result/share/doc/presentation_external.html without locally installing reveal.js. Unlike presentationLocal, this requires an internet connection at runtime to access reveal.js, but results in a deployable file. Due to reproducibility, the reveal.js URL is hard-coded. Feel free to open an issue/PR to update its version.
presentationLocal	Compiles the presentation at result/share/doc/presentation_local.html and locally installs reveal.js. Unlike presentationExternal, this does not require an internet connection at runtime to access reveal.js, but results in a non-deployable file. Consequently, this package should not be released without the accompanying reveal.js installation.

Examples

To build the packages directly from upstream using nix, run one of the following commands:

nix build github:trueNAHO/asciidoctor.nix#default
nix build github:trueNAHO/asciidoctor.nix#defaultExternal
nix build github:trueNAHO/asciidoctor.nix#defaultLocal
nix build github:trueNAHO/asciidoctor.nix#docbook
nix build github:trueNAHO/asciidoctor.nix#html
nix build github:trueNAHO/asciidoctor.nix#manpage
nix build github:trueNAHO/asciidoctor.nix#pdf
nix build github:trueNAHO/asciidoctor.nix#presentationExternal
nix build github:trueNAHO/asciidoctor.nix#presentationLocal

To build the packages from a local copy at /path/to/repository using nix, run one of the following commands:

nix build /path/to/repository#default
nix build /path/to/repository#defaultExternal
nix build /path/to/repository#defaultLocal
nix build /path/to/repository#docbook
nix build /path/to/repository#html
nix build /path/to/repository#manpage
nix build /path/to/repository#pdf
nix build /path/to/repository#presentationExternal
nix build /path/to/repository#presentationLocal

See Also

Asciidoctor, License, Reproducible and Deployable Asciidoctor Template, Reveal.js converter for Asciidoctor, The HTML Presentation Framework, asciidoctor-nix.code-of-conduct(7), asciidoctor-nix.contributing(7)