Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/truenaho/asciidoctor.nix

Reproducible and Deployable Asciidoctor Template
https://github.com/truenaho/asciidoctor.nix

asciidoc asciidoctor book converter devops docbook flake html html5 manpage nix pdf pdf-generation presentation publish publishing slides slideshow template writing

Last synced: about 2 months ago
JSON representation

Reproducible and Deployable Asciidoctor Template

Awesome Lists containing this project

README 

        
= asciidoctor-nix(1)

:asciidoctor-asciidoctor-reveal-js-ruby-setup: link:https://docs.asciidoctor.org/reveal.js-converter/latest/setup/ruby-setup/

:asciidoctor-asciidoctor-reveal-js: link:https://github.com/asciidoctor/asciidoctor-reveal.js

:asciidoctor-asciidoctor: link:https://github.com/asciidoctor/asciidoctor

:direnv: link:https://direnv.net

:github-template: link:https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template

:idprefix:

:idseparator: -

:nix-installables: link:https://nixos.org/manual/nix/stable/command-ref/new-cli/nix#installables

:nix3-develop: link:https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-develop.html

:nix: link:https://nixos.wiki/wiki/Nix_Installation_Guide

:nixos: link:https://nixos.org

:repository-path: trueNAHO/asciidoctor.nix

:repository-star-history-align: center

:repository-star-history-alt: Star History Chart

:repository-star-history-width: 100%

:reveal-js: link:https://github.com/hakimel/reveal.js

:template-repository-commit-presentation-hash: de19b8059c410dc49e036d681749c7f8db8d609a

:template-repository: link:https://github.com/trueNAHO/asciidoctor.nix

:template-summary: Reproducible and Deployable Asciidoctor Template

:toc:



:repository-flake-url: github:{repository-path}

:repository-raw: https://github.com/{repository-path}

:repository-star-history-src-dark: https://api.star-history.com/svg?repos={repository-path}&type=Date&theme=dark

:repository-star-history-src-light: https://api.star-history.com/svg?repos={repository-path}&type=Date

:template-repository-commit-presentation-link: {template-repository}/commit/{template-repository-commit-presentation-hash}



:repository: link:{repository-raw}

:repository-raw-stargazers: {repository-raw}/stargazers



:repository-release-latest: {repository}/releases/latest



== Name



asciidoctor-nix - {template-summary}



== Synopsis



*nix build* [_options_] _installables_



== Description



Reproducible and deployable {asciidoctor-asciidoctor}[Asciidoctor]

{github-template}[template] based on {nixos}[Nix].



The {repository-release-latest}[`latest`] release containing the

<> <>, the

`link:Gemfile.lock[]` and `link:gemset.nix[]` files, and the `link:flake.lock[]`

file are automatically updated by the `link:.github/workflows/deploy.yml[]`,

`link:.github/workflows/bundix_lock.yml[]`, and

`link:.github/workflows/nix_flake_update.yml[]` GitHub actions respectively.



If the slides are not required, feel free to revert the

{template-repository-commit-presentation-link}[`{template-repository-commit-presentation-hash}`]

commit to reduce install size and compile time.



== Usage



=== Development Environment



Enter the link:flake.nix[development environment] with

{nix3-develop}[`nix develop`] or {direnv}[`direnv allow`].



=== nix build



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

____

`nix build` builds the specified _installables_.

{nix-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 `--,` 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`). `-` is

omitted if _N_ = 0, and `-` is omitted if _outname_ = `out` (denoting

the default output).

____



== Packages

:path: result/share



[cols="1,100"]

|===

| Package | Description



| [[default]] `default`

a| Compiles the <>, <>, <>, <>, <>, and <>

   <>.



| [[defaultexternal]] `defaultExternal`

a| Compiles the <>, <>, <>, <>, and <> <>.



| [[defaultlocal]] `defaultLocal`

a| Compiles the <>, <>, <>, <>, and <>

   <>.



| [[docbook]] `docbook`

a| Compiles the DocBook at `{path}/doc/main.xml`.



| [[html]] `html`

a| Compiles the HTML at `{path}/doc/index.html`.



| [[manpage]] `manpage`

a| Compiles the manpage at `{path}/man/man7/main.7.gz`.



| [[pdf]] `pdf`

a| Compiles the PDF at `{path}/doc/main.pdf`.



| [[presentationexternal]] `presentationExternal`

a| Compiles the presentation at `{path}/doc/presentation_external.html`

   {asciidoctor-asciidoctor-reveal-js-ruby-setup}[without locally installing

   `reveal.js`]. Unlike <>, this

   requires an internet connection at runtime to access

   {reveal-js}[`reveal.js`], but results in a deployable file.



Due to reproducibility, link:flake.nix[the `reveal.js` URL is hard-coded]. Feel

free to open an issue/PR to update its version.



| [[presentationlocal]] `presentationLocal`

a| Compiles the presentation at `{path}/doc/presentation_local.html` and

   {asciidoctor-asciidoctor-reveal-js-ruby-setup}[locally installs `reveal.js`].

   Unlike <>, this does not

   require an internet connection at runtime to access {reveal-js}[`reveal.js`],

   but results in a non-deployable file.



Consequently, this package should not be released without the accompanying

{reveal-js}[`reveal.js`] installation.

|===



== Examples

:command-base: nix build

:command-local-path: /path/to/repository



:command-local: {command-base} {command-local-path}#

:command-upstream: {command-base} {repository-flake-url}#



To build the <> directly from {repository}[upstream] using

{nix}[`nix`], run one of the following commands:



[,bash,subs="attributes"]

----

{command-upstream}default

{command-upstream}defaultExternal

{command-upstream}defaultLocal

{command-upstream}docbook

{command-upstream}html

{command-upstream}manpage

{command-upstream}pdf

{command-upstream}presentationExternal

{command-upstream}presentationLocal

----



To build the <> from a local copy at `{command-local-path}`

using {nix}[`nix`], run one of the following commands:



[,bash,subs="attributes"]

----

{command-local}default

{command-local}defaultExternal

{command-local}defaultLocal

{command-local}docbook

{command-local}html

{command-local}manpage

{command-local}pdf

{command-local}presentationExternal

{command-local}presentationLocal

----



== See Also



{asciidoctor-asciidoctor}[Asciidoctor], link:LICENSE[License],

{template-repository}[{template-summary}],

{asciidoctor-asciidoctor-reveal-js}[Reveal.js converter for Asciidoctor],

{reveal-js}[The HTML Presentation Framework],

link:docs/code_of_conduct.adoc[asciidoctor-nix.code-of-conduct(7)],

link:docs/contributing.adoc[asciidoctor-nix.contributing(7)]



ifdef::env-github[]

[subs=attributes]

++++



  


    

      



      



      {repository-star-history-alt}

    

  




++++

endif::[]