Jul 20262 min read

Every block in the portability contract

This file exists so the renderer, the list page and the validator have something real to work against before the first Notion export arrives. It uses every block the contract allows and nothing it doesn't, so if this file ever fails validation, the validator has regressed.

Delete this directory once you have imported a real post.

What the contract allows

Paragraphs, two heading levels, single-level lists, quotes, dividers, images, code blocks, links, bold, italic and inline code. That set is the intersection of what survives a paste into dev.to, Hashnode, Medium, X and LinkedIn.

Text styles

Only italic, bold and inlineCode travel intact. Everything else — the underline, the coloured text, the highlight — either vanishes or arrives as raw HTML, which the allowlist rejects.

A full https link is fine. Relative links and Notion-internal links are not: they break the moment the post leaves this site.

This line ends with a hard break,
and this is the line after it — still one paragraph.

Lists, one level only

Nesting collapses or re-indents unpredictably when pasted
So a bullet is a bullet, and that's the whole vocabulary
If a point needs sub-points, it needs a heading

Numbered lists follow the same rule
One level
No exceptions

Use a quote wherever you would reach for a Notion callout. Callouts export as raw HTML, and raw HTML is not in the contract.

Images and code

Images are uploaded to ImageKit at import and referenced by absolute URL, so they stay hotlinkable when the post is cross-posted. Their dimensions live in frontmatter, which is what keeps the layout from shifting.

Code blocks are highlighted at build time, and the copy button emits the raw source — print(), not the fenced block — because X's article editor renders neither.

def chunk(text: str, size: int = 512) -> list[str]:
    words = text.split()
    return [
        " ".join(words[i : i + size])
        for i in range(0, len(words), size)
    ]

Reading time excludes the block above. Counting a sixty-line snippet as three hundred words turns an honest four-minute post into "12 min read".

What the contract allows

Text styles

Only italic, bold and inlineCode travel intact. Everything else — the underline, the coloured text, the highlight — either vanishes or arrives as raw HTML, which the allowlist rejects.

A full https link is fine. Relative links and Notion-internal links are not: they break the moment the post leaves this site.

This line ends with a hard break,
and this is the line after it — still one paragraph.

Lists, one level only

Nesting collapses or re-indents unpredictably when pasted

So a bullet is a bullet, and that's the whole vocabulary

If a point needs sub-points, it needs a heading

Numbered lists follow the same rule

One level

No exceptions

Use a quote wherever you would reach for a Notion callout. Callouts export as raw HTML, and raw HTML is not in the contract.

Images and code

Code blocks are highlighted at build time, and the copy button emits the raw source — print(), not the fenced block — because X's article editor renders neither.

def chunk(text: str, size: int = 512) -> list[str]:
    words = text.split()
    return [
        " ".join(words[i : i + size])
        for i in range(0, len(words), size)
    ]

Reading time excludes the block above. Counting a sixty-line snippet as three hundred words turns an honest four-minute post into "12 min read".