Content Format

Articles are composed of content blocks. Each block has a type field that determines its structure and how it should be rendered.

Block Types

Type	Description
`paragraph`	Text paragraph with inline formatting
`heading`	Section heading (levels 1-6)
`code`	Code block with optional language
`list`	Bullet, numbered, or task list
`divider`	Horizontal divider line

Inline Content

Paragraph and heading blocks contain an array of inline content nodes:

type TextNode = {
  type: "text";
  text: string;
  marks?: ("bold" | "italic" | "code" | "underline" | "strike")[];
  link?: { href: string };
};

Marks

Text can have multiple formatting marks applied:

Mark	Description
`bold`	Bold text
`italic`	Italic text
`code`	Inline code
`underline`	Underlined text
`strike`	Strikethrough text

Links

Links are represented with a link object containing the href:

{
  "type": "text",
  "text": "Click here",
  "link": { "href": "https://example.com" }
}

Block Examples

Paragraph

{
  "type": "paragraph",
  "content": [
    { "type": "text", "text": "This is a " },
    { "type": "text", "text": "bold", "marks": ["bold"] },
    { "type": "text", "text": " paragraph with a " },
    { "type": "text", "text": "link", "link": { "href": "https://example.com" } },
    { "type": "text", "text": "." }
  ]
}

Heading

{
  "type": "heading",
  "level": 2,
  "content": [
    { "type": "text", "text": "Section Title" }
  ]
}

The level field can be 1-6, corresponding to HTML <h1> through <h6>.

Code Block

{
  "type": "code",
  "language": "typescript",
  "code": "function hello() {\n  console.log('Hello!');\n}"
}

The language field is optional and may be omitted for plain code blocks.

List

{
  "type": "list",
  "style": "bullet",
  "items": [
    {
      "content": [{ "type": "text", "text": "First item" }]
    },
    {
      "content": [{ "type": "text", "text": "Second item" }]
    }
  ]
}

List styles:

bullet - Unordered list
ordered - Numbered list
task - Task list with checkboxes

Task list items include a checked field:

{
  "type": "list",
  "style": "task",
  "items": [
    {
      "content": [{ "type": "text", "text": "Done task" }],
      "checked": true
    },
    {
      "content": [{ "type": "text", "text": "Pending task" }],
      "checked": false
    }
  ]
}

Divider

{
  "type": "divider"
}

TypeScript Types

Here are the complete TypeScript types for reference:

type InlineMark = "bold" | "italic" | "code" | "underline" | "strike";

type TextNode = {
  type: "text";
  text: string;
  marks?: InlineMark[];
  link?: { href: string };
};

type InlineContent = TextNode[];

type ParagraphBlock = {
  type: "paragraph";
  content: InlineContent;
};

type HeadingBlock = {
  type: "heading";
  level: 1 | 2 | 3 | 4 | 5 | 6;
  content: InlineContent;
};

type CodeBlock = {
  type: "code";
  language?: string;
  code: string;
};

type ListItem = {
  content: InlineContent;
  checked?: boolean;
};

type ListBlock = {
  type: "list";
  style: "bullet" | "ordered" | "task";
  items: ListItem[];
};

type DividerBlock = {
  type: "divider";
};

type ParableBlock =
  | ParagraphBlock
  | HeadingBlock
  | CodeBlock
  | ListBlock
  | DividerBlock;

Future Block Types

The following block types may be added in the future:

Type	Description
`image`	Embedded image with caption
`youtube`	YouTube video embed

These will be documented when they become available.

Content Format

On this page