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.
| Node | Feature | Attributes |
|---|---|---|
doc | core | none. The top node. |
text | core | none. Holds the string and the marks. |
paragraph | core | textAlign |
hardBreak | core | none |
heading | heading | level, textAlign |
blockquote | blockquote | none |
horizontalRule | horizontalRule | none |
bulletList, listItem | bulletList (listItem also for orderedList) | none |
orderedList | orderedList | start, type |
taskList | taskList | none |
taskItem | taskList | checked. Items can nest. |
codeBlock | codeBlock | language |
table, tableRow | table | none |
tableHeader, tableCell | table | colspan, rowspan, colwidth |
mention | mention or hashtag | id, label, mentionSuggestionChar |
What the sanitizer does with each attribute:
textAlign: one ofleft,center,right,justify, otherwisenull(the default start alignment). Only onparagraphandheading, and only whentextAlignis 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 of1,a,A,i,I, otherwisenull.checked:trueonly fortrueor the string"true".language: lower-cased, must match^[a-z0-9+#-]{1,20}$, otherwisenull. 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, otherwisenull.mention:idandlabelare trimmed and cut to 200 characters.labelfalls back toid. A mention without anidis dropped.mentionSuggestionCharis#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
| Mark | Feature | Attributes |
|---|---|---|
bold | bold | none |
italic | italic | none |
underline | underline | none |
strike | strike | none |
code | code | none |
subscript | subscript | none |
superscript | superscript | none |
link | link | href, target, rel |
textStyle | color | color |
highlight | highlight | color |
link:hrefmust passsafeHref: http, https, mailto, tel and relative URLs only, also when the scheme hides behind whitespace, entities or percent-encoding. A link with an unsafehrefis dropped and its text stays.targetis_blankornull.relkeeps only known tokens (noopener,noreferrer,nofollow,ugc,sponsored,external). Withtarget="_blank",noopeneris always there, and an emptyrelbecomesnoopener noreferrer nofollow.textStyle: carries a palette colour by name. A value that is not a palette name drops the mark.highlight: a palette colour, ornullfor 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.
| Node | Feature | Attributes |
|---|---|---|
image | image | id, the MediaSource fields, caption, align |
gallery | gallery | id, layout, photos, caption |
file | file | id, 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:andblob:sources never survive. The staged-upload markerhttps://staged.post-canvas.invalid/<key>, which the editor uses for a pasted picture on its way to upload, is transient too:sanitizeDocumentdrops it,validateDocumentrefuses it, andhasPendingUploads(json)andhasTransientContent(json)report it, so a document with one is not ready to save.width,height: whole pixels up to 100,000, or0.0means unknown.renderHTMLleaves them out when they are0, 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 a640wor2xstyle descriptor. Bad entries are dropped, at most 12 are kept, and the field isnullwhen none is left.placeholder: a base64data:image/jpeg,pngorwebpURL of about 2 KB at most, otherwisenull.uploadId: a plain token (letters, digits and. : @ / + = -, up to 200 characters), otherwisenull.uploadKey: always cleared. It marks an upload that is running or failed, and is never saved.align(image): one ofcenter,wide,full,left,right. Anything else becomescenter.
Rules for a gallery:
- At most
maxPhotosphotos (from thegalleryfeature, 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 thegalleryfeature allows (carousel,grid,masonry,collage). Anything else becomes the first allowed layout.place(collage only): the first photo is the base and hasplace: null. Every other photo has{ x, y, w, r }: centrexandyfrom 0 to 1 of the base, widthwfrom 0.08 to 1 of the base, rotationrfrom -180 to 180 degrees rounded to 0.1. In any other layout everyplaceisnull.
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 tofile.size: a whole number of bytes, ornull.mimeType: a lower-casedtype/subtype, otherwisenull.
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.
| Node | Feature | Attributes |
|---|---|---|
video | video | id, provider, videoId, hash, vertical, start, title, description, thumbnailUrl |
embed | embed | id, provider, ref, url, title, aspectRatio |
linkCard | linkCard | id, url, title, description, image, siteName, favicon |
embedInput | video, embed or linkCard | id, value, status, error, kind |
Rules for video:
providerisyoutubeorvimeo. ThevideoIdmust pass the provider's pattern and round-trip through its canonical URL, otherwise the node is dropped.hashis the privacy hash of an unlisted Vimeo video and is kept only for Vimeo.verticalis kept only for YouTube (a Short).startis a whole number of seconds from 1 to 43,200 (twelve hours), otherwisenull. A vertical video never keeps a start time.titleis one line up to 200 characters.descriptionis up to 1,000 characters.thumbnailUrlmust be an image on YouTube's or Vimeo's own image host, over https, otherwisenull.
Rules for embed:
providermust be registered and in theembedfeature'sproviderslist, otherwise the node is dropped.refis a flat record of at most 8 short strings. It must round-trip through the provider's canonical URL.urlis replaced by that rebuilt canonical URL.titleis one line up to 200 characters.aspectRatiois a number from 0.2 to 5, otherwise the provider's default.
Rules for linkCard:
urlmust be a safe absolute http or https URL, otherwise the node is dropped.titleis up to 200 characters and falls back to the host name.descriptionis up to 500.siteNameis up to 100.imageandfaviconmust be absolute http or https URLs, otherwisenull.
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.