@ewanc26/bismuth

@ewanc26/bismuth converts richtext-block documents from the Standard.site platform ecosystem to Markdown. It supports all three publishing platforms — Leaflet (pub.leaflet.), Pckt (blog.pckt.), and Offprint (app.offprint.) — and ships as both a CLI tool and a TypeScript library.

Part of the @ewanc26/pkgs monorepo.

Why Bismuth?

Standard.site stores longform content as site.standard.document ATProto records, with the actual body represented as a block tree from one of the platform's three editors. Each editor uses its own lexicon namespace (pub.leaflet., blog.pckt., app.offprint.), but they share the same core shape: typed blocks (paragraphs, headings, code, lists, embeds) with byte-slice facet annotations for inline formatting. This is a great format for a federated document store, but it's opaque to anything outside the Standard.site ecosystem.

The gap bismuth fills: if you want to take a document from any Standard.site platform and use it somewhere else — feed it into a static site generator, archive it, diff it, or just read it in a terminal — you need something that understands the block tree and can produce plain text. Markdown is the obvious target because it preserves the document's semantic structure (headings, lists, code blocks, emphasis) without requiring a custom renderer.

The alternative is hand-rolling the same conversion every time it's needed, which is what prompted bismuth's existence. The conversion logic for facet byte-slice annotations in particular — which must be applied in reverse order to avoid index drift — is fiddly enough to be worth extracting once into a tested library.

Why Bismuth as a name?

Bismuth the element is known for its iridescent oxide surface — a single underlying structure that refracts into many colours depending on how you look at it. A pub.leaflet document is the same thing: one block tree that can be rendered as a rich web UI, a terminal reader, a static site, or plain Markdown depending on what's doing the rendering. The name also fits the monorepo's loose theme of naming packages after elements and minerals (see @ewanc26/malachite).

Install

Ships as both ESM and CJS with full TypeScript type definitions.

CLI

The input JSON can be any of:

• site.standard.document
• pub.leaflet.content
• blog.pckt.content
• app.offprint.content

Library

documentToMarkdown(doc, opts?)

Converts a site.standard.document to Markdown. When opts.frontmatter is true, a YAML front matter block is prepended containing title, publishedAt, description, tags, and path.

contentToMarkdown(content, opts?)

Converts a pub.leaflet.content to Markdown. Multi-page documents are joined with opts.pageBreak (default \n\n---\n\n). Canvas pages emit an HTML comment since their spatial layout cannot be represented linearly.

pcktContentToMarkdown(content, sourceDid?, opts?)

Async. Converts a blog.pckt.content to Markdown. Pckt content can be either inline (items array) or extended (a blob reference); extended mode requires sourceDid for blob resolution and will throw if it is absent. An optional opts.blobResolver can override the default PDS resolver.

offprintContentToMarkdown(content, opts?)

Converts an app.offprint.content to Markdown.

blockToMarkdown(block)

Converts a single AnyBlock — from any of the three platforms — to a { markdown, footnotes } result.

applyFacets(plaintext, facets?)

Applies richtext facet byte-slice annotations to a plaintext string, returning annotated Markdown. Supports facets from all three platform namespaces (pub.leaflet.richtext.facet, blog.pckt.richtext.facet, app.offprint.richtext.facet).

resolvePcktContent(content, sourceDid, resolver?)

Async. Resolves a blog.pckt.content to a flat block array, handling both inline and blob modes. Exported for cases where you want the blocks without immediately converting them.

createPdsBlobResolver(pdsEndpoint?)

Returns a BlobResolver that fetches blobs from a PDS via com.atproto.sync.getBlob. Defaults to https://bsky.network.

Options

Block support

All block types from all three platforms are supported via a unified dispatcher.

Leaflet (pub.leaflet.)

Pckt (blog.pckt.)

Offprint (app.offprint.)

Facet support

Facets from all three platform namespaces are normalised to a shared internal representation before being applied. The byteStart/byteEnd byte offsets are handled correctly for multi-byte UTF-8 characters.

Licence

AGPL-3.0-only — see the pkgs monorepo.