- Notifications
You must be signed in to change notification settings - Fork0
Generates tree views based on ascii-tree with beautiful icons for folders and icons
License
lask79/asciidoctor-treeview
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
asciidoctor-treeview is an extension forasciidoctor.js andAntora that generates a treeview based on several input formats and displays beautiful icons for folders and files.
| Source | Result |
|---|---|
|
|
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 (useshttps://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 
To use the extension with standalone Asciidoctor:
constasciidoctor=require('@asciidoctor/core')()constasciidoctorTreeView=require('asciidoctor-treeview')constregistry=asciidoctor.Extensions.create()asciidoctorTreeView.register(registry)
Note | The extension automatically adds required CSS via theDocInfoProcessor. |
The extension seamlessly integrates with Antora documentation sites. Follow these steps:
Add the extension to your Antora playbook:
antora:extensions: -require:"asciidoctor-treeview/antora"
Important | Do not add asciidoctor-treeview toasciidoc.extensions. This will prevent proper CSS integration. |
The extension requires a small modification to your Antora UI bundle to include its styles. You have two options:
Add the following line topartials/head-styles.hbs in your UI bundle:
{{>treeview-styles}}
If you’re using the default UI bundle or prefer not to modify your custom bundle, create a supplemental UI file:
<linkrel="stylesheet"href="{{{uiRootPath}}}/css/site.css">{{> treeview-styles }}
The extension providestreeview-styles.hbs which includes:
<linkrel="stylesheet"href="{{{uiRootPath}}}/css/treeview.css">
Note | Thetreeview.css file contains styles necessary for proper rendering and overrides some styles from theAntora UI Default. |
| Type | Source | Result |
|---|---|---|
ascii-tree | |
|
Hash Symbol | |
|
* Symbol | |
|
Custom Symbol | |
|
Default: dark
Use
treeview-themeattribute on document
:treeview-theme: lightUse attribute on treeview block
[treeview,theme=light]----<your tree>----[treeview,theme=dark]----<your tree>----Default: jsdelivr
Use
treeview-icon-sourceattribute on documentSupported 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:
= Document Title:treeview-icon-source: embedded= Document Title:treeview-icon-source: https://example.com/cdn/iconsThe icon name like file.svg will be added as suffix to the given url.
antora:extensions: -require:"asciidoctor-treeview/antora"icon_source:antora# or embedded or jsdelivr
Default: antora
Use
icon-sourceattribute on documentSupported values:
antora(default) ⇒ copies icons into UI catalogjsdelivr⇒ downloads from CDNembedded⇒ embeds the icons into the css as data-uri
Warning | The asciidoctor attributetreeview-icon-source will be ignored when antora is used. |
Symbols * and # are already autodetected.
If you want to use a custom symbol like '-' then you need to configure it on the treeview block.
[treeview,symbol="-"]----.- .vscode-- extensions.json-- settings.json----- 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----
Improvements
Fixed documentation about how to use the extension in antora
Added github actions to validate against asciidoctor, antora and nodejs versions
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
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
handlebarsandmaterial-icons-theme.Collects all used icons and uses them to generate the css and copies only the used icons to the UI catalog