Asciidoctor-treeview NPM

asciidoctor-treeview

NPM version

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

| -------- -------- | width=300 |

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 | -------- -------- | width=300 |

.
# .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 | -------- -------- | width=300 |

.
* .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 | -------- -------- | width=300 |

.
- .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 | -------- -------- | width=300 |

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)