Skip to Content
Post Canvas
Reference

Nodes and marks

Every node and mark in a Post Canvas document, with its attributes, its feature flag and what the sanitizer clamps or drops.

A Post Canvas document is Tiptap JSON: a doc node holding block nodes, which hold text nodes with marks. This page lists every node and mark, the attributes each one stores, and the rule the sanitizer applies to each attribute. sanitizeDocument() runs these rules, and so do renderToHTML, PostCanvasView, fromHTML, fromMarkdown and the paste handler. See Render and Server.

A node or mark exists only when its feature is on (see Features). The sanitizer removes nodes of a feature that is off. A node or mark the schema does not know is removed too, and the text of an unknown inline wrapper stays.

Node types are camelCase names such as codeBlock and linkCard. Ids (id) are added by the editor to image, gallery, file, video, embed and linkCard (the list is idNodeTypes from post-canvas/extensions). A valid id matches letters, digits, _ and -, at most 64 characters. Anything else becomes null and the editor assigns a new one.

Text nodes

In the Feature column, core means the node is always in the schema.

NodeFeatureAttributes
doccorenone. The top node.
textcorenone. Holds the string and the marks.
paragraphcoretextAlign
hardBreakcorenone
headingheadinglevel, textAlign
blockquoteblockquotenone
horizontalRulehorizontalRulenone
bulletList, listItembulletList (listItem also for orderedList)none
orderedListorderedListstart, type
taskListtaskListnone
taskItemtaskListchecked. Items can nest.
codeBlockcodeBlocklanguage
table, tableRowtablenone
tableHeader, tableCelltablecolspan, rowspan, colwidth
mentionmention or hashtagid, label, mentionSuggestionChar

What the sanitizer does with each attribute:

  • textAlign: one of left, center, right, justify, otherwise null (the default start alignment). Only on paragraph and heading, and only when textAlign is on.
  • level: rounded and clamped to 1 to 4. A bad value becomes 2, so the text survives.
  • start (ordered list): a whole number from 0 to 1,000,000. Default 1.
  • type (ordered list): one of 1, a, A, i, I, otherwise null.
  • checked: true only for true or the string "true".
  • language: lower-cased, must match ^[a-z0-9+#-]{1,20}$, otherwise null. The code block menu offers 20 languages in the npm package and 8 in the CDN build. Highlighting loads the grammars on first use.
  • colspan, rowspan: whole numbers from 1 to 100.
  • colwidth: a list of positive numbers up to 4000, one per column of the span, otherwise null.
  • mention: id and label are trimmed and cut to 200 characters. label falls back to id. A mention without an id is dropped. mentionSuggestionChar is # for a hashtag and @ for everything else.

A document holds at most 20 mentions and hashtags together (maxMentions). The editor stops turning typed @ and # text into mentions at that count, and a document over it reports a limit.mentions problem.

Marks

MarkFeatureAttributes
boldboldnone
italicitalicnone
underlineunderlinenone
strikestrikenone
codecodenone
subscriptsubscriptnone
superscriptsuperscriptnone
linklinkhref, target, rel
textStylecolorcolor
highlighthighlightcolor
  • link: href must pass safeHref: http, https, mailto, tel and relative URLs only, also when the scheme hides behind whitespace, entities or percent-encoding. A link with an unsafe href is dropped and its text stays. target is _blank or null. rel keeps only known tokens (noopener, noreferrer, nofollow, ugc, sponsored, external). With target="_blank", noopener is always there, and an empty rel becomes noopener noreferrer nofollow.
  • textStyle: carries a palette colour by name. A value that is not a palette name drops the mark.
  • highlight: a palette colour, or null for the default highlight.

Palette colours

Text colour and highlight store a name, never hex, so themes and dark mode recolour them and nothing unsafe reaches a style attribute. The names are, in menu order:

gray, brown, orange, yellow, green, blue, purple, pink, red

paletteColors (from post-canvas) is this list as a readonly PaletteColor[]. Hex values and CSS never survive a sanitize.

Media nodes

Media nodes are atoms: they have no editable content, only attributes. Every picture shares the attributes of MediaSource.

NodeFeatureAttributes
imageimageid, the MediaSource fields, caption, align
gallerygalleryid, layout, photos, caption
filefileid, src, name, size, mimeType, uploadId, uploadKey

The MediaSource fields are src, width, height, alt, srcset, placeholder, uploadId and uploadKey. A gallery photo has them plus a key and a place. The field-by-field types are on the types page.

Rules for a picture (image and every gallery photo):

  • src: an absolute http or https URL. Without one the node (or photo) is dropped. javascript:, data: and blob: sources never survive. The staged-upload marker https://staged.post-canvas.invalid/<key>, which the editor uses for a pasted picture on its way to upload, is transient too: sanitizeDocument drops it, validateDocument refuses it, and hasPendingUploads(json) and hasTransientContent(json) report it, so a document with one is not ready to save.
  • width, height: whole pixels up to 100,000, or 0. 0 means unknown. renderHTML leaves them out when they are 0, and the editor measures the picture on load, outside the undo history.
  • alt: one line, up to 500 characters. Empty for decorative pictures.
  • caption: up to 1,000 characters, line breaks kept.
  • srcset: each entry is an absolute http or https URL with a 640w or 2x style descriptor. Bad entries are dropped, at most 12 are kept, and the field is null when none is left.
  • placeholder: a base64 data:image/jpeg, png or webp URL of about 2 KB at most, otherwise null.
  • uploadId: a plain token (letters, digits and . : @ / + = -, up to 200 characters), otherwise null.
  • uploadKey: always cleared. It marks an upload that is running or failed, and is never saved.
  • align (image): one of center, wide, full, left, right. Anything else becomes center.

Rules for a gallery:

  • At most maxPhotos photos (from the gallery feature, default 10, never more than 50). Extra photos and photos without a valid source are dropped. A gallery with no usable photo is dropped.
  • key: unique per gallery, letters, digits, _ and -, up to 40 characters. A bad or repeated key gets a new one.
  • layout: one of the layouts the gallery feature allows (carousel, grid, masonry, collage). Anything else becomes the first allowed layout.
  • place (collage only): the first photo is the base and has place: null. Every other photo has { x, y, w, r }: centre x and y from 0 to 1 of the base, width w from 0.08 to 1 of the base, rotation r from -180 to 180 degrees rounded to 0.1. In any other layout every place is null.

Rules for a file:

  • src: an absolute http or https URL, otherwise the node is dropped.
  • name: one line, up to 255 characters. It falls back to the last part of the URL, then to file.
  • size: a whole number of bytes, or null.
  • mimeType: a lower-cased type/subtype, otherwise null.

Embeds

Videos and embeds never store a player URL. The sanitizer and the renderers rebuild every iframe URL from the provider and the validated ids, so a tampered document cannot smuggle in a player.

NodeFeatureAttributes
videovideoid, provider, videoId, hash, vertical, start, title, description, thumbnailUrl
embedembedid, provider, ref, url, title, aspectRatio
linkCardlinkCardid, url, title, description, image, siteName, favicon
embedInputvideo, embed or linkCardid, value, status, error, kind

Rules for video:

  • provider is youtube or vimeo. The videoId must pass the provider's pattern and round-trip through its canonical URL, otherwise the node is dropped.
  • hash is the privacy hash of an unlisted Vimeo video and is kept only for Vimeo. vertical is kept only for YouTube (a Short).
  • start is a whole number of seconds from 1 to 43,200 (twelve hours), otherwise null. A vertical video never keeps a start time.
  • title is one line up to 200 characters. description is up to 1,000 characters.
  • thumbnailUrl must be an image on YouTube's or Vimeo's own image host, over https, otherwise null.

Rules for embed:

  • provider must be registered and in the embed feature's providers list, otherwise the node is dropped.
  • ref is a flat record of at most 8 short strings. It must round-trip through the provider's canonical URL. url is replaced by that rebuilt canonical URL.
  • title is one line up to 200 characters. aspectRatio is a number from 0.2 to 5, otherwise the provider's default.

Rules for linkCard:

  • url must be a safe absolute http or https URL, otherwise the node is dropped.
  • title is up to 200 characters and falls back to the host name. description is up to 500. siteName is up to 100.
  • image and favicon must be absolute http or https URLs, otherwise null.

embedInput is the transient "paste a link" field. It is never part of a saved document: nothing parses into it, it renders to hidden markup, and the sanitizer always drops it. hasTransientContent(json) reports one that is open. Its kind is an EmbedInputKind and its status is idle, loading or error.

Where the rules live

Each rule above is a postCanvasSanitize function on the node or mark. You can call the text ones (sanitizeLink, sanitizeHeading and the rest) and the media ones (sanitizeImageAttrs, sanitizeGalleryAttrs, sanitizeFileAttrs) from post-canvas/extensions. They are listed on the extensions page.

On this page