asciidoctor-treeview
v1.0.1
Published
An extension to generate folder treeview with beautiful icons for Asciidoctor.js
Downloads
291
Maintainers
Readme
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
Generates css based on used icons
Copies only the used icons to the antora UI catalog
Dark and light mode
| Dark | Light | | :-: | --- | |
|
|
Installation and Integration
Basic Installation
Install the extension using npm:
npm i asciidoctor-treeview
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
.
Integration with Antora
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
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:
{{> 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.
Integration with VSCode
For VSCode users:
VSCode Integration
// Add to .asciidoctor/lib/asciidoctor-treeview.js
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 CDNembedded
=> embeds the icons into the css as data-uriantora
=> 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/antora"
icon_source: antora # or embedded or jsdelivr
Default: antora
- Use
icon-source
attribute on document - Supported values:
antora
(default) => copies icons into UI catalogjsdelivr
=> downloads from CDNembedded
=> 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.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
v1.0.0-alpha.7
- Features
- add support for different icon sources (#8)
jsdelivr
(default) => downloads from CDNembedded
=> embeds the icons into the css as data uriantora
=> copies icons into UI catalog<custom_path>
=> configure your own path or url
- add support for different icon sources (#8)
- 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
andmaterial-icons-theme
. - Collects all used icons and uses them to generate the css and copies only the used icons to the UI catalog