asciidoctor-treeview

Contents

• 1. Features
• 2. Installation
• 3. Register extension
  • 3.1. Asciidoctor
  • 3.2. Antora
  • 3.3. VSCode
• 4. Usage
• 5. Configuration
  • 5.1. Asciidoc Attributes
  • 5.2. Antora
• 6. Symbol Based Parser
• 7. HowTos
• 8. Changelog
  • 8.1. v1.0.0-alpha.7
  • 8.2. 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

npm i asciidoctor-treeview

3. Register extension

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

3.2. Antora

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

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

3.3. VSCode

VSCode

// add this to .asciidoctor/lib/asciidoctor-treeview.js when you have turned on the extension
module.exports = require('asciidoctor-treeview')

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

5. Configuration

5.1. Asciidoc Attributes

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

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

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

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

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

8. Changelog

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

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