AnyBlock: one Markdown extension library rendered through five hosts

A selector and a processor, applied to ordinary Markdown

AnyBlock is a module and plugin for parsing and rendering highly versatile Markdown extensions. The feature description is a bit compressed, so the mechanics are worth pulling apart.

The README's own formulation of the feature is that you can flexibility to create a 'Block' by many means, and it provides useful features like 'list to table' and so on. The detailed version says you can select a section by list, heading, table, quote, code block or markdown-it container, written with triple colons, and turn it into a table, tabs, dir, card, column, mindmap, markmap, mermaid, PlantUML, timeLine, jsonChart, nodeTree and more.

So the model is a two-step pipeline. A selector picks a region of the document, using something that already exists in Markdown rather than something new, and a processor renders that region into a richer structure. A list becomes a table. A list becomes a tab set. A heading and a list become a mindmap. The same source document can be rendered completely differently depending on which processor you attach.

That is what makes the library reusable across hosts. The parsing and the rendering logic does not depend on Obsidian, and the five host packages are thin adapters over a shared core.

The README is careful to say the list of processors shown in the effects gallery is only a few of them, and that the processors can be freely combined in series, and that besides the list selector it supports many other selectors such as headings, code blocks and quote blocks. A pipeline of several processors is therefore possible, which is a different thing from a single transform.

The same core, built for five different hosts

The same document logic has to run in five different editors, and the package manifest shows how that becomes a build. The root scripts fan out into a build per host:

		"build": "pnpm run ob:build",
		"build-min": "pnpm run ob:build-min",
		"ob:build": "cd ./src/Obsidian && pnpm build",
		"mdit:build": "cd ./src/MarkdownIt && pnpm build",
		"app:build": "cd ./src/App && pnpm build",

The `ob:` prefix is Obsidian, `mdit:` is Markdown-it and `app:` is the standalone web application, each of them a separate package under `src/` with its own pnpm build. The root `build` script runs the Obsidian build, `build-min` runs the reduced one, and `bump` calls a version script.

Two build outputs sit at the root, `dist-min/` and `dist-pro/`, and the README links a separate repository for a min-sized version of the plugin that you can download manually or install with the BRAT plugin, which is the Obsidian community's answer to a plugin that is not in the official store.

Everything is driven by pnpm, with `[email protected]` as the declared package manager, a `pnpm-workspace.yaml` at the root, and Node 20.6.0 or newer required. The build tool is Vite, with `vite.config.mjs` at the root and a `tsconfig.base.json` and `tsconfig.json` pair for the TypeScript configuration. The `styles.css` file and `manifest.json` handle the Obsidian side of the packaging, and `version-bump.mjs` with `versions.json` handles versioning across the host packages.

Syntax free, and why that is a deliberate constraint

The Lightspot section of the README states the design principles, and the first one is the one that most affects how you use it.

Syntax free. No new syntax, syntax-free intrusion. And the reasoning given is that this also leads to no excessive reliance on plugins, with the author's argument that a good plugin should not cause that when you have used the plugin for a period of time, leaving it will cause the original content to deform, become unreadable or maintainable.

That is a genuinely different bet from most Markdown extension projects, which add a directive syntax and then leave the documents unparseable without the plugin. A document that only uses existing Markdown constructs, plus a processor configuration held outside the document, keeps working when the plugin is gone. For a tool that has to run in Obsidian, in a static site generator and in a browser editor simultaneously, that property is close to a requirement, since the three hosts have different ideas about what syntax they tolerate.

The other principles are Extensible, described as facilitating secondary development, and Flexible and powerful, with the selector described as flexible with six selection methods and the processor as rich and diverse, powerful in function and highly scalable. And then multi-platform, strong universality: an Obsidian plugin, a Markdown-it plugin, an online app and a Vuepress plugin, and blogs such as Vuepress or Vitepress that support Markdown-it parsing.

The cost of syntax freedom is that the reader of a document cannot tell what a block will become. A list renders as a plain list in a reader that has no AnyBlock, and as a table or a mindmap in one that does. For a personal knowledge base that is a good trade. For documentation that other people will read in a plain viewer, it means the fallback rendering has to be good on its own, and the library's own decision to make the list-to-table transform the most prominent example suggests that the plain list is expected to remain the readable fallback.

The processor catalogue, from list to table to mindmap

The effects gallery in the README is the best catalogue the project offers, and it is organised by the visual result rather than by the underlying operation.

The table family comes first, with multiWay table, multiCross table and Cross table shown together, and then ListTable, TreeTable and TreeGrid. The README explains that the optimised list is listtable with a mock list style added, and the Dir Tree is listtable with an imitation directory style.

The tree family follows, with Dir Tree on the same listtable foundation but the addition of imitation directory style, and an ASCII Dir Tree variant. There is a WBS, a Work Breakdown Structure, and a timeline.

Then the diagram family, which is the widest part of the catalogue. Tabs and card are shown together, then mermaid flow, plantuml mindmap, nodes for an abstract mindmap, markmap mindmap and mermaid mindmap. The mermaid diagram appears in several forms because the point is that the same source list can be rendered as a flowchart or as one of three different mindmap styles, and the choice is the user's.

The older processor list in the README shows the same thing with the names you would search for: list2table, also called 2datatable, list2listtable, list2mermaid with a graph LR example, list2mindmap with a mermaid v9.3.0 mindmap example, list2tab, list2timeline, and title2list combined with list2something.

The naming convention is worth noting. The `list2` prefix tells you the source construct and the target, which makes the catalogue searchable in a way that a list of visual results is not. The newer names in the gallery, multiWay table and Dir Tree, are less mechanical and read as features rather than transforms.

The documentation for the full list is pointed at from the gallery itself, and the README notes that more functions are in the detailed documentation.

Where to try it, and what the docs look like

The project points at several ways to see it work, and they are not equally useful.

The tutorial is a separate site with a tabbed interface, and the README describes it as the place to learn how to use it by switching between tabs. The wiki is the general documentation home. The online interaction demo is a live editor where you can write examples and learn usage through templates, and there is a second online interaction site for the Obsidian web build, with a note that because of the size limit of the free Cloudflare account, images are not supported there.

The install documentation is split by host, with separate pages for installing and using in Obsidian and for installing and using in Vuepress and Markdown-it. That split is the practical entry point for most people, and the fact that there are two pages rather than one is a small hint at how different the two installations are.

The README also documents two workarounds that are worth knowing before you hit them. When the website link to an article fails, try replacing `linczero.github.io` with `linczero-github-io.pages.dev` in the url, which is the usual way to reach a Pages site when the primary domain is having trouble. And the alternate link for the detailed documentation points at a different path than the wiki, so the two are not the same document set.

There is a companion project the README recommends using alongside it, AnyMenu, developed by the author of AnyBlock, which is described as reducing the learning cost and quickly generating templates. It is a separate repository, and the reasoning behind the pairing is straightforward: AnyBlock does the rendering, AnyMenu does the editing surface for producing the input that rendering expects, and a visual editor is what makes a syntax free design usable in practice.

Editorial conclusion

Adopt AnyBlock if you publish the same documents across Obsidian, a Vuepress or Quartz site and a CodeMirror editor, because a single block implementation with per-host builds is what the project is built for. Do not adopt it if you want a new Markdown syntax to learn, because the design principle is syntax free with no new syntax, and check first that the processors you need exist, because the catalogue of transforms is large but the documentation is spread across a wiki, a tutorial site and an online demo rather than one reference page.

Frequently asked questions

Official sources

1. any-block/any-block on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases