---
title: One Document, the Same Meaning Everywhere
language: en
---

## What I wanted to know

![Publisle wordmark with the tagline Portable semantic articles, compiled to static HTML, and the address publisle.xyz](/media/bf4d929f-deeb-475a-bc35-d7bc11082adf.png "The official Publisle project card from publisle.xyz.")

When I was developing my website for blogging, I wanted a standard schematic system for blogging with version control, and to be able to represent the full blog as pure MD with support for customized elements for interactivity. I also wanted a compiled result for lightweight browsing without much client overhead, and to be able to create a searchable database for content on the website.

I struggled to find a solution that solves all the points needed, so I said why not make my own solution to be focused around providing a standard for portability between frameworks and browser-based compilation, with an addon to compile an article as a research paper, with support for bibliography and standard research paper format templates out of the box.

The same document keeps its meaning when you read it as static HTML with no JavaScript, as print or PDF, as Markdown, or as text for an LLM, and when a framework host makes the interactive islands live. Authored fallbacks keep the same semantics when interactivity is not available.

This post looks at a simple compile workflow, and at the first adoption on voidreg.xyz. The [Publisle project page](https://www.voidreg.xyz/projects/publisle) covers the schema, compiler, adapters, and addon split in more detail.

## How the stack is split

The main decision is to keep a portable document model at the center, and compile out from that model instead of tying the article to one framework or one export format. That ensures portability without enforcing strict framework limits that can be expanded later easily.

As per the design decision for flexibility of design, most of the library infrastructure is built as addons over the core library package for decoupled development, with a prime example being `@publisle/cli-research`. The same document can pick up bibliography support, BibTeX and CSL, and export to LaTeX, PDF, and JATS, including standard research paper format templates. Core itself does not pull in TeX, citeproc, or those templates.

```mermaid
flowchart LR
  subgraph core ["Core"]
    direction TB
    schema["@publisle/schema"]
    corepkg["@publisle/core"]
    markdown["@publisle/markdown"]
    compiler["@publisle/adapter-core"]
    schema --> corepkg
    markdown --> corepkg
    corepkg --> compiler
  end
  subgraph layer ["CLI, adapters, and addons"]
    direction TB
    cli["@publisle/cli"]
    hosts["Svelte, React, Next.js,<br/>Astro, and Vue adapters"]
    addon["Addon: @publisle/cli-research"]
  end
  subgraph out ["Outputs"]
    direction TB
    html["Static HTML"]
    journal["LaTeX, PDF, and JATS"]
  end
  compiler --> cli
  compiler --> hosts
  core --> addon
  cli --> html
  hosts --> html
  addon --> journal
```

The Core packages sit in the middle, the CLI and framework adapters compile to static HTML, and `@publisle/cli-research` is an addon for research export.

Schema, markdown, and core feed adapter-core in the Core group. From there the CLI and the Svelte, React, Next.js, Astro, and Vue adapters compile to static HTML, and @publisle/cli-research, built over Core, exports LaTeX, PDF, and JATS.

## One document, step by step

A concrete workflow is the Core quickstart. You write the article in Markdown, publisle validation cli command, then build the article to produce static output and open HTML output index for preview.

Here is a short article.md.

````md article.md
---
title: A portable article
language: en
---
The transform in Equation :ref[eq\:signal] turns samples into a spectrum :cite[shannon1949].
:::equation{label="eq:signal"}
$$
X_k=\sum_{n=0}^{N-1} x_n e^{-2\pi i kn/N}
$$
:::
::::figure{src="/fft-spectrum.svg" variant-dark="/fft-spectrum-dark.svg" label="fig:spectrum" alt="Eight frequency bins with magnitude four at bins two and six"}
:::caption
A signal becomes two clear peaks.
:::
::::
::::diagram{engine="mermaid" label="diagram:flow" alt="Samples go through the DFT to a spectrum."}
```mermaid
flowchart LR A[Samples] --> B[DFT] --> C[Spectrum]
```
:::fallback
Samples go through the DFT to a spectrum.
:::
::::
::::interactive{type="publisle:interactive-schematic" schemaVersion="2" activation="interaction" label="Interactive clocked counter"}
:::title
Clocked counter
:::
:::description
Observe the output on each clock edge.
:::
:::instructions
Press Clock to advance the count and Reset to return it to zero.
:::
:::fallback
The counter starts at zero.
:::
```publisle-payload
{ "source": "./counter.json" }
```
::::
:::bibliography
```json
[{"id":"shannon1949","type":"article-journal","authors":["Shannon, Claude E."],"title":"Communication in the Presence of Noise","issued":"1949","containerTitle":"Proceedings of the IRE","volume":"37","issue":"1","page":"10--21","doi":"10.1109/JRPROC.1949.232969"}]
```
:::
````

```sh
publisle validate article.md
publisle build article.md --out dist/
```

I wanted the compiled result to stay lightweight for the reader. The measured comparison in [Put the work in the build. Keep the reader lean.](https://publisle.xyz/#performance) uses the same math-heavy document through popular publishing tools, with reader delivery measured separately, and static hosts and default documentation themes identified.

| Tool                                                    | Math compilation · median              | Reader JS | Installed tools |
| :------------------------------------------------------ | :------------------------------------- | :-------- | :-------------- |
| Publisle&#xA;Minimal static HTML host, one article      | 11.29 ms&#xA;HTML · warm process       | 0 B       | 10.8 MiB        |
| MDX&#xA;Minimal static HTML host, one article           | 46.35 ms&#xA;HTML · warm process       | 0 B       | 13.8 MiB        |
| VitePress&#xA;Default documentation theme, one article  | 60.22 ms&#xA;HTML · warm process       | 56.8 KiB  | 144.2 MiB       |
| Docusaurus&#xA;Default documentation theme, one article | 42.94 ms&#xA;MDX module · warm process | 171.2 KiB | 163.3 MiB       |
| Pandoc&#xA;Minimal static HTML host, one article        | 24.66 ms&#xA;HTML · fresh process      | 0 B       | 157.8 MiB       |

MDX and Pandoc can also publish static HTML without reader JavaScript. Docusaurus compilation here produces a module; its default site theme and VitePress include navigation and framework code. JavaScript compilers are warm; Pandoc includes process startup. Prose and large-document results are in the [full report](https://publisle.xyz/docs/guides/performance-comparison/).

## What happens to interactive elements

On the web, a host runtime can make the islands interactive, and the authored fallbacks are already in the page if that runtime is not there. Print and PDF exports do not execute interactive behavior. Diagrams and embeds contribute their accessible text, and schematic islands contribute their authored fallback prose, with that reduction reported in the export diagnostics.

A research paper export can use the same source without pretending the interactive parts still run on paper.

## voidreg.xyz, the first adoption

I built voidreg.xyz as the first adoption of Publisle, an attempt to stress test the architecture and prove its value in a production environment.

The compiled documents are hosted on the site, and I use [the knowledge map](https://www.voidreg.xyz/map) as a searchable view of that set. Each module is a category and each chip is a project, I can filter by name, technology, or category, and choosing a chip lights the projects it relates to, the technologies it shares, and the posts that follow it.

For a static database that agents can read, [llms.txt](https://www.voidreg.xyz/llms.txt) is the site index, [llms-full.txt](https://www.voidreg.xyz/llms-full.txt) is the full text of the published site, and each project has its own index at `/llms/<project>.txt` and full text at `/llms/<project>-full.txt`. Every published post and project also has a clean Markdown version if I add `.md` to its address, or if the page is requested as `text/markdown`. Published posts and projects can also be searched and read over the MCP server at <https://www.voidreg.xyz/mcp>, with no token required for that published read.

## Try it out

If you want to try Publisle, go to [publisle.xyz](https://publisle.xyz/). There is a [playground](https://publisle.xyz/playground/) to edit Markdown and preview a compiled article, and [docs](https://publisle.xyz/docs/) for the standard and the integration guides. To compile locally, install the Core CLI with `npm install -g @publisle/cli`.

## References

* [Publisle project page](https://www.voidreg.xyz/projects/publisle): The project write-up, with the schema and compiler split and the current status.
* [publisle/publisle](https://github.com/publisle/publisle): Source repository for the Publisle document standard and tooling.
* [Publisle website](https://publisle.xyz/): Project site and documentation home.
* [Documentation](https://publisle.xyz/docs/): Guides, standards, and integration docs.
* [Playground](https://publisle.xyz/playground/): In-browser Markdown editor, article preview, and an interactive FFT example.
* [Put the work in the build. Keep the reader lean.](https://publisle.xyz/#performance): Measured compile time, reader JavaScript, and installed tool sizes compared with MDX, VitePress, Docusaurus, and Pandoc.
* [Measured publishing performance](https://publisle.xyz/docs/guides/performance-comparison/): Methodology and the full report, including prose and large-document results.
* [Knowledge map](https://www.voidreg.xyz/map): Searchable map of published projects and posts, filterable by name, technology, or category.
* [llms.txt](https://www.voidreg.xyz/llms.txt): Static site index for agents, with links to Markdown versions of published posts and projects.
* [llms-full.txt](https://www.voidreg.xyz/llms-full.txt): Full text of the published site in one document.
* [Connect an agent](https://www.voidreg.xyz/agents): How to connect over MCP, and the Markdown and llms.txt endpoints.
