mdzk is a plain text Zettelkasten system that is based on the mdBook API.

Related tags

Miscellaneous mdzk


A lovingly designed system and static publishing tool for your plain text Zettelkasten

mdzk is a plain text Zettelkasten system that is based on the mdBook API. It consists of specialized preprocessors for handling key features such as wikilinks, backlinks and front matter, all tied together in the mdzk CLI. mdzk allows you to use whatever text editor you prefer - be it Obsidian, Vim, Visual Studio Code or even Notepad. You can view your notes with live updating as you edit them, have them automatically published to GitHub Pages on push and much more.


You can install mdzk with Cargo by running

cargo install mdzk

mdzk will soon also be available as a pre-built binary for quicker installation.

Getting started

We are still figuring out the exact user interface, so there would not be much help in a "getting started" guide just yet. mdzk works very much like mdBook, so you can use their guide for the time being. We hope to provide a full documentation very soon...

Important notes

  • Supported characters:

    These characters are disallowed in note filenames: =, `, ^, #, |, :, /, [ and ]. $ is supported, but not recommended, as it might intefere with the KaTeX math delimiters.

  • Trojan inside?

    Trojan inside?

    I just download the latest release 0.4.1 ( The download was blocked by threat protection of Windows 10.


    I'm using the latest Windows 10 build including the latest updates for threat protection.

    I also tried download release 0.4.0. Same effect.

    Any idea why this could be happening?

    opened by eBerdnA 13
  • Move around some of the configuration options

    Move around some of the configuration options

    This sadly has to be done because some options logically belong to other tables. These need to be moved:

    • ignore from [mdzk] to [build]
    • backlinks-header from [mdzk] to [style]
    • generate-summary from [mdzk] to [build]
    • Fold options from [output.html] to [style]
    enhancement breaking-change 
    opened by kmaasrud 9
  • Parentheses in note title is not parsed

    Parentheses in note title is not parsed

    For example, a note with a title How to Take Smart Notes (2017) by Sönke Ahrens was referred in another note as [[How to Take Smart Notes (2017) by Sönke Ahrens]], but it is parsed as <span class="missing-link" style="color:darkred;">How to Take Smart Notes</span> in the HTML generated by mdzk.

    opened by huangziwei 6
  • Linking to images?

    Linking to images?

    I'm not sure if I am using the library correctly. When I insert a wikilink to an image the output is noted in mdzk as a missing link. You can see an example here.

    For now I am hard coding img tags. Am I doing something incorrect or the syntax is different? It works in obsidian but when I publish it doesn't come out as knowing about the image.

    <img src="/Bins/Images/Wardley_Pioneers-Settlers-Town_Planners.jpg">
    opened by alanmbarr 6
  • Bad parsing when using mdzk with mdbook-toc

    Bad parsing when using mdzk with mdbook-toc

    I would like to use mdbook-toc to automatically add table of contents to my notes, but when I set it inside as a preprocessor it breaks mdzk parsing (backlinks doesn't work, metadata on top of notes doesn't get parsed).

    Is there a way to make them both work together?

    Current configuration:

    authors = ["author"]
    ignore = []
    language = "en"
    multilingual = false
    src = "notes"
    title = "mdzk"
    backlinks-header = "Backlinks"
    create-missing = false
    build-dir = "book"
    no-section-label = true
    enable = false
    enable = true
    level = 1
    command = "mdbook-toc"
    renderer = ["html"]
    opened by viniciusmuller 6
  • Collect metadata from front matter

    Collect metadata from front matter

    Signed-off-by: Matteo Joliveau [email protected]


    Ability to export all the metadata from the front matter to be processed by downstream tools

    Linked Issues/PRs/Discussions

    Closes #101

    opened by MatteoJoliveau 5
  • Fixed issue #62, KaTeX rendering cuts off

    Fixed issue #62, KaTeX rendering cuts off


    There was an issue with the LaTeX rendering.

    The problem was with pulldown_cmark. It sometimes splits the Text event into several pieces. When the split occurs inside a LaTeX entry, the entry is split into two and it is not converted into KaTeX. The best way to solve this is by using a new function that clears up the buffer until it sees an unmatched $ sign.

    Another problem that causes this issue is that the Text event does not contain the links as-is. So when there is a link like

    [Some Text](

    The buffer only has Some Text. Because of this, running ch.content.replacen() does not work since the buffer does not have the identical string as ch.content.



    Linked Issues/PRs/Discussions


    opened by theFr1nge 5
  • Custom folder representatives

    Custom folder representatives

    In Hugo, for example, _index is the markdown folder representative, on GitHub it's README.

    The current behaviour raises a warning duplicated page title found: .../ The current behavior shows _index as a sibling document.

    opened by lucasew 5
  • Add a note for init and header name Add a note for init and header name

    Just a little note to help anyone that uses it, since the project does not have a documentation, yet the mention to the init command helps compare mdbook config to mdzk, with special attention that without the head [mdzk] we get a:

    thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: Unable to represent the item as a JSON Value
    Caused by:
        unsupported None value', src/
    note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
    opened by bryanasdev000 5
  • Build fails while installing 0.3.5 through crate on Pop!OS 21.04

    Build fails while installing 0.3.5 through crate on Pop!OS 21.04

       Compiling mdzk v0.3.5
    error[E0658]: use of unstable library feature 'osstring_ascii'
      --> /root/.cargo/registry/src/
    61 |                 a.file_name().to_ascii_uppercase().cmp(&b.file_name().to_ascii_uppercase())
       |                               ^^^^^^^^^^^^^^^^^^
       = note: see issue #70516 <> for more information
    error[E0658]: use of unstable library feature 'osstring_ascii'
      --> /root/.cargo/registry/src/
    61 |                 a.file_name().to_ascii_uppercase().cmp(&b.file_name().to_ascii_uppercase())
       |                                                                       ^^^^^^^^^^^^^^^^^^
       = note: see issue #70516 <> for more information
    error: aborting due to 2 previous errors
    For more information about this error, try `rustc --explain E0658`.
    error: could not compile `mdzk`
    To learn more, run the command again with --verbose.
    warning: build failed, waiting for other jobs to finish...
    error: failed to compile `mdzk v0.3.5`, intermediate artifacts can be found at `/tmp/cargo-installOA68P1`
    Caused by:
      build failed
    opened by aquatix 5
  • nix: improvements

    nix: improvements


    The idea of this PR is to improve the Nix support of our application.

    • [x] GitHub Action to check if our package is building
    • [x] An overlay with the newest version
    opened by ratsclub 4
  • Fail to build mdzk version 0.5.2

    Fail to build mdzk version 0.5.2

    mdzk fails when building on github actions and on my computer by cargo install

    Default host: x86_64-unknown-linux-gnu
    rustup home:  /home/runner/.rustup
    stable-x86_64-unknown-linux-gnu (default)
    rustc 1.65.0 (897e37553 2022-11-02)
    /home/runner/.cargo/bin/rustup toolchain install stable
    info: syncing channel updates for 'stable-x86_64-unknown-linux-gnu'
    info: latest update on 2022-12-15, rust version 1.66.0 (69f9c33d7 2022-12-12)
        Compiling mdzk v0.5.2
      error[E0063]: missing field `extra_watch_dirs` in initializer of `mdbook::config::BuildConfig`
        --> /home/runner/.cargo/registry/src/
      36 |         Self {
         |         ^^^^ missing `extra_watch_dirs`
      error[E0609]: no field `livereload_url` on type `HtmlConfig`
        --> /home/runner/.cargo/registry/src/
      95 |         if let Some(ref livereload) = html_config.livereload_url {
         |                                                   ^^^^^^^^^^^^^^ unknown field
         = note: available fields are: `theme`, `default_theme`, `preferred_dark_theme`, `curly_quotes`, `mathjax_support` ... and 16 others
      Some errors have detailed explanations: E0063, E0609.
      For more information about an error, try `rustc --explain E0063`.
      error: could not compile `mdzk` due to 2 previous errors
      warning: build failed, waiting for other jobs to finish...
      error: failed to compile `mdzk v0.5.2`, intermediate artifacts can be found at `/tmp/cargo-installNcxbor`
    opened by ImGabe 0
  • Wikilink handler interface

    Wikilink handler interface


    This PR has a rewrite of how wikilinks are handled, which allows users of the API to add their own handlers to get custom functionality.


    None yet

    To do

    • [x] Main proof-of-concept interface
    • [x] Wikilink preprocessors and renderers
    • [ ] New tests for wikilink parsing
    • [ ] Revamp CommonMarkHandler to be more easily pluggable
    • [ ] Write docs
    opened by kmaasrud 3
  • Configurable link-style generation

    Configurable link-style generation

    Hi, it's me again!

    Currently fn fix_link(dest: CowStr) -> CowStr converts markdown links from something/ to something/something.html. This makes it difficult to support clean URLs (aka /my/page instead of /my/page.html). In my case, I actually generate HTML files as independent index.html files in dedicated directories. For instance, this is the conversion my SSG performs:

    | Source File | Generated File | Live URL | |:------------------------------:|:--------------------------:|:--------------:| | | index.html | / | | | an-article/index.html | /an-article | | a/nested/ | a/nested/index.html | /a/nested |

    Proposed solution

    Have the Vault accept an additional (optional) configuration flag that asks whether to generate clean URLs or not. Since the output of the actual HTML files is up to the caller, the only thing this flag does is change the behaviour of fix_link(). The flag can be false by default to keep the current behaviour as the default one.

    /// Generate /my/page.html and /categories/README.html links. Default behaviour
    /// Generate /my/page and /categories links

    Currently, I worked around this by parsing the generated HTML and applying some heuristics based on the current note path, fixing relative links and cleaning up file extensions, but it's cumbersome (around 60 LOC of pretty inefficient string manipulation) and the built-in solution would be much cleaner and more efficient.

    Alternatives I considered

    One alternative would be to skip Note::as_html and implement Markdown parsing myself using pulldown-cmark. That could work, and I may have to do it anyway in the future for stuff like custom HTML nodes, but I still think this could be a useful feature for use-cases that do not require such fine-grained control over the parsed DOM.

    opened by MatteoJoliveau 4
  • Can't read `mdzk.toml`

    Can't read `mdzk.toml`

    With the current main (d061a140e9437973f54c261c6440883b1781854c), when I try to build a site, I get:

    E TOML deserialize error: missing field `title` at line 1 column 1
      missing field `title` at line 1 column 1

    I get this even if I reduce mdzk.toml to:

    title = "Title"

    I feel like I'm missing something here. Is there an example of an mdzk.toml that works with the current code out there that I could look at?

    opened by jimkang 2
  • Determine behavior on equal titles

    Determine behavior on equal titles

    Equal titles are allowed, as the IDs serve as the one truth to what note is which. However, ID lookup and internal link creation can be ambiguous when notes share an equal title. We need to determine how mdzk should handle this.

    Currently, looking up an ambiguous title returns the last note walked. The walk happens randomly, so this behavior is not consistent, though it might be the best we can get without sacrificing performance. Giving the user a warning would likely be the most sensible solution.

    opened by kmaasrud 0
  • 0.5.2(Feb 22, 2022)

    You can download this release through any of the following package managers:

    | Package manager | Command | | ------------------ | ---------- | | Cargo | cargo install mdzk | | AUR (with Paru) | paru -S mdzk | | Homebrew | brew install mdzk | | Nix | nix shell nixpkgs#mdzk |



    • #70: Fixed issue where parentheses were not allowed in internal links.

      577e84c: allow non-square brackets in internal links

    Source code(tar.gz)
    Source code(zip) MB) bytes) MB) bytes) MB) bytes)
    mdzk-0.5.2-x86_64-unknown-linux-musl.tar.gz(7.40 MB)
    mdzk-0.5.2-x86_64-unknown-linux-musl.tar.gz.sha256sum(110 bytes)
  • 0.5.1(Feb 21, 2022)



    • #66: All CSS variables can now be changed directly in the configuration file. For example, say you want to set the variable --sidebar-bg to red. To do this, you can simply add

      sidebar-bg = "red"

      This should work for all CSS variables.

    • #66: Add any custom CSS through the configuration file. You can either write CSS as a string directly in mdzk.toml, like this:

      additional-css = """
      <CSS here>

      or you can load a separate CSS file, like this:

      additional-css = "path/to/file.css"

      Paths are relative to the mdzk.toml file.


    • #66: mdzk now has a custom renderer and a new look. Everything should look more clean and polished, and you can expect some performance improvements as well.
    • #66: KaTeX is no longer loaded through a CDN, but written to the generated site. This means your mdzk will work offline as well.
    • #66: The default renderer is no longer mdbook, but mdzk. You can change back to rendering with mdBook by adding --renderer mdbook after the build command.


    • #67: You could previously not use ? characters in a title, because they were not escaped properly in URLs. This is now fixed with the introduction of our custom renderer.
    • #66: Note titles are now added to the search index as well.


    • #66: You can no longer theme mdzk like in mdBook (by adding a directory called theme). See above for how you can customize your mdzk.
    Source code(tar.gz)
    Source code(zip)
    mdzk-x86_64-apple-darwin(14.64 MB)
    mdzk-x86_64-linux(20.33 MB)
  • 0.5.0(Jan 3, 2022)


    New features

    • #55: You can now turn off each preprocessor feature of mdzk separately. This is done with the following configuration values:

      # ...
      front-matter = false
      math = false
      readme = false
      math = false

      More about these features and what they do, can be found in the documentation.

    • #39: Wikilinks now support blockreferences. Mark a paragraph with an ID by appending it with a space, a ^ and then a six-character ID. Then you can link to this paragraph, by using the syntax [[Note^#id]], where Note is the name of the note and id is the ID of the paragraph. You can read more about blockreferences in the documentation.


    • #54: Our separate preprocessor crates are now moved to within the mdzk crate. This allows us to avoid iterating over the vault multiple times, which drastically increases the efficiency.
    • #45: New custom made user interface, for a friendlier look. Expect more informative messages from this update and on.
    • Enabled pulldown-cmark's SIMD accelerated scanners.

    Bug fixes

    • #63: Fixed buggy KaTeX rendering and simplified the rendering code a lot. Special thanks to @TheFr1nge for fixing this.
    • #41: mdzk will not panic on invalid TOML anymore, but rather print an error message coupled with the configuration content and a description of what part of it is invalid.
    • #40: mdzk now checks whether you updated your mdzk.toml correctly or not. If a [book] section is found in your mdzk.toml file, a warning will appear that prompts the user to change it to [mdzk].
    • When loading the mdzk from another directory than the root directory, parsing the summary would throw an error, as the path to it was not absolute. This is now fixed, which means you can build an mdzk located anywhere, from anywhere.
    Source code(tar.gz)
    Source code(zip) MB) bytes) MB) bytes) MB) bytes)
    mdzk-0.5.0-x86_64-unknown-linux-musl.tar.gz(5.66 MB)
    mdzk-0.5.0-x86_64-unknown-linux-musl.tar.gz.sha256sum(110 bytes)
  • 0.4.3(Nov 1, 2021)


    New features

    • New generate-summary key at the [mdzk] section in mdzk.toml that controls whether mdzk will generate your summary file automatically or not. The default value is true.

    • New preprocessors field under the [build] section in mdzk.toml. This lets you define mdBook preprocessors to be run after the default preprocessors. Order is preserved.

    • New draft option in the front matter. Setting this to true will skip rendering for that note.

      NOTE: Beware that the note will still show up in the index, as that is how mdBook handles draft chapters. We will probably change this behaviour as soon as we release our custom renderer. If you want to hide a note completely from your vault, use the ignore field in mdzk.toml.


    • Removed several dangerous unwraps, to make the codebase more robust.
    • The Nix build now supports Apple Silicon as well.
    • Dependencies have been cleaned up, leading to a slightly smaller binary size.
    • New version of mdbook-wiklinks (0.4.0), that replaces regexes in favor of a combination of pulldown-cmark's iteration and a custom Pest parser. This should decrease build times drastically.
    • Math delimiters are now converted into spans/divs on build. This will hopefully make KaTeX support more robust, and ignore math rendering within code and links.

    Bug fixes

    • #38: User-defined preprocessors (through the mdBook-style preprocessor.<name> pattern in the config file) would sometimes interfere with mdzk's default preprocessors. This fix converts all of these preprocessor-statements into the preprocessors field mentioned above, which mdzk can handle the order of.

      NOTE: To simplify compatibility between mdzk and mdbook, we assume the preprocessor has a command on the form mdbook-<name>. Other preprocessors are simply not supported yet. Fields are ignored, so you can only turn preprocessors on or off.

    • #24: mdzk.backlinks-header in the config had no defuault value, which made mdzk panic when it was not set. This is now fixed.

    Source code(tar.gz)
    Source code(zip) MB) bytes) MB) bytes)
  • 0.4.2(Sep 24, 2021)

    This is a quick update that should make compiling mdzk easier (and even possible) for Windows users.

    We have also experienced some trouble with Windows Defender flagging pre-compiled mdzk binaries as a trojan. This is a false positive. A report is submitted to Microsoft, and we have removed all previously released Windows binaries. We suspect the warning is related to the amount of embedded JavaScript that is contained in mdzk. Hopefully, you will not get any warnings from this version and onwards. If you do, please leave a comment with a screenshot of the warning in this issue.


    New features

    • When naming a file the same name as it's parent directory, this file will work as the content of that directory. Namely, the directory will itself function as a note.

    Bug fixes

    • Our dependency on mdbook-katex, and subsequently QuickJS, did not work well with most Windows computers. To circumvent this, KaTeX is now loaded from a CDN and handles the rendering client-side. This shouldn't lead to any significant increases in load time, but it is not ideal for offline usage. We are working on embedding KaTeX locally in the generated output, which hopefully will be included soon.
    Source code(tar.gz)
    Source code(zip) MB) bytes)
    mdzk_0.4.2_x86_64-unknown-linux-musl.tar.gz(6.55 MB)
    mdzk_0.4.2_x86_64-unknown-linux-musl.tar.gz.sha256sum(64 bytes)
  • 0.4.1(Sep 23, 2021)

  • 0.4.0(Sep 21, 2021)

    With version 0.4.0, we finally supply pre-compiled x86 binaries for Linux. On other devices/architectures, you have to compile mdzk yourself - using cargo install mdzk. We hope to supply binaries for these platforms as well soon.


    Breaking changes

    • The [book] table header in mdzk.toml is now changed to [mdzk]. You will need to change this in your own configuration, or else the values will be ignored.
    • The disable-default-processors configuration option is now placed under the [build] table.

    New features

    • An ignore field is added under the [mdzk] table. This is a list of gitignore-style patterns that specify files or directories which mdzk should ignore when building.
    • The header above the backlinks can now also be configured under the [mdzk] table, with the backlinks-header field. Both this and the previous preprocessor.backlinks.header field are supported, but you are recommended to use the former, in case we might remove the latter.
    • You can now choose a renderer with the --renderer or -r flag when running build or serve. The choices are between mdbook, markdown or mdzk, the latter being our own work in progress custom renderer. This feature is mostly for debugging purposes.


    • We now use our own configuration struct. This will allow us to more easily expand mdzk with more options and configuration.
    • The mdzk renderer now copies over KaTeX locally in the output, to ensure speedy math rendering.
    • The mdzk renderer now uses the Inter font.
    Source code(tar.gz)
    Source code(zip)
    mdzk_0.4.0_x86_64-unknown-linux-musl.tar.gz(6.97 MB)
    mdzk_0.4.0_x86_64-unknown-linux-musl.tar.gz.sha256sum(64 bytes)
A preprocessor for mdbook to add Material Design admonishments.

mdbook-admonish A preprocessor for mdbook to add Material Design admonishments, based on the mkdocs-material implementation. It turns this: ```admonis

Tom Milligan 65 Jan 8, 2023
Modrinth API is a simple library for using, you guessed it, the Modrinth API in Rust projects

Modrinth API is a simple library for using, you guessed it, the Modrinth API in Rust projects. It uses reqwest as its HTTP(S) client and deserialises responses to typed structs using serde.

null 21 Jan 1, 2023
API wrapper for the tankerkönig api

tankerkoenig-rs API wrapper for the tankerkoenig-api written in rust. Gives you ready deserialized structs and a easy to use and strictly typed api. I

Jonathan 2 Feb 27, 2022
A repository full of manually generated hand curated JSON files, which contain the API Types that the Discord API returns.

Discord API Types A repository full of manually generated hand curated JSON files, which contain the API Types that the Discord API returns. Also did

Unofficial Discord Documentation 1 Sep 16, 2022
A Rust Based GMod Module for finding system info.

gm_sysinfo Fetching System Information in Rust to Lua. Installation Download the Module. Compile it. Cry because it doesn't work. Spend 2 hours debugg

Joshua Piper 3 May 18, 2022
Log your spending in seconds with short text snippets. Powered by Rust, Cloudflare Workers and Svelte.

FastSpend Log your daily spending lightning fast with short text snippets! FastSpend is a tool to log your spending in seconds, powered by a lightning

Phoomparin Mano 24 Sep 13, 2022
🛠️ | System tool for all my lovers

<<<<<<< HEAD ?? love-fetch Original code ferris-fetch ?? ??️ System tool for all my lovers ?? How to install it ?? cargo install love-fetch License ??

Fabio Grimaldi 11 Jun 13, 2021
A simple entity-component-system crate for rust with serialization support

Gallium A simple entity-component-system crate for rust with serialization support Usage You can include the library using carge: [dependencies] galli

null 7 Aug 31, 2021
secmem-proc is a crate designed to harden a process against low-privileged attackers running on the same system trying to obtain secret memory contents of the current process.

secmem-proc is a crate designed to harden a process against low-privileged attackers running on the same system trying to obtain secret memory contents of the current process. More specifically, the crate disables core dumps and tries to disable tracing on unix-like OSes.

null 3 Dec 19, 2022
A supposed operating system.

mold This supposedly does something. Building This project is using a simple build script written in fish, which automates the process of compiling th

Aodhnait Étaín 2 Nov 29, 2021
A Garry's Mod module that lets you check which fonts are available on the system

gm_fontsx Since apparently we're never getting a proper way to check for installed fonts on Garry's Mod, this has to exist ?? Usage require("fontsx")

Earu 4 Mar 14, 2022
A dead-simple, extreme fast permission flag system for Rust with no dependencies

A dead-simple, extreme fast permission flag system for Rust with no dependencies

pan93412 2 Mar 17, 2022
Notion Offical API client library for rust

Notion API client library for rust.

Jake Swenson 65 Dec 26, 2022
Rust lib for Scaleway API

Notes This Scaleway API Crate is created and maintained by Qovery and used in production in the Qovery Engine. This project relies on OpenAPI Generato

Qovery 5 Nov 10, 2022
The official rust implementation of the SpamProtectionBot API

SpamProtection-rs Table of contents About Supported Rust version Features How to use Credits License About SpamProtection-Rust is a Rust wrapper for I

Intellivoid 0 Feb 26, 2022
An asynchronous Rust client library for the Hashicorp Vault API

vaultrs An asynchronous Rust client library for the Hashicorp Vault API The following features are currently supported: Auth AppRole JWT/OIDC Token Us

Joshua Gilman 59 Dec 29, 2022
Rust bindings for the KING OF TIME API

Rust bindings for the KING OF TIME API Example Prints if you are at work or not at work. $ cargo run --example tc -- status Record the time you start

Idein Inc. 2 Oct 11, 2021
A Rust API for D-Bus communication.

zbus A Rust API for D-Bus communication. The goal is to provide a safe and simple high- and low-level API akin to GDBus, that doesn't depend on C libr

Michael Murphy 2 Nov 6, 2021
A library to access BGPKIT Broker API and enable searching for BGP data archive files over time from public available data sources.

BGPKIT Broker BGPKIT Broker is a online data API service that allows users to search for publicly available BGP archive files by time, collector, proj

BGPKIT 10 Nov 30, 2022