JacobCrabill/zigdown
Markdown toolset in Zig ⚡
db40631ef191d3692a706b142f524022c6be80d7.tar.gz
b2dcac090852c9b26f16798dbbb35c3da1f65773.tar.gz
8f65f0d5bf0d92b950ddf16afb34533491831c7d.tar.gz
980316cb4fd0da6075a6a8f86bd1a3927bf68ad3.tar.gz
ab5cf5feb936fa3b72c95d3ad0c0c67791937ba1
011758bab2c2b5a4b6e678e33a8dbb24570d4394.tar.gz
49c31006d8307dcb12bc5770f35b6d5b9e2be68e.tar.gz
e8841a6a9431b7365ac9055688429e1deb8db90f.tar.gz
fe48221d4d9842d916d66b5e71ab3c6307ec28b3.tar.gz
f41b4f66a42100be405f96bdc4ebc4a61095d3e8.tar.gz
4d770d31f732d50d3ec373865822fbe659e47c75.tar.gz
5e9e8f8ff3387b0edcaa90f46ddf3629f4cfeb1d.tar.gz
de0c01e7102e755f6c2e1b3055ae6ca85f261a10.tar.gz
c447dcce961ac438aaeaf117347749fe7d1e8365.tar.gz
1805917414a9a8ba2473717fd69447277a175fae.tar.gz
b670c8df85a1568f498aa5c8cae42f51a90473c0.tar.gz
[!TIP] Zig 0.15.1 Required
NOTE Github does not support this, but the above Table of Contents can be auto-generated using the
{toctree}
directive!
Zigdown, inspired by Glow and mdcat, is a tool to parse and render Markdown-like content to the terminal, to HTML, or inside Neovim. It can also serve up a directory of files to your browser like a psuedo-static web site, or present a set of files interactively as an in-terminal slide show.
WARNING This is not a CommonMark-compliant Markdown parser, nor will it ever be one!
zigdown console {file}
zigdown html {file}
zigdown format {file}
zigdown present -d {directory}
zigdown serve -f {file}
Headers
Basic text formatting (Bold, italic, strikethrough)
Links
Quote blocks
Unordered lists
Ordered lists
Code blocks, including syntax highlighting using TreeSitter
Task lists
Tables
Autolinks
GitHub-Flavored Markdown Alerts
Console and HTML rendering
Images (rendered to the console using the
Kitty graphics protocol)
Web-based images (fetch from URL & display in-terminal)
(Clickable) Links
Tables
Automatic Table of Contents creation
Neovim integration (Lua)
Markdown formatter
HTML-encode all text in the HTML renderer
Table of Contents generation from a directory tree of files
Deeper NeoVim integration:
- in-buffer image rendering
- auto-scrolling of preview/source wrt source/preview
Link References
Color schemes for syntax highlighting
Enabling TreeSitter parsers to be used in WASM modules
- Requires filling in some libC stub functions (the TS parsers use quite a few functions from
the C standard library that are not available in WASM)
- To run the exising WASM demo, do ./tools/run_wasm_demo.sh
.
Character escaping
Note that I am not planning to implement complete CommonMark specification support, or even full Markdown support by any definition. Rather, the goal is to support "nicely formatted" Markdown, making some simplifying assumptions about what constitutes a paragraph vs. a code block, for example. The "nicely formatted" caveat simplifies the parser somewhat, enabling easier extension for new features like special warnings, note boxes, and other custom directives.
In addition to my "nicely formatted" caveat, I am also only interested in supporting a very common subset of all Markdown syntax, and ignoring anything I personally find useless or annoying to parse.
The current version of Zig this code compiles with is 0.14.0. I highly recommend using the Zig version manager to install and manage various Zig versions.
zig build run -- console test/sample.md
zig build -l # List build options
zig build -Dtarget=x86_64-linux-musl # Compile for x86-64 Linux using
# statically-linked MUSL libC
zig build
will create a zigdown
binary at zig-out/bin/zigdown
. Add -Doptimize=ReleaseSafe
to
enable optimizations while keeping safety checks and backtraces upon errors.
To enable syntax highlighting within code blocks, you must install the necessary TreeSitter language
parsers and highlight queries for the languages you'd like to highlight. This can be done by
building and installing each language into a location in your $LD_LIBRARY_PATH
environment
variable.
Zigdown comes with a number of TreeSitter parsers and highlight queries built-in:
The parsers are downloaded from Github and the relevant source files are added to the build, and the
queries are stored at data/queries/
, which contain some fixes and improvements to the original
highlighting queries.
The Zigdown cli tool can also download and install parsers for you. For example, to download, build, and install the C and C++ parsers and their highlight queries:
zigdown install-parsers c,cpp # Assumes both exist at github.com/tree-sitter on the 'master' branch
zigdown install-parsers maxxnino:zig # Specify the Github user; still assumes the 'master' branch
zigdown install-parsers tree-sitter:master:rust # Specify Github user, branch, and language
You can also install manually if Zigdown doesn't properly fetch the repo for you (or if the repo is not setup in a standard manner and requires custom setup). For example, to install the C++ parser from the default tree-sitter project on Github:
#!/usr/bin/env bash
# Ensure the TS_CONFIG_DIR is available
export TS_CONFIG_DIR=$HOME/.config/tree-sitter/
mkdir -p ${TS_CONFIG_DIR}/parsers
cd ${TS_CONFIG_DIR}/parsers
# Clone and build a TreeSitter parser library
git clone https://github.com/tree-sitter/tree-sitter-cpp
cd tree-sitter-cpp
make install PREFIX=$HOME/.local/
# Add the install directory to LD_LIBRARY_PATH (if not done so already)
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/.local/lib/
In addition to having the parser libraries available for dlopen
, you will also need the highlight
queries. For this, use the provided bash script ./tools/fetch_queries.sh
. This will install the
queries to $TS_CONFIG_DIR/queries
, which defaults to $HOME/.config/tree-sitter/queries
.
Zigdown plays well with all the typical Neovim packages managers. For example, with Lazy.nvim:
require('lazy').setup({
-- ... all your other packages here ...
'jacobcrabill/zigdown',
})
After first being downloaded, Zigdown will download the correct version of the Zig compiler and
build itself. This might take a minute, but only needs to be done once (or whenever you pull a new
version of Zigdown). The output binary is the shared library at ./lua/zigdown_lua.so
(or .dll
or
.dylib
, depending on your OS). If you need to, you can manually build and place the library in
that directory.
To trigger a rebuild from within Neovim, do :ZigdownRebuild
. This is generally needed after
updating Zigdown (pulling the latest changes), e.g. via Lazy.nvim.
To manually build the Zigdown Lua plugin yourself for Neovim, do:
zig build -Dlua zigdown-lua -Doptimize=ReleaseFast
Rendering a Markdown buffer to a preview pane (the right-most window; if only one editable window is
open, a new one will be added as a vsplit) is done with the Vim command :Zigdown
. This will also
create an autocommand to re-render on save. If you want to cancel this autocommand, do
:ZigdownCancel
.
CAUTION Zigdown is an experimental project, and the Neovim auto-formatter will modify your files in-place. Use at your own risk!
To change the default formatter column width (the default is 100), do:
require('zigdown').setup({ format_width = 100 })
To enable auto-formatting of Markdown files on save, I recommend first adding a global option to enable/disable auto-formatting in case something goes wrong, or you're working in a Git repo that does not use formatters:
-- Globally enable/disable auto-formatting
-- (Useful in Git repos you don't own, or when you encounter formatter bugs)
vim.g.autoformat_enabled = true
-- Enable/Disable format-on-save for all auto-formatters
function DisableAutoFmt()
vim.g.autoformat_enabled = false
end
function EnableAutoFmt()
vim.g.autoformat_enabled = true
end
The actual autocommand to format-on-save is very simple:
-- Markdown auto-formatter
vim.api.nvim_create_autocmd('BufWritePre', {
pattern = { '*.md' },
group = 'AutoFmt',
callback = function()
if vim.g.autoformat_enabled then
vim.api.nvim_command([[ZigdownFormat]])
end
end
})