PDF to Seed Document Import

Convert PDFs into Seed Hypermedia documents by reading the PDF, structuring the content, and publishing via the Seed CLI. Images are extracted, converted to IPFS, and published atomically alongside the document.

For CLI setup, key management, and environment configuration, see the seed-hypermedia-write skill.

Prerequisites

1. Seed CLI (@seed-hypermedia/cli on npm, binary: seed-cli) -- See the seed-hypermedia-write skill for detection, installation, updates, key management, and environment configuration.
2. For image extraction (optional) -- poppler-utils for pdfimages, or Python pypdfium2. See references/pdf-extraction.md.

Workflow

Step 1: Read the PDF

Preferred: Read the PDF directly using vision capabilities. Analyze each page to understand:

• Document structure (headings, sections, hierarchy)
• Text content with formatting (bold, italic, links, code)
• Images and figures (location, captions)
• Tables, lists, code blocks, math formulas
• Reading order and logical nesting
• Metadata: title, authors, publication date, abstract/summary

Fallback: For very large PDFs or when vision is unavailable, use extraction tools documented in references/pdf-extraction.md.

Step 2: Extract Images

If the PDF contains images/figures that should be preserved:

bash
1# Extract embedded images
2pdfimages -j document.pdf /tmp/pdf-images/img
3# Produces /tmp/pdf-images/img-000.jpg, img-001.jpg, etc.
4
5# Or render specific pages as images for figures
6pdftoppm -png -r 300 -f 3 -l 3 document.pdf /tmp/pdf-images/page

Or use Python:

python
1import pypdfium2 as pdfium
2pdf = pdfium.PdfDocument("document.pdf")
3# Render page 3 (0-indexed) at 2x resolution
4bitmap = pdf[2].render(scale=2.0)
5bitmap.to_pil().save("/tmp/pdf-images/figure1.png")

Step 3: Produce Content

You have two output format options:

Option A: Markdown with Frontmatter (Preferred)

Write a markdown file with YAML frontmatter containing all extracted metadata. This is the simplest approach:

markdown
1---
2name: 'Paper Title'
3summary: 'The paper abstract or a brief summary'
4displayAuthor: 'Jane Doe, John Smith'
5displayPublishTime: '2024-06-15'
6---
7
8# Introduction
9
10Paper content as markdown...
11
12## Methods
13
14![Figure 1: Experimental setup](/tmp/pdf-images/img-000.jpg)
15
16More content...

Then publish:

bash
1seed-cli document create -f extracted.md --key <keyname>

Option B: JSON Blocks (Precise Control)

For precise control over block structure, annotations, and non-standard block types, produce a JSON array of HMBlockNode objects. Use file:///absolute/path for image links -- the CLI converts them to IPFS automatically.

See references/seed-document-format.md for the complete block format reference and a comprehensive example covering all block types.

Key rules:

• Every block needs a unique id: 8 random characters from [A-Za-z0-9_-]
• Headings contain their content as children
• Lists are a container Paragraph with childrenType ("Ordered"/"Unordered") and child Paragraphs
• Annotations use byte-offset starts/ends arrays within the text field
• Images use "link": "file:///path/to/image.png" for local files
• Math blocks use LaTeX in the text field
• Code blocks use attributes.language for syntax highlighting

Then publish:

bash
1seed-cli document create -f blocks.json --name "Paper Title" --display-author "Jane Doe" --key <keyname>

Or pipe JSON via stdin:

bash
1cat blocks.json | seed-cli document create --name "Paper Title" --key <keyname>

Step 4: Publish and Verify

Publish using the Seed CLI (see seed-hypermedia-write skill for full reference):

bash
1# Create the document
2seed-cli document create -f content.md --key <keyname>
3
4# Or with explicit metadata overrides
5seed-cli document create -f content.md \
6  --name "Paper Title" \
7  --display-author "Jane Doe, John Smith" \
8  --display-publish-time "2024-06-15" \
9  --key <keyname>
10
11# Preview extraction without publishing
12seed-cli document create -f content.md --dry-run
13
14# Append to an existing document
15seed-cli document update <hm-id> -f additional-content.md --key <keyname>

Verify the result:

bash
1seed-cli document get <hm-id> --md

Built-in PDF Extraction

The CLI also has built-in PDF extraction (pdfjs-dist + optional GROBID) which can be used directly:

bash
1# Built-in extraction
2seed-cli document create -f paper.pdf --key <keyname>
3
4# With GROBID for better academic paper extraction
5seed-cli document create -f paper.pdf --grobid-url http://localhost:8070 --key <keyname>
6
7# Preview extraction result
8seed-cli document create -f paper.pdf --dry-run

The LLM-powered approach (this skill) produces higher quality results for complex layouts, figures, and multi-column papers, but the built-in extraction is faster for simple documents.

Output Format Summary

The JSON output should be valid JSON matching HMBlockNode[]:

[
  {
    "block": {
      "id": "<8-char-id>",
      "type": "Heading|Paragraph|Code|Math|Image|Video|File|Embed|WebEmbed|Button",
      "text": "...",
      "annotations": [...],
      "attributes": {...},
      "link": "..."        // for Image, Video, File, Embed, WebEmbed, Button
    },
    "children": [...]      // nested HMBlockNode[]
  }
]

For the full schema, block type details, annotation format, and a comprehensive worked example, see references/seed-document-format.md.