Overview
SHM documents can embed rich media (images, videos, files) and other SHM documents. All media is stored as content-addressed blobs, ensuring integrity and enabling distributed serving.
Embedding Images
Images are uploaded as blobs to the daemon, then referenced from Image blocks using their IPFS CID.
Upload via HTTP API
# Upload an image to the daemon
curl -X POST http://localhost:55001/ipfs \
-F "file=@photo.jpg" \
-H "Content-Type: multipart/form-data"
# Response: {"cid": "bafybei..."}Reference in Document
// In a document change:
{
"replace_block": {
"block_id": "img1",
"type": "Image",
"ref": "ipfs://bafybei...",
"attributes": {
"width": "800"
}
}
}The width attribute controls the display width. Images are served directly from the gateway's blob store via the /ipfs/ endpoint.
Embedding Videos
Video embedding works the same as images — upload the video file, get a CID, and use a Video block:
{
"replace_block": {
"block_id": "vid1",
"type": "Video",
"ref": "ipfs://bafybei..."
}
}For external videos (YouTube, etc.), use WebEmbed blocks instead:
{
"replace_block": {
"block_id": "we1",
"type": "WebEmbed",
"ref": "https://www.youtube.com/watch?v=VIDEO_ID"
}
}Embedding Other Documents
One of SHM's most powerful features is document transclusion — embedding content from one document inside another. This enables modular, composable knowledge bases.
Full Document Embed
{
"replace_block": {
"block_id": "emb1",
"type": "Embed",
"ref": "hm://z6Mk.../other-document",
"attributes": {"view": "content"}
}
}The content view renders the full document inline, as if its blocks were part of your document.
Card View
For a compact reference, use the card view:
{"attributes": {"view": "card"}}This renders a summary card with the document's title, subtitle, and icon.
Block-Level Embeds
You can embed a specific block from another document by appending the block ID to the HM URL:
"ref": "hm://z6Mk.../document?b=block-id"This enables fine-grained content reuse — pull in a single paragraph, code example, or section from any document.
File Attachments
Attach any file type (PDFs, CSVs, archives) using File blocks:
{
"replace_block": {
"block_id": "file1",
"type": "File",
"ref": "ipfs://bafybei...",
"attributes": {
"name": "report.pdf",
"size": "2048000"
}
}
}File blocks render as download links showing the filename and size.
Inline Links
For inline references to other documents (within text), use link annotations:
{
"block": {
"type": "Paragraph",
"text": "See the publishing guide for details.",
"annotations": [{
"type": "link",
"starts": [8],
"ends": [24],
"attributes": {
"url": "hm://z6Mk.../guides/publishing"
}
}]
}
}Links to other SHM documents are resolved by the web UI to show hover previews and enable navigation within the knowledge base.
Best Practices
• Always upload media before publishing — ensure blobs exist before referencing them
• Push media blobs along with documents — use recursive push to include all referenced content
• Use appropriate embed views — content for full inclusion, card for references, inline for mentions
• Optimize images before upload — the daemon doesn't resize; upload appropriately sized images
• Cross-link related documents — use inline links and embeds to create a navigable knowledge graph