https://github.com/pmeinhardt/maxdown
for you @klappradla 👋
https://github.com/pmeinhardt/maxdown
cli html markdown neovim preview vim
Last synced: 6 months ago
JSON representation
for you @klappradla 👋
- Host: GitHub
- URL: https://github.com/pmeinhardt/maxdown
- Owner: pmeinhardt
- License: mit
- Created: 2023-02-13T15:31:08.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-05-10T19:15:06.000Z (about 1 year ago)
- Last Synced: 2025-05-13T04:55:10.180Z (about 1 year ago)
- Topics: cli, html, markdown, neovim, preview, vim
- Language: HTML
- Homepage:
- Size: 689 KB
- Stars: 5
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Maxdown 🚲
[](https://github.com/pmeinhardt/maxdown/actions/workflows/build.yml)
Maxdown is a simple and fast Markdown-to-HTML converter. It comes with a command-line interface and an integration for (Neo)Vim.
## Before you get going 🐿️
You will need [`cargo`](https://doc.rust-lang.org/cargo/index.html) in order to build the `maxdown` command-line tool.
In case you are using [Homebrew](https://brew.sh/), it should be as easy as `brew install rust`.
## Installation 🪛
### Command-line tool
If you're only interested in the `maxdown` command-line tool, you can build it by running:
```shell
cargo build --release --locked
```
Then, just put the resulting `target/release/maxdown` binary somewhere on your `PATH`.
### Command-line tool via Homebrew
Alternatively, you can install `maxdown`, built from source, via Homebrew:
```shell
brew install --HEAD pmeinhardt/tools/maxdown
```
To update, use:
```shell
brew upgrade --fetch-HEAD pmeinhardt/tools/maxdown
```
### Vim plugin
For the Vim plugin, if you use [vim-plug](https://github.com/junegunn/vim-plug), add this line to your Vim configuration file:
```vim
Plug 'pmeinhardt/maxdown', {'do': ':MaxdownCompile'}
```
If you have a different way of managing your Vim plugins, make sure you add the project directory to your `runtimepath` and build the command-line tool:
```sh
cargo build --release --locked
```
Or, to build from within Vim:
```
:MaxdownCompile
```
## Usage ⌨️
### Command-line tool
The `maxdown` command-line tool reads Markdown from `stdin` or a file and outputs HTML to `stdout` or a file.
For instance:
```sh
echo 'Hello *World*!' | maxdown
maxdown README.md
```
To learn about the extra knobs and switches, kindly ask `maxdown` for help:
```
$ maxdown --help
Convert Markdown to HTML
Usage: maxdown [OPTIONS] [PATH]
Arguments:
[PATH] Path to the input Markdown file [default: stdin]
Options:
-b, --base Base URL to use for all relative URLs in the document
--dangerous Only use this if you trust the authors of the document
-o, --output File to write output to [default: stdout]
-t, --template Template to use for output [default: built-in template]
--title Title to pass to the template [default: Preview]
-h, --help Print help
-V, --version Print version
```
### Vim plugin
To preview the current markdown buffer, invoke `:MaxdownPreview`.
Alternatively, define a custom mapping. For instance:
```vim
autocmd FileType markdown nnoremap m MaxdownPreview
```
This will create a normal-mode mapping to preview the current markdown buffer.
To replace the current Markdown buffer's content with the corresponding HTML, use `:MaxdownConvert`.
If you have other use cases, you always have the option of defining your own custom commands and mappings using the command-line tool.
## Enhancements 🪄
With the `ql` [Vim plugin](https://github.com/pmeinhardt/ql), previews on macOS will look more neat (no `[DEBUG]` in the title):
```vim
Plug 'pmeinhardt/ql', {'do': ':QuickLookCompile'}
```
## Thanks ❤️
Maxdown is built on top of the impressive work of other people:
- markdown-rs: https://github.com/wooorm/markdown-rs
- minijinja: https://github.com/mitsuhiko/minijinja
- clap: https://github.com/clap-rs/clap
- trycmd: https://github.com/assert-rs/trycmd
- github-markdown-css: https://github.com/sindresorhus/github-markdown-css