rysana-ai / bundown

Bundown is a fast all-in-one Markdown runtime and bundler, built on Bun.

Bundown is a fast all-in-one Markdown runtime and bundler.

You can install bundown (bd) globally using Bun:

bun i -g bundown

Bundown runs TS, JS, and Shell code. It pretty-prints and syncs code in almost any language.

Links

• Usage
• Changelog
• Contributing
• Roadmap
• Scripts
  • Format
• Source
• MIT License

Usage

• bundown run to run a Markdown file from a path or URL
• bundown sync to pack/unpack code between files and Markdown
• bundown -h to view help
• bundown upgrade to update Bundown

Changelog

See what's planned in the roadmap.

^0.1.2

• Improvements
  • bundown --print uses improved box drawing for run & sync code printing.

^0.1.0

• Features
  • bundown run <file> now aliases bundown <file>.
  • bundown sync synchronizes Markdown codeblocks with actual code files using file tags in the codeblock metadata:
    • --file <file> (-f) in a codeblock meta header sets the corresponding file.
    • bundown <file> does not run code blocks with a --file flag.
    • bundown sync <file> <dir> (over)writes files in <dir> with corresponding codeblocks from <file>.
    • bundown sync <url> <dir> downloads and over(writes) the files in <dir> with codeblocks from <url>.
    • bundown sync --print (-p) pretty-prints the synced files.
  • bundown https://example.com/file.md runs a Markdown file from a URL.
  • bundown --tag <tag> <file> (-t) runs only code blocks with the specified tag.
    • --tag <tag> (-t) in a codeblock meta header tags the codeblock with <tag>.
    • bundown <file> does not run code blocks with a --tag flag.
  • bundown auto-detects operating system and only runs corresponding codeblocks.
    • --os <os> in a codeblock meta header tags the codeblock with <os>.
    • linux and macos/darwin are supported <os> tags.
  • bundown <dir> auto-detects the best potential default file like readme.md and runs it.
• Improvements
  • bundown now has a block-level args parser for advanced features.
  • bundown now uses abstract syntax trees to parse and manipulate Markdown.
  • bundown --print uses syntax highlighting for code blocks and rich text.
• Languages
  • bundown can print and sync: c, cuda, c++, c#, css, diff, go, graphql, .gitignore, html, arduino, java, javascript, json, jsx, kotlin, less, lua, makefile, markdown, objective-c, perl, php, python, r, ruby, rust, scss, shell, sql, svg, swift, toml, tsx, typescript, xml, vb.net, wasm, yaml, and many aliases for the aforementioned.

^0.0.10

• Improvements
  • bundown upgrade fixed.

^0.0.9

• Improvements
  • bundown checks that the user has bun@^1.0.24 installed and reports a helpful error message if not.

^0.0.8

• Improvements
  • bundown upgrade upgrades bundown to the latest version.

^0.0.7

• Improvements
  • package.json now lists runtime dependencies.

^0.0.6

• Features
  • bundown --version (-v) prints the version of bundown installed.
  • bundown --print <file> (-p) pretty-prints the Markdown and syntax highlighted code blocks.
  • bundown --help (-h) prints a help message.
• Improvements
  • bundown now uses ANSI colors for more helpful usage messages & pretty-printing.

^0.0.5

• Features
  • bundown recognizes languages regardless of case, allowing uppercase language names in code blocks.
• Improvements
  • bundown now uses a single parser loop to run faster in less lines of code.

^0.0.4

• Features
  • bundown can run multiple instances at once.
  • bundown returns the same exit code as the code it ran.

^0.0.3

• Improvements
  • bundown has developer tooling including biome code formatting via bundown and a .gitignore file.

^0.0.2

• Improvements
  • bundown doesn't skip a code block if a supported language is specified in full but has extra whitespace/content on the language line.

^0.0.1

• Features
  • bundown <file> runs TypeScript, JavaScript, and Shell code blocks in Markdown files.
  • bundown can be installed globally using npm, bun, pnpm, or yarn and run from anywhere.

Contributing

If you have any bugs, feature requests, etc. please open a discussion, issue or pull request as appropriate.

Before you open a PR, use this script to format the code with biome. We use an opinionated style guide, aimed at maximizing the intuitive readability of code and minimizing noisy syntax - follow it.

We also have a roadmap of planned features and bugs we'd like to fix if you'd like to pick one up:

Roadmap

See what's already been done in the changelog. Please suggest changes.

• Features
  • bundown sync <url> <file> downloads and over(writes) the Markdown file from <url> into <file>.
  • bundown sync <dir> <file> (over)writes codeblocks in <file> with corresponding files from <dir>.
    • --no-new-blocks does not create new codeblocks in <file> for files in <dir> without corresponding codeblocks.
  • bundown sync bundown.md . is used to sync the bundown codebase from a single file.
  • bundown sync --delete deletes files/blocks in the destination that don't exist in the source.
  • bundown --interactive <file> (-i) pretty-prints each code block before running with a Y/N prompt to run it.
  • bundown detects potentially unsafe code and prompts the user to run interactively if so.
  • bundown uses source mapping to deliver helpful and traceable error messages when code blocks or individual lines of code fail.
  • bundown ai uses the core runtime, pretty-printing, and safe execution to deliver a great private, local, open-source alternative interface to LLM chat/search/code apps.
  • ... | bundown can be used to pipe Markdown into bundown instead of using a file path.
  • bundown tasks allows you to view and manage task lists.
  • bundown.config.md allows a user to set a custom color theme for Bundown.
• Improvements
  • bundown should safely escape the content of Shell code when compiling to TS.
  • bundown --print visually formats Markdown segments (code, links, etc.) beyond just syntax highlighting.
  • bundown --print supports GFM style autolinks.
  • bundown --print supports GFM style task lists.
  • bundown --print supports GFM style tables.
  • bundown --print supports GFM style footnotes.
  • bundown --print converts emoji codes like :fire: to actual emojis.
  • bundown --print pretty-prints math e.g. replacing common TeX characters e.g. \pi to π.
• Languages
  • bundown shares variables and functions between code blocks, regardless of language.
  • bundown can print and sync: sass, zig, assembly, haskell, lisp, clojure, julia, brainfuck, latex, and more?
  • bundown can run: python, c#, c++, c, zig, rust, php, go, ruby, lua, assembly, wasm, lisp, clojure, julia, brainfuck, and more?

Scripts

If you have Bundown installed, you can run any of the following scripts with bundown -t <script>

Format

We use biome to format our code.

To format all files in the project, make sure you have biome installed and run:

bun x biome format --write .

bundown's Issues

About the scope of the roadmap

I have few comments about the roadmap, and since discussions are not enabled in this repo, I will write them down here.

We are using markdown tags for bash and other shell variants to mark sections to be executed by the new bun shell syntax.

However, those are neither bash nor zsh.
For example, things like for cycles do not work, and the syntax is somewhat divergent from any specific shell, favoring the integration with js/ts. This design decision/limitation is totally fine within the scope of bun shell, but considering that you envision support for multiple languages as part of the roadmap, this would leave shell scripting far behind in terms of compatibility.

In my opinion, the only way to have a true portable bash would be to compile it for webassembly, and pack it with the application, or to manually exec it hoping the system has minimal support for it, which was one of the main reasons why bun shell was made in the first place.

Tabs seem to break box-drawing in print mode

I was playing around with #9 locally today and it seemed that a tab for indentation in a code block caused the box drawing in print mode to miscalculate the width of that line, forcing the right border of the box onto a new line in my terminal.

We should probably preprocess tabs out of code blocks and replace them with a couple spaces each or something before printing happens.

Source mapping, block step execution & line step execution.

I think it would be relevant to have some form of source mapping, so that errors in the execution of the generated script can be traced back to the original markdown file.

Two more nice to have in my opinion are block stepping and line stepping the execution of the file. This would give the user a chance to review what is going to be run, which is important if we are just taking and trusting a random file from the internet.

It would also be nice because I am integrating bundown with ollama and some self-hosted model to comment on the nature of the code which is going to execute, so that the inexperienced user can have a better-than-0 context about the operations which are going to be performed, if they are potentially dangerous or at the very least on what to expect.

Please, let me know what you think about these features and if they are desirable in bundown mainline.