BEOE

It should be easy to add diagrams to your Markdown documentation. There are many solutions that can render diagrams inside Markdown; for example, see Asciidoctor.

However, if you want to add a custom diagram, it can be tedious to implement. Core idea: If you have a function that can produce a diagram as SVG, it should be trivial to use it in Astro (or other SSGs that use remark/rehype).

It should be easy to create documentation with many diagrams, like in Byrne's Elements of Euclid.

Status

I have implemented core packages and added some examples. However, I still need to add more tests, configure CI, create a demo site, and address the remaining TODOs.

Packages

Core

• @beoe/rehype-code-hook
• @beoe/sqlitecache
• @beoe/cache
• @beoe/remark-code-hook
• @beoe/pan-zoom

Diagrams

	rehype
Graphviz	@beoe/rehype-graphviz
Mermaid	@beoe/rehype-mermaid
Gnuplot	@beoe/rehype-gnuplot
Vizdom	@beoe/rehype-vizdom
D2	@beoe/rehype-d2
Penrose
...

Ideas for other diagrams: Text to Diagram.

Logo

The logo is an illustration from Oliver Byrne's Elements of Euclid: The First Six Books with Coloured Diagrams and Symbols.

TODO

• rehype-code-hook-img maybe
  • reuse svgStrategy in all plugins
  • add processMeta to all plugins, so it would be possible to configure class and strategy
  • try to implement external file strategy (with vfile)
    • basePath: "src/.generated"?
    • https://docs.astro.build/en/guides/images/#images-in-markdown-files
    • loading="lazy" decoding="async"
    • ~/.generated/*
  • maybe rename strategies