AsciiDoc Document Template

This repository is a reusable template for writing structured AsciiDoc documents. It is set up for reports, technical notes, and other long-form documents.

What Is Included

The repository already contains:

1. A main AsciiDoc document with includes for the rest of the template.

2. A html stylesheet and PDF theme.

3. Python helper scripts and PlantUML .jar for filtering and other generation tasks.

4. A Makefile that wires the build together.

5. Sample assets for images, diagrams, tables, and planning charts.

How To Use This Template

You can use this repository directly by cloning it or by using github template features to create a new repository based on it.

Once you have your own copy of the repository, replace all the sample content with your own material. It is recommended to read the rest of this README to understand the structure of the repository and how to build the document.

Notes

• The images used for the headers and title page are stored im styles/.

• This template uses .adoc for files that are meant to be read or modified by scripts and .asciidoc for files that are meant to be edited directly. This is just a convention to help you identify which files are generated and which are source files.

• Even if this template is supposed to work on any OS and with any editor, the provided settings are configured for Visual Studio Code on a Unix-like system.

Setup and Build Instructions

Please see the end of this README for VSCode recommendations.

Dependencies

The template uses both Ruby and Python tooling:

1. Ruby is needed for asciidoctor-pdf and asciidoctor-lists.

2. Python is needed for the helper scripts in [scripts/].

3. drawio is needed to export .drawio diagrams.

4. java is needed to export PlantUML diagrams through the bundled JAR.

The Python dependencies are listed in [requirements.txt]. The Ruby dependencies are listed in [Gemfile].

Set Up A Python Virtual Environment

From the repository root:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

If you prefer to recreate the environment later, remove .venv and run the same commands again.

Install Ruby Dependencies

If you do not already have the AsciiDoc Ruby gems installed, use Bundler from the repository root:

bundle install

How To Build

The simplest way to build the document is:

make build

That target does the full pipeline:

1. Filters references into [src/main_references.adoc].

2. Filters glossary entries into [src/main_glossary.adoc].

3. Regenerates planning chart PNG files from .mw inputs.

4. Regenerates diagram PNG files from .drawio and .plantuml inputs.

5. Builds the final PDF into [dist/main.pdf].

If you only want to refresh parts of the pipeline, use the smaller targets that you can find using make help.

Structure

The repository is organized as follows:

.
├── README.adoc
├── .vscode/
│   ├── asciidoc.code-snippets
│   ├── cspell.json
│   ├── settings.json
│   ├── tasks.json
│   └── cspell-dictionaries/
│       └── ...
├── docs/
│   └── ...
├── scripts/
│   ├── README.adoc
│   └── ...
├── src/
│   ├── main.asciidoc
│   ├── main_glossary.adoc
│   ├── main_references.adoc
│   └── assets/
│       ├── complete_glossary_db.adoc
│       ├── complete_ref_db.adoc
│       ├── diagrams/
│       │   └── ...
│       ├── imgs/
│       ├── includes/
│       │   └── ...
│       └── plannings/
│           └── ...
└── styles/
	├── basic-theme.css
	├── basic-theme.yml
	└── fonts/
		└── ...

The tree above shows the main layout of the repository and is described below.

• .vscode/ - This folder contains the workspace settings. (VSCode specific)

  • settings.json - workspace settings, including AsciiDoc preview configuration.

  • asciidoc.code-snippets - snippets for AsciiDoc syntax in VS Code.

  • cspell.json - configuration for the Code Spell Checker extension.

  • cspell-dictionaries/ - custom dictionaries for the spell checker.

  • tasks.json - custom tasks for building the document and running scripts.

• docs/ - This folder contains supporting material you may want to commit with the template.

• scripts/ - This folder contains the helper scripts used by the build pipeline.

• src/ - This folder contains the main AsciiDoc sources and their assets.

  • assets/ - this folder contains all assets used in the document.

    • complete_glossary_db.adoc - complete_ref_db.adoc - these files contain the full glossary and bibliography databases used to generate the filtered versions.

    • diagrams/ - this folder contains source files for diagrams, such as .drawio and .plantuml files.

    • imgs/ - this folder contains image assets.

    • includes/ - this folder contains other files types that are included in the main document.

    • plannings/ - this folder contains Markwhen .mw files for planning charts.

  • main.asciidoc - the main document that includes the rest of the content.

  • main_glossary.adoc - main_references.adoc - These files will be automatically generated and should not be edited directly.

• styles/ - This folder contains the PDF theme, preview stylesheet, and bundled fonts as well as header logos and title page logo.

Contributing to this Template

Contributions to this template are welcome! If you have suggestions for improvements, additional features, or bug fixes, please open an issue or submit a pull request.

VSCode extensions

As mentioned, this template as VSCode specific configuration, but you can adapt it to your preferred editor. The recommended extensions for VSCode are:

• AsciiDoc from asciidoctor - asciidoctor.asciidoctor-vscode

• Code Spell Checker from Street Side Software - streetsidesoftware.code-spell-checker

• Draw.io Integration from Henning Dieterichs - hediet.vscode-drawio

• Markwhen from Markwhen - markwhen.markwhen

• PlantUML from jebbs - jebbs.plantuml