{"id":23100486,"url":"https://github.com/jacobcrabill/zigdown","last_synced_at":"2025-08-16T14:31:45.338Z","repository":{"id":88341410,"uuid":"605658674","full_name":"JacobCrabill/zigdown","owner":"JacobCrabill","description":"Markdown parser in Zig","archived":false,"fork":false,"pushed_at":"2024-12-12T16:34:22.000Z","size":1074,"stargazers_count":17,"open_issues_count":1,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-12-12T17:39:11.407Z","etag":null,"topics":["markdown","terminal","zig"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JacobCrabill.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-23T16:17:59.000Z","updated_at":"2024-12-08T14:41:23.000Z","dependencies_parsed_at":null,"dependency_job_id":"7225a304-4486-427c-a887-3525b66d3fc1","html_url":"https://github.com/JacobCrabill/zigdown","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JacobCrabill%2Fzigdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JacobCrabill%2Fzigdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JacobCrabill%2Fzigdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JacobCrabill%2Fzigdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JacobCrabill","download_url":"https://codeload.github.com/JacobCrabill/zigdown/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230039990,"owners_count":18163484,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["markdown","terminal","zig"],"created_at":"2024-12-16T23:32:51.785Z","updated_at":"2025-08-16T14:31:45.308Z","avatar_url":"https://github.com/JacobCrabill.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zigdown: Markdown toolset in Zig\n\n![CI Status](https://github.com/JacobCrabill/zigdown/actions/workflows/main.yml/badge.svg)\n\n```{toctree}\nThis block will be rendered as a Table of Contents\n```\n\n![Zig is Awesome!](src/assets/img/zig-zero.png)\n\nZigdown, inspired by [Glow](https://github.com/charmbracelet/glow) and\n[mdcat](https://github.com/swsnr/mdcat), is a tool to parse and render Markdown-like content to the\nterminal or to HTML. It can also serve up a directory of files to your browser like a psuedo-static\nweb site, or present a set of files interactively as an in-terminal slide show.\n\nThis will likely forever be a WIP, but it currently supports the the most common features of simple\nMarkdown files.\n\n\u003e [!WARNING]\n\u003e This is not a CommonMark-compliant Markdown parser, nor will it ever be one!\n\n## Tools\n\n- **Console Renderer:** `zigdown console {file}`\n- **HTML Renderer:** `zigdown html {file}`\n- **Markdown Formatter:** `zigdown format {file}`\n- **In-Terminal Slide Shows:** `zigdown present -d {directory}`\n- **HTTP Document Server:** `zigdown serve -f {file}`\n\n## Features \u0026 Future Work\n\n### Parser Features\n\n- [x] Headers\n- [x] Basic text formatting (**Bold**, _italic_, ~strikethrough~)\n- [x] Links\n- [x] Quote blocks\n- [x] Unordered lists\n- [x] Ordered lists\n- [x] Code blocks, including syntax highlighting using TreeSitter\n- [x] Task lists\n- [x] Tables\n- [x] Autolinks\n- [x] GitHub-Flavored Markdown Alerts\n\n### Renderer Features\n\n- [x] Console and HTML rendering\n- [x] Images (rendered to the console using the\n      [Kitty graphics protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/))\n- [x] Web-based images (fetch from URL \u0026 display in-terminal)\n- [x] (Clickable) Links\n- [x] Tables\n- [x] Automatic Table of Contents creation\n- [x] Neovim integration (Lua)\n- [x] Markdown formatter\n\n### Future Work / Missing Pieces\n\n- [ ] HTML-encode all text in the HTML renderer\n- [ ] Enabling TreeSitter parsers to be used in WASM modules\n      - Requires filling in some libC stub functions (the TS parsers use quite a few functions from\n        the C standard library that are not available in WASM)\n- [ ] Character escaping\n- [ ] Deeper NeoVim integration: image rendering and auto-scrolling\n- [ ] [Link References](https://spec.commonmark.org/0.31.2/#link-reference-definition)\n- [ ] Color schemes for syntax highlighting\n\n## Caveats\n\nNote that I am **not** planning to implement complete CommonMark specification support, or even full\nMarkdown support by any definition. Rather, the goal is to support \"nicely formatted\" Markdown,\nmaking some simplifying assumptions about what constitutes a paragraph vs. a code block, for\nexample. The \"nicely formatted\" caveat simplifies the parser somewhat, enabling easier extension for\nnew features like special warnings, note boxes, and other custom directives.\n\nIn addition to my \"nicely formatted\" caveat, I am also only interested in supporting a very common\nsubset of all Markdown syntax, and ignoring anything I personally find useless or annoying to parse.\n\n### Things I Will Not Support\n\n- Setext headings\n- Thematic breaks\n- Embedded HTML\n- Indent-based code blocks (as opposed to fenced code blocks)\n\n## Usage\n\nThe current version of Zig this code compiles with is\n[0.14.0](https://ziglang.org/download/0.14.0/zig-linux-x86_64-0.14.0.tar.xz). I highly recommend\nusing the [Zig version manager](https://github.com/tristanisham/zvm) to install and manage various\nZig versions.\n\n```bash\nzig build run -- console test/sample.md\nzig build -l # List build options\nzig build -Dtarget=x86_64-linux-musl # Compile for x86-64 Linux using\n                                     # statically-linked MUSL libC\n```\n\n`zig build` will create a `zigdown` binary at `zig-out/bin/zigdown`. Add `-Doptimize=ReleaseSafe` to\nenable optimizations while keeping safety checks and backtraces upon errors. The shorthand options\n`-Dsafe` and `-Dfast` also enable ReleaseSafe and ReleaseFast, respectively.\n\n## Enabling Syntax Highlighting\n\nTo enable syntax highlighting within code blocks, you must install the necessary TreeSitter language\nparsers and highlight queries for the languages you'd like to highlight. This can be done by\nbuilding and installing each language into a location in your `$LD_LIBRARY_PATH` environment\nvariable.\n\n### Built-In Parsers\n\nZigdown comes with a number of TreeSitter parsers and highlight queries built-in:\n\n- Bash\n- C\n- C++\n- CMake\n- JSON\n- Make\n- Python\n- Rust\n- YAML\n- Zig\n\nThe parsers are downloaded from Github and the relevant source files are added to the build, and the\nqueries are stored at `data/queries/`, which contain some fixes and improvements to the original\nhighlighting queries.\n\n### Installing Parsers Using Zigdown\n\nThe Zigdown cli tool can also download and install parsers for you. For example, to download, build,\nand install the C and C++ parsers and their highlight queries:\n\n```bash\nzigdown install-parsers c,cpp # Assumes both exist at github.com/tree-sitter on the 'master' branch\nzigdown install-parsers maxxnino:zig  # Specify the Github user; still assumes the 'master' branch\nzigdown install-parsers tree-sitter:master:rust # Specify Github user, branch, and language\n```\n\n### Installing Parsers Manually\n\nYou can also install manually if Zigdown doesn't properly fetch the repo for you (or if the repo is\nnot setup in a standard manner and requires custom setup). For example, to install the C++ parser\nfrom the default tree-sitter project on Github:\n\n```bash\n#!/usr/bin/env bash\n\n# Ensure the TS_CONFIG_DIR is available\nexport TS_CONFIG_DIR=$HOME/.config/tree-sitter/\nmkdir -p ${TS_CONFIG_DIR}/parsers\ncd ${TS_CONFIG_DIR}/parsers\n\n# Clone and build a TreeSitter parser library\ngit clone https://github.com/tree-sitter/tree-sitter-cpp\ncd tree-sitter-cpp\nmake install PREFIX=$HOME/.local/\n\n# Add the install directory to LD_LIBRARY_PATH (if not done so already)\nexport LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HOME/.local/lib/\n```\n\nIn addition to having the parser libraries available for `dlopen`, you will also need the highlight\nqueries. For this, use the provided bash script `./tools/fetch_queries.sh`. This will install the\nqueries to `$TS_CONFIG_DIR/queries`, which defaults to `$HOME/.config/tree-sitter/queries`.\n\n## Sample Renders\n\n### Console\n\n![Sample Console Render](sample-render.png)\n\n### HTML\n\n![Sample HTML Render](sample-render-html.png)\n\n### Presentations\n\n![asciicast](https://asciinema.org/a/730075.png)\n\n[Demo](https://asciinema.org/a/730075)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjacobcrabill%2Fzigdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjacobcrabill%2Fzigdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjacobcrabill%2Fzigdown/lists"}