FileTree
filetree fence. Use indentation for depth, trailing slashes for directories, and aligned comments for explanations.A filetree fence contains a directory listing. Indentation sets depth, a trailing / marks a directory, and text after # is a comment.
Use it to explain the relevant directory structure, with one annotation per entry.
If readers need to copy the exact listing, use an ordinary code block.
Shortest form
content/
- _index.md
- docs/
- blog/
- hugo.yml
- go.mod
Bullets (-, *, +) are optional and do not change the result.
Entries with children are directories. For entries without children, a trailing / marks a directory.
Adding comments
Text after the first whitespace-preceded # is a comment. Comments appear in an aligned column on the right.
They are plain text, so Markdown appears literally. Use \# for a literal hash.
content/every page, both languages in one directory
- docs/the documentation tree you are reading
- blog/release notes and articles
- assets/scss/the site's own SCSS, overriding theme variables
- layouts/site-level template overrides, the fewer the better
- static/images/images that need no build-time processing
- hugo.ymlsite configuration: languages, menus, params.ui
At build time, the widest row determines the comment column’s starting position. Each # aligns even if the source does not.
The comment column occupies at least three tenths and at most half of the panel.
Drag the dashed splitter to change the width. Alternatively, focus it with Tab and move it with arrow keys.
Home / End move it to the limits.
By default (wrap=false), long names and comments are truncated with an ellipsis within their columns. Hover to see the full text in title.
Only trees with comments load JavaScript. This script controls the splitter.
truncation in both columns
runbooks/
- a-deliberately-long-runbook-filename-for-a-failover-drill.mdan equally overlong comment, kept on one line so it has to be clipped inside the comment column
- restart.mdshort
Wrap long comments
Use wrap=true on the filetree fence to show complete comments in their
column. Rows grow as needed, including for unbroken identifiers. The default
wrap=false keeps compact rows with ellipsis. Names, folding, splitter controls,
mobile layout, and expanded Print output retain their existing behavior.
Complete storage comments
storage/
- metadata/Schema definitions: property keys, vertex and edge labels, indexes, and counters.
- graph/Graph data: vertices, edges, index tables, and OLAP analysis data.
Invalid wrap values warn and fall back to false. Review the warning and fallback before publication.
Title bars
The fence attribute {title="…"} adds a title bar above the tree. Without it, no title bar appears.
the oink.pgsty.com repository root
- content/pages
- assets/resources that take part in the build
- data/data for the home page, landings and downloads
- layouts/template overrides
- static/files copied verbatim
- tests/Playwright and node --test
- hugo.yml
- go.modthe theme, imported as a Hugo Module
- Makefilemake d / make b / make c
Indentation and depth
Indentation sets depth. Two spaces, four spaces, and tabs, counted as four columns, are supported.
Indentation widths can vary within one tree, but every level that you return to must have been opened previously.
You can paste complete tree command output, including the root and summary lines. The summary is removed.
content/docs
about
- _index.md
- features.md
components
- filetree.md
image
- index.md
- _index.md
Returning to an unopened indentation level warns and skips that line. The warning identifies the line inside the fence.
Folding and explicit types
Directories with children are open by default. {open=false} makes a directory initially closed.
Directories use native <details> and work with the keyboard without JavaScript. Only directories accept open.
An entry without children or a trailing / is a file. {type=dir} forces a directory, and {type=file} forces a file.
the content directory
content/
docs/the documentation tree
components/22 component pages
- callout.md
- filetree.md
- image/page bundle: body + images
customize/site-level configuration
- config.md
blog/
- release.md
Icons and tones
The theme infers icons from names. Directory icons follow the open state.
Files are matched first by full filename (LICENSE, Makefile, go.mod, package.json, .gitignore …), then by extension (md yml toml json sh py go js sql css png svg pdf zip …). Other files use a generic file icon.
{icon=…} overrides the icon with exactly one Font Awesome class pair.
{tone=…} colors the icon. It uses the badges vocabulary: neutral info success warning danger.
deployment layout: permissions and what matters
/etc/pigsty/0755 root:root · configuration root
- pigsty.yml0644 root:root · cluster inventory
ca/0700 root:root · self-signed CA, never commit
- ca.key0600 root:root
/var/lib/pgsql/18/data/0700 postgres:postgres · data directory
- postgresql.conf0600 postgres:postgres
- /usr/bin/pig0755 root:root · command-line tool
tone colors only the icon. It never colors the text. State the meaning in the name or comment; color supplements it.
Linked entries
Write [name](link) to make an entry name a link. Site paths, relative paths, and http(s): are supported.
Links use the same URL validation as other components.
this site's component pages
content/docs/
- callout.mdcallouts
- filetree.mdthis page
- gallery.mdgalleries
image/page bundle
- index.mdimages
- hugo.ymlfixture configuration on GitHub
One tree per platform
A fence carrying tab= (and group= / value=) becomes one panel of a
tab set and can sit alongside code fences.
- /etc/pigsty/configuration
- /var/lib/pgsql/data
- /usr/bin/pigexecutable
- ~/Library/Application Support/pigsty/configuration
- /opt/homebrew/bin/pigexecutable
Output
| Output | Shape |
|---|---|
| HTML | <div class="td-filetree">, an optional title bar, directories as native <details>; a tree with comments also gets the draggable splitter, its only runtime |
| The same tree, fully expanded, no splitter, comments wrapped instead of truncated | |
| Markdown | The filetree fence, emitted as written |
| RSS | The fence source inside a <pre> |
Below the sm breakpoint, the layout becomes one column. Comments move below names, display without truncation, and the splitter is hidden.
Trees without comments always use one column and load no script.
Parameter reference
Fence attributes, after ```filetree:
Entry attributes, in the {…} at the end of a line:
The line syntax itself:
Unknown attributes or values, open on files, malformed {…}, and dedents to unopened levels warn.
The theme uses a safe fallback or skips the invalid line. The message identifies the line.
Limits
filetreefences are the only form. There is no{.filetree}list marker or shortcode.- Names and comments are plain text.
**bold**appears literally, so the source remains readable in other tools. - The tree reads nothing from disk. You write or paste static content, which does not track the repository.
- There is no search, multiple selection, or control to copy the whole tree. Use a code block when readers must copy the exact listing.
- Split positions are not saved. Reloading restores the width calculated at build time.
Related
- Code blocks — listings meant to be copied verbatim
- Tabs — one tree per platform, side by side
- Badges —
toneuses the same vocabulary - Organizing content — how a real content directory is laid out