asciidoctor-treeview

asciidoctor-treeview is an extension for asciidoctor.js and Antora that generates a treeview based on several input formats and displays beautiful icons for folders and files.

Features

| Source | Result | | --- | --- |

.
* .vscode
** extensions.json
**  settings.json
* data
**  config
*** default.json
*** full.json
*** minimal.json
** templates
*** treeview.css.hbs
*** treeview.js.hbs
* .editorconfig
* .eslintrc
* .gitignore
* .npmignore
* .stylelintrc
* LICENSE
* package.json

| -------- -------- | |

• No scripts used (no highlight.js or custom scripts)

• Supports Antora and Asciidoctor standalone

• Generates treeview based on:

  • symbol based treeview (#, *) or custom symbol
  • ascii-tree (using tree command on Linux or Windows)
  • autodetects if ascii-tree parser should be used or symbol parser

• Calculates the right icons for folders and files based on:

  • extensions
  • file names
  • folder names
  • language ids

• Uses the same icons as VSCode (uses https://github.com/PKief/vscode-material-icon-theme)

• Adds styles to the document

• Supports dark and light mode

• Uses different icons for dark and light mode

• Supports callouts / conums

• Supports different ways of retrieving the icons:

  • jsdelivr (default) => downloads from CDN
  • embedded => embeds the icons into the css as data uri
  • antora => copies icons into UI catalog
  • <custom_path> => configure your own path or url

• Generates css based on used icons

• Copies only the used icons to the antora UI catalog

• Dark and light mode

  | Dark | Light | | :-: | --- | | | |

Installation and Integration

Basic Installation

Install the extension using npm:

npm i asciidoctor-treeview

Integration with Asciidoctor

To use the extension with standalone Asciidoctor:

Register with Asciidoctor

const asciidoctor = require('@asciidoctor/core')()
const asciidoctorTreeView = require('asciidoctor-treeview')
const registry = asciidoctor.Extensions.create()
asciidoctorTreeView.register(registry)

📌 NOTE
The extension automatically adds required CSS via the DocInfoProcessor.

Integration with Antora

The extension seamlessly integrates with Antora documentation sites. Follow these steps:

1. Configure Antora Playbook

Add the extension to your Antora playbook:

antora-playbook.yml

antora:
  extensions:
    - require: "asciidoctor-treeview/antora"

❗ IMPORTANT
Do not add asciidoctor-treeview to asciidoc.extensions. This will prevent proper CSS integration.

2. Set Up UI Integration

The extension requires a small modification to your Antora UI bundle to include its styles. You have two options:

Option A: Modify UI Bundle

Add the following line to partials/head-styles.hbs in your UI bundle:

{{> treeview-styles }}

Option B: Use Supplemental UI (Recommended)

If you’re using the default UI bundle or prefer not to modify your custom bundle, create a supplemental UI file:

supplemental-ui/partials/head-styles.hbs

<link rel="stylesheet" href="{{{uiRootPath}}}/css/site.css">
{{> treeview-styles }}

The extension provides treeview-styles.hbs which includes:

<link rel="stylesheet" href="{{{uiRootPath}}}/css/treeview.css">

📌 NOTE
The treeview.css file contains styles necessary for proper rendering and overrides some styles from the Antora UI Default.

Integration with VSCode

For VSCode users:

VSCode Integration

// Add to .asciidoctor/lib/asciidoctor-treeview.js
module.exports = require('asciidoctor-treeview')

Usage

| Type | Source | Result | | :-: | --- | --- |

.
├── .vscode
│   ├── extensions.json
│   └── settings.json
├── data
│   ├── config
│   │   ├── default.json
│   │   ├── full.json
│   │   └── minimal.json
│   └── templates
│       ├── treeview.css.hbs
│       └── treeview.js.hbs
├── .editorconfig
├── .eslintrc
├── .gitignore
├── .npmignore
├── .stylelintrc
├── LICENSE
└── package.json

| ascii-tree | -------- -------- | |

.
# .vscode
## extensions.json
##  settings.json
# data
##  config
### default.json
### full.json
### minimal.json
## templates
### treeview.css.hbs
### treeview.js.hbs
# .editorconfig
# .eslintrc
# .gitignore
# .npmignore
# .stylelintrc
# LICENSE
# package.json

| Hash Symbol | -------- -------- | |

.
* .vscode
** extensions.json
**  settings.json
* data
**  config
*** default.json
*** full.json
*** minimal.json
** templates
*** treeview.css.hbs
*** treeview.js.hbs
* .editorconfig
* .eslintrc
* .gitignore
* .npmignore
* .stylelintrc
* LICENSE
* package.json

| * Symbol | -------- -------- | |

.
- .vscode
-- extensions.json
--  settings.json
- data
--  config
--- default.json
--- full.json
--- minimal.json
-- templates
--- treeview.css.hbs
--- treeview.js.hbs
- .editorconfig
- .eslintrc
- .gitignore
- .npmignore
- .stylelintrc
- LICENSE
- package.json
- test.hcl

| Custom Symbol | -------- -------- | |

Configuration

Asciidoc Attributes

treeview-theme

Default: dark

• Use treeview-theme attribute on document

:treeview-theme: light

• Use attribute on treeview block

<your tree>

<your tree>

treeview-icon-source

Default: jsdelivr

• Use treeview-icon-source attribute on document
• Supported values:
  • jsdelivr (default) => downloads from CDN
  • embedded => embeds the icons into the css as data-uri
  • antora => copies icons into UI catalog
  • <custom_path> => configure your own or url to the folder that contains the icons.

Examples:

Embed icons as data-uri in CSS

= Document Title
:treeview-icon-source: embedded

Use custom url

= Document Title
:treeview-icon-source: https://example.com/cdn/icons

The icon name like file.svg will be added as suffix to the given url.

Antora

antora:
  extensions:
    - require: "asciidoctor-treeview/antora"
      icon_source: antora # or embedded or jsdelivr

Default: antora

• Use icon-source attribute on document
• Supported values:
  • antora (default) => copies icons into UI catalog
  • jsdelivr => downloads from CDN
  • embedded => embeds the icons into the css as data-uri

⚠️ WARNING
The asciidoctor attribute treeview-icon-source will be ignored when antora is used.

Symbol Based Parser

• Symbols * and # are already autodetected.
• If you want to use a custom symbol like '-' then you need to configure it on the treeview block.

Autodetected symbol #

.
- .vscode
-- extensions.json
--  settings.json

HowTos

• I want to mark a line as folder even when it does not have children
  Put a / at the end of the name. Then that line will be marked as a folder.

  ---

  .
  # folder/
  # second-folder/

  ---

• I want to add comments to a line
  Put // at the end of the line. Then that line will be marked as a comment.

  ---

  .
  # README.md // this is a comment

  ---

Changelog

v1.0.1

• Improvements
  • Fixed documentation about how to use the extension in antora
  • Added github actions to validate against asciidoctor, antora and nodejs versions

v1.0.0

• Improvements
  • Updated to material-icons-theme version 5.19.0
  • Added tests to validate antora build
• Fixes
  • Asciidoctor-treeview plugin no longer works with Antora (#10)
  • material-icon-theme package is not set as a dependency (#11)

v1.0.0-alpha.7

• Features
  • add support for different icon sources (#8)
    • jsdelivr (default) => downloads from CDN
    • embedded => embeds the icons into the css as data uri
    • antora => copies icons into UI catalog
    • <custom_path> => configure your own path or url
• Refactoring
  • Now generates a treeview.css that uses urls for the different icons instead of creating image tags inside of the document.
  • Uses roles on an <i> tag to define the icons.
  • There are now new dependencies to handlebars and material-icons-theme.
  • Collects all used icons and uses them to generate the css and copies only the used icons to the UI catalog

v1.0.0-alpha.6

• Features
  • allow comments on lines (#6)
  • mark lines as folders (see HowTos)
• Fixes
  • do not render empty lines as files without name allow comments on lines (#5)