Antora Notes

1. About

Antora is one of a few static site generators which can build a website from asciidoc files sourced from one or more Git repos.

2. Antora Install

Full doc is here

  1. Install Node.js

    1. Download from here.

    2. If VSC windows were opened prior to the install then all of them will need to be closed.

  2. Initialize package.json file

    1. CD to

      C:\Users\mattosd\source\repos\GitLab\repo-tech-docs2

    2. Run

      node -e "fs.writeFileSync('package.json', '{}')"
      npm i -D -E antora

3. Asciidoctor

Asciidoctor is the core AsciiDoc processor. It reads the AsciiDoc source, parses it into a document model, and converts it to a publishable format such as HTML using a converter. Asciidoctor has both a CLI and an API that you can use to invoke a built-in converter (HTML, DocBook, man page) or an add-on converter. Asciidoctor enriches the HTML it produces from AsciiDoc by applying a default stylesheet, adding stylistic icons, and syntax highlighting source blocks.

— https://docs.asciidoctor.org/

3.1. Asciidoctor.js

Don’t know how to create PDF file with this method.

  1. Details are here

  2. Install asciidoctor.js

    npm i asciidoctor

  3. Confirm asciidoctor.js is installed

    npm -x asciidoctor --version

  4. Install the asciidoctor.js CLI

    npm i -g asciidoctor

  5. Confirm asciidoctor.js CLI is installed

    asciidoctor --version

  6. Place holder for a missing node.js package

  7. Convert file to pdf

    asciidoctor -b [path to .adoc file]

3.2. Asciidoctor to PDF

asciidoctor-pdf is deprecated and will be removed in a future version, please use asciidoctor-web-pdf instead

  1. Install asciidoctor-pdf

    npm i asciidoctor-pdf

  2. Install the asciidoctor-pdf CLI

    npm i -g asciidoctor-pdf

  3. Convert file to pdf

    asciidoctor-pdf -a icons=font -a iconset=fas [path to .adoc file]

3.3. Asciidoctor Web to PDF

  1. Details are here

  2. Start a CLI window

  3. Install asciidoctor-kroki

    npm i asciidoctor-kroki

  4. Install yargs-parser

    npm i yargs-parser

  5. Install asciidoctor-pdf

    npm i @asciidoctor/core asciidoctor-pdf --save-dev

  6. Confirm installation

    npx asciidoctor-web-pdf --version

  7. Generate a PDF file

    npm x asciidoctor-web-pdf README.adoc
    Doesn’t work
    npm x asciidoctor-web-pdf --require asciidoctor-kroki README.adoc

4. Antora Extensions

4.1. Lunr Extension

Allows for text search. See more details here.

  1. Install

    npm install @antora/lunr-extension

  2. After the install, new folders will be added

    Expand for tree view
    lunr-extension-tree

  3. Add the following to the playbook.yml file:

    antora:
  extensions:
  - '@antora/lunr-extension'

4.2. Kroki

Kroki documentation can be found here.
Documentation for integration with Antora can be found here.

4.2.1. Install the Kroki Extension:

  1. Via npm, install the asciidoctor-kroki extension:

    npm install asciidoctor-kroki

  2. Add the following to the playbook.yml file:

    An external site does the actual rendering

    		 
    asciidoc:
  attributes:
    #kroki-server-url: https://kroki.io
    kroki-server-url: "https://kroki.xackleystudio.com/kroki"
    kroki-fetch-diagram: true
  extensions:
  - asciidoctor-kroki

4.3. PlantUML

PlantUML documentation can be found here.
Documentation for integration with Antora can be found here.

4.3.1. Install the PlantUML Extension:

  1. Via npm, install the asciidoctor-plantuml extension:

    npm install asciidoctor-plantuml

  2. After the install, new folders will be added to the node_modules folder:

    1. asciidoctor-plantuml

    2. mkdirp

    3. plantuml-encoder

    4. rusha

  3. Add the following to the playbook.yml file:

    An external site does the actual rendering

    		 
    asciidoc:
  attributes:
    #plantuml-server-url: "https://plantuml.gitlab-static.net"
    plantuml-server-url: "https://plantuml.xackleystudio.com/plantuml"
    plantuml-fetch-diagram: true
  extensions:
  - asciidoctor-plantuml

4.3.2. Enable Visual Studio Code preview

  1. In the VSC AsciiDoc extension, set the following config values:

    Config Value

    Enable Kroki

    true

  2. If the PlantUML extension is installed set the following config values:

    Config Value

    Plantuml: Render

    PlantUMLServer

    Plantuml: Server
    Select one of the following:

  3. Now place PlantUML code in your document via one of these two methods:

    Inline PlantUML code:
    [plantuml,sample-puml,svg]
....
@startuml
!theme materia-outline
frame "Group 1" as g1 #Yellow {
}
package "Group 2" as g2 #LightBlue {
}

g1--->g2 #Blue
g2--->g1 #Red

@enduml
....
    Or include from a separate source file:
    [plantuml,sample-puml,svg]
....
include::../partials/sample-puml.puml[]
....

  4. The rendered PlantUML code:

    Example 1. Rendered PlantUML code
    sample-puml

5. Antora Publish

5.1. Build the Site

  1. Download this repo.

  2. Edit the output:dir key specified in the site-playbook.yml yaml file. This should point to the physical path of your website.

    Example
    output:
  clean: false
  dir: \\p-ubuntu-norco\repo-docker-master\stack-websites\TechDocs\html-data

  3. To build the AsciiDoc pages of this REPO into a static website via Antora, open a terminal window and run the following:

    Run from the root of the project. 
    npx antora --fetch site-playbook --stacktrace

  4. If you see this:

    npx : File C:\Program Files\nodejs\npx.ps1 cannot be loaded because running scripts is disabled on this system.
For more information, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170.

    1. Launch PowerShell as Administrator.

    2. Run this

      Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

This will create a build\site folder in this repo.

5.2. Preview the Site

  1. Go to the directory specified in output:dir key of the site-playbook.yml yaml file.

  2. Open the ..\Xackley-Tech-Docs\1.0\index.html file in a web browser.

This should launch the site and allow for previewing before publishing to IIS for the purpose of hosting the static website.

5.3. Supplemental UI

Instructions are here

5.4. Customize the UI

Instructions are here with the git repo here.