asciidoctor-treeview

Contents

• 1. Features
• 2. Installation and Integration
  • 2.1. Basic Installation
  • 2.2. Integration with Asciidoctor
  • 2.3. Integration with Antora
  • 2.4. Integration with VSCode
• 3. Usage
• 4. Configuration
  • 4.1. Asciidoc Attributes
  • 4.2. Antora
• 5. Symbol Based Parser
• 6. HowTos
• 7. Changelog
  • v1.0.1
  • v1.0.0
  • v1.0.0-alpha.7
  • v1.0.0-alpha.6

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.

1. 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 ----

• 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

2. Installation and Integration

2.1. Basic Installation

Install the extension using npm:

npm i asciidoctor-treeview

2.2. 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.

2.3. Integration with Antora

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

2.3.1. 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.3.2. 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.

2.4. Integration with VSCode

For VSCode users:

VSCode Integration

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

3. Usage

Type	Source	Result
ascii-tree	[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 ----
Hash Symbol	[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	[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 ----
Custom Symbol	[treeview,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 ----

4. Configuration

4.1. Asciidoc Attributes

4.1.1. treeview-theme

Default: dark

• Use treeview-theme attribute on document

:treeview-theme: light

• Use attribute on treeview block

[treeview,theme=light]
----
<your tree>
----

[treeview,theme=dark]
----
<your tree>
----

4.1.2. 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.

4.2. 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.

5. 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,symbol="-"]
----
.
- .vscode
-- extensions.json
--  settings.json
----

6. 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
----

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