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

• Dark and light mode

  Dark	Light

Installation

npm i asciidoctor-treeview

Register extension

Asciidoctor

Asciidoctor

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

📌 NOTE
The needed css file is added via DocInfoProcessor.

Antora

Antora Playbook

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

⚠️ WARNING
Do not add the asciidoctor-treeview to the asciidoc.extensions. It will not work because then the needed css will not be added to the site.

Add handlebars template

You have to change 1 file in your Antora UI bundle or by overwriting it via supplemental-ui:

• add {{> treeview-styles }} to partials/head-styles.hbs

If you do not want to change your UI bundle or when you use the default ui bundle you can simply put the following lines into supplemental-ui/partials/head-styles.hbs next to your antora playbook:

head-styles.hbs

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

{{> treeview-styles }} will be replaced with the content of the file treeview-styles.hbs that provided by this extension.

treeview-styles.hbs

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

The treeview.css file contains some treeview specific styles that are needed to render the code blocks correctly and overrides some styles defined in the Antora UI Default.

VSCode

VSCode

// add this to .asciidoctor/lib/asciidoctor-treeview.js when you have turned on the extension
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"
      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.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.

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)