Skip to main content

Markdown tools

Update: since writing this post I created braindb to address all issues described below

So you have folder with markdown files. It can be static website, it can be Obsidian vault, second brain, digital garden, zettelkasten, notes…

And you want to do something with it. There are a lot tools for that:

  • “second brain” editors: Obsidian, Foam, Roam Research, etc.
  • static website generators: Hugo, Astro, etc.

And everything in between:

One more tool #

We already have plenty. What shall we do? Obviously, create another one.

What I want minimum:

  • Given there is a folder with markdown files
  • it (tool) reads files and parses markdown
  • it resolves wikilinks and relative links
  • (optional) it stores data in embedded database, for example SQLite
  • it builds graph (as a data structure, not a visualisation)
    • which would allow to check for (local) broken links (also images, header-ids)
    • build visualisation
    • export graph - to work with graph in other tools, like NetworkX etc.
  • It dumps files (with resolved links) to another folder
  • It dumps grpah structure to JSON file (or any other format)

What I want maximum:

  • watch mode
  • UI (TUI or GUI) to query data with SQL/Cypher/Datalog…
  • plugins, for example:
    • to convert code fences to diagrams (inline or vfile)
    • to generate social images
  • LSP
  • implement as library so other software could reuse it, for example, Astro, VScode, Obsidian, etc.
  • linter and pretty-printer

Preliminary ideas about implementation #

Read more: Documentation generators, BEOE