= asciidoctor-treeview :url-repo: https://github.com/lask79/asciidoctor-treeview :url-antora-docs: https://docs.antora.org/antora/3.1 :toc: macro :toc-title: Contents :sectnums: :imagesdir: docs/modules/ROOT/images

image::https://img.shields.io/npm/v/asciidoctor-treeview.svg[NPM version]

toc::[]

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

[%header,cols="2a,2a""] |=== |Source |Result

| [source, plaintext]

[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

  ---

  |image:small-structure-result.png[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 => 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

• [%header,cols="^1a,1a""] |=== |Dark |Light |image:treeview-dark.png[width=300px] |image:treeview-light.png[width=300px] |===

== Installation

npm i asciidoctor-treeview

== Register extension

=== Asciidoctor

.Asciidoctor [source, javascript]

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 [source, yaml]

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 [source,html]

{{> treeview-styles }}

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

.treeview-styles.hbs [source,html]

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 https://docs.antora.org/antora-ui-default/[Antora UI Default].

=== VSCode

.VSCode [source,javascript]

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

== Usage

[%header,cols="^1s,4a,2a""] |=== |Type |Source |Result

[source, plaintext]

[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

|image:small-structure-result.png[width=300]

[source, plaintext]

[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

|image:small-structure-result.png[width=300]

[source, plaintext]

[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

  ---

  |image:small-structure-result.png[width=300]

[source, plaintext]

[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

  ---

  |image:small-structure-result.png[width=300] |===

== Configuration

=== Asciidoc Attributes

==== treeview-theme Default: dark

• Use treeview-theme attribute on document

[source,plaintext]

:treeview-theme: light

• Use attribute on treeview block

[source,plaintext]

[treeview,theme=light]