Skip to content

Examples

These progressive examples show how PCF documents are structured, from the simplest possible document to a complete document with an entity overlay.

Simple Paragraph

The simplest valid PCF document — one block, one span, no marks.

[
  {
    "_type": "block",
    "_key": "b1",
    "style": "normal",
    "markDefs": [],
    "children": [
      {
        "_type": "span",
        "_key": "s1",
        "text": "Hello, world.",
        "marks": []
      }
    ]
  }
]

Renders as: Hello, world.

Formatted Text with Marks

Multiple decorators on spans produce bold, italic, underline, inline code, and other formatting.

[
  {
    "_type": "block",
    "_key": "b1",
    "style": "normal",
    "markDefs": [],
    "children": [
      {
        "_type": "span",
        "_key": "s1",
        "text": "This is ",
        "marks": []
      },
      {
        "_type": "span",
        "_key": "s2",
        "text": "bold and italic",
        "marks": ["strong", "em"]
      },
      {
        "_type": "span",
        "_key": "s3",
        "text": ", and this is ",
        "marks": []
      },
      {
        "_type": "span",
        "_key": "s4",
        "text": "inline code",
        "marks": ["code"]
      },
      {
        "_type": "span",
        "_key": "s5",
        "text": ".",
        "marks": []
      }
    ]
  }
]

Renders as: This is bold and italic, and this is inline code.

Annotations are defined in markDefs and referenced by key in span marks arrays.

[
  {
    "_type": "block",
    "_key": "b1",
    "style": "normal",
    "markDefs": [
      {
        "_type": "link",
        "_key": "lnk1",
        "href": "https://www.packtpub.com"
      }
    ],
    "children": [
      {
        "_type": "span",
        "_key": "s1",
        "text": "Visit ",
        "marks": []
      },
      {
        "_type": "span",
        "_key": "s2",
        "text": "Packt Publishing",
        "marks": ["strong", "lnk1"]
      },
      {
        "_type": "span",
        "_key": "s3",
        "text": " for more.",
        "marks": []
      }
    ]
  }
]

The span "Packt Publishing" carries both the strong decorator (bold) and a reference to the lnk1 link annotation.

List Items

Lists are represented as consecutive blocks with listItem and level properties. There is no wrapper element.

[
  {
    "_type": "block",
    "_key": "li1",
    "style": "normal",
    "listItem": "number",
    "level": 1,
    "markDefs": [],
    "children": [
      {
        "_type": "span",
        "_key": "s1",
        "text": "Simple.",
        "marks": []
      }
    ]
  },
  {
    "_type": "block",
    "_key": "li2",
    "style": "normal",
    "listItem": "number",
    "level": 1,
    "markDefs": [],
    "children": [
      {
        "_type": "span",
        "_key": "s2",
        "text": "Easy to use.",
        "marks": []
      }
    ]
  },
  {
    "_type": "block",
    "_key": "li3",
    "style": "normal",
    "listItem": "bullet",
    "level": 2,
    "markDefs": [],
    "children": [
      {
        "_type": "span",
        "_key": "s3",
        "text": "A nested bullet point.",
        "marks": []
      }
    ]
  }
]

Code Block

Custom block types like codeBlock sit at the same level as text blocks in the root array.

[
  {
    "_type": "block",
    "_key": "b1",
    "style": "normal",
    "markDefs": [],
    "children": [
      {
        "_type": "span",
        "_key": "s1",
        "text": "Here is a simple Go HTTP server:",
        "marks": []
      }
    ]
  },
  {
    "_type": "codeBlock",
    "_key": "b2",
    "language": "go",
    "filename": "main.go",
    "code": "package main\n\nimport \"net/http\"\n\nfunc main() {\n\thttp.HandleFunc(\"/\", func(w http.ResponseWriter, r *http.Request) {\n\t\tw.Write([]byte(\"hello\"))\n\t})\n\thttp.ListenAndServe(\":3000\", nil)\n}"
  }
]

Image Block

Images are stored as image blocks with responsive sizes, alt text, and optional captions.

[
  {
    "_type": "image",
    "_key": "img1",
    "alt": "Kubernetes cluster architecture diagram",
    "caption": [
      {
        "_type": "span",
        "_key": "cs1",
        "text": "Figure 1: Kubernetes cluster architecture",
        "marks": []
      }
    ],
    "asset": {
      "url": "https://cdn.packt.com/images/k8s-arch.png",
      "width": 1200,
      "height": 800,
      "mimeType": "image/png"
    }
  }
]

Entity Overlay

Entities live in a separate overlay document alongside the PCF content. Here is a PCF document paired with its overlay.

The Content

[
  {
    "_type": "block",
    "_key": "b1",
    "style": "h1",
    "markDefs": [],
    "children": [
      {
        "_type": "span",
        "_key": "s1",
        "text": "Building APIs with Go and Chi",
        "marks": []
      }
    ]
  },
  {
    "_type": "block",
    "_key": "b2",
    "style": "normal",
    "markDefs": [
      {
        "_type": "link",
        "_key": "lnk1",
        "href": "https://github.com/go-chi/chi"
      }
    ],
    "children": [
      {
        "_type": "span",
        "_key": "s2",
        "text": "Go is a popular language for building web services. The ",
        "marks": []
      },
      {
        "_type": "span",
        "_key": "s3",
        "text": "Chi router",
        "marks": ["lnk1"]
      },
      {
        "_type": "span",
        "_key": "s4",
        "text": " provides a lightweight HTTP router.",
        "marks": []
      }
    ]
  }
]

The Overlay

{
  "$schema": "https://schema.packt.com/pcf/entity-overlay/v0.1.0",
  "contentRef": "contentlake://packt/a3d9e712-4f6b-48c1-b5a0-91c7d2e8f304",
  "version": "2026-03-23T10:30:00Z",
  "entities": [
    {
      "_type": "language",
      "_id": "ent-lang-go",
      "name": "Go",
      "confidence": 0.96,
      "salience": 0.85,
      "mentions": [
        {
          "blockKey": "b1",
          "startChar": 20,
          "endChar": 22,
          "text": "Go"
        },
        {
          "blockKey": "b2",
          "startChar": 0,
          "endChar": 2,
          "text": "Go"
        }
      ],
      "metadata": {
        "about": "An open-source programming language",
        "website": "https://go.dev"
      }
    },
    {
      "_type": "github",
      "_id": "ent-gh-chi",
      "name": "chi",
      "confidence": 0.94,
      "salience": 0.70,
      "mentions": [
        {
          "blockKey": "b2",
          "startChar": 55,
          "endChar": 65,
          "text": "Chi router"
        }
      ],
      "metadata": {
        "href": "https://github.com/go-chi/chi",
        "about": "Lightweight HTTP router for Go",
        "license": "MIT",
        "stats": {
          "stars": 18900,
          "contributors": 120
        }
      }
    }
  ]
}

The overlay uses block keys and character offsets to locate entity mentions within the content, keeping entities completely separate from the content structure. See Entities for the full overlay specification.