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 |
| --- | --- |
``treeview
.
* .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 |
| :-: | --- |
| !width=300px | !width=300px |

Installation and Integration

$3

Install the extension using npm:

`bash
npm i asciidoctor-treeview
`

$3

To use the extension with standalone Asciidoctor:

Register with Asciidoctor

`javascript
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.

$3

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

`yaml
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:

`handlebars
{{> 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

`html

{{> treeview-styles }}
`

The extension provides treeview-styles.hbs which includes:

`html

`

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

$3

For VSCode users:

VSCode Integration

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

Usage

| Type | Source | Result |
| :-: | --- | --- |
`treeview
.
├── .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 |
`treeview
.


.vscode

extensions.json

settings.json

data

config

$3

$3

$3

templates

$3

$3

.editorconfig

.eslintrc

.gitignore

.npmignore

.stylelintrc

LICENSE

package.json

`
| Hash Symbol | -------- -------- | !width=300 |
`treeview
.
* .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 |
`treeview
.
- .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

$3

#### treeview-theme
Default: dark

* Use treeview-theme attribute on document

`plaintext
:treeview-theme: light
`

* Use attribute on treeview block

--------
`treeview

`

`treeview

`
--------

#### 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
* => configure your own or url to the folder that contains the icons.

Examples:

Embed icons as data-uri in CSS

`plaintext
= Document Title
:treeview-icon-source: embedded
`

Use custom url

`plaintext
= 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.

$3

`yaml
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 #

--------
`treeview
.
- .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.

--------
`treeview
.
# 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.

--------
`treeview
.
# README.md // this is a comment
`
--------

Changelog

$3

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

$3

* 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)

$3


* 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
* => 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

$3

* 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)