Skip to content

Home

Current state / Main goals

  • Migrate SSG

    Migrate MkDocs setup to Zensical.

    The initial effort is as plug and play as they say. Remove all your python dependencies, add zensical to dev, disable your custom overrides (for now) and run. Your mkdocs config should build just fine. I highly recommend switching your pip setup to uv while at it.

    The devil's in the details of course. Zensical knows the basics23 but is far from feature complete (remember those thousands of extensions for hacking into MkDocs) and you cannot easily extend yet1 (which is totally fine as it is still v0.x). I'm looking forward to the implementation of the blog plugin, which is listed in Tier 2.

    See warning below for expected changes to the markdown parser.

    Getting started Playground

  • Publish from Obsidian

    Assess workflows to directly publish specific notes from Obisidian. Currently investigating Enveloppe. The idea behind this is to have a generic SSG based on Markdown that can be populated by multiple sources where Obsidian just acts as one source of many.

    When looking to publish an Obsidian vault full scale with proprietary features like graph (e.g. for internal company documentation), use Quartz instead. It works great.

    Enveloppe Quartz Markdown

  • Preview snippets

    Find a way to easily share, annotate and comment code snippets that cannot be "compiled" together in a sensible / maintaineable way.

    E.g. embedding a gist (either on GitHub or self-hosted) in an issue or discussion is not allowed due to (necessary) security measures. Linking images can be a hassle too, if that image is not static but supposed to be updateable (regenerated / changed).

    You will end up authoring parts of one context in multiple sources and systems to keep it all together -- or rather you will not do it ending with shattered topics of broken links outdated images, lost annotations, etc.

    Being able to generically push the sidecar "fluff" (render images, embedding gists, notes) removes the decentralized authoring part. You link to the source and to the fluff. It stays consistent even when breaking.

Careful

Zensical runs on Python Markdown (a legacy inherited from MkDocs) which was never meant to support modern Markdown implementations. It needs tons of extensions to render common syntax and yet still breaks on things like Obsidian / GFM style callouts vs admonitions.

Zensical announced that they will correct this and change to CommonMark soon.4

Until that happens, I suggest not putting any effort into syntax related rendering stuff, because you will (and should) start from zero once the migration to CommonMark is done.

Backlog

  • Abbreviations like HTML up and running
  • Render tables with {{ pd_read_csv("data/team.csv") | convert_to_md_table }}
  • Render Obsidan / GitHub style callouts. waiting for CommenMark transition
  • Migrate relevant (!) old overrides according to new partials in .venv\Lib\site-packages\zensical\templates\partials, e.g.
    • comments
    • tags feature not fully implemented yet
    • removed
      • https://unpkg.com/@popperjs broken
      • https://unpkg.com/tippy.js redirect
      • https://cdnjs.cloudflare.com/ajax/libs/font-awesome broken
  • Make use of tag.url documentation missing
  • get some structure into the nav folders, which are generated from frontmatter values for Obsidian published notes
    • planned navigation module not yet implemented
    • Fall back to generating the folder structure from frontmatter with Enveloppe

  1. https://zensical.org/about/roadmap/#module-system ↩

  2. https://zensical.org/compatibility/features/ ↩

  3. https://zensical.org/compatibility/plugins/ ↩

  4. https://zensical.org/docs/setup/extensions/about/ ↩