Content Type: Attachment

Changes to how this Type behaves are requested through a GitHub Issue and implemented, together with this reference page, through the repository's normal workflow. See /_docs/posts for how Content Types, Roles, and Rank work in general, and docs/Internal/type-doc-templates.md for the Content Type Doc template this file follows.

A downloadable file attached to a Post — a PDF report, a Word document, a spreadsheet, a zip archive. Same shape as Image/Video/Audio, but the point is downloading the file itself rather than playing or displaying it inline.

Where it comes from

Ingested one of two ways — see /_docs/media for the full mechanics:

• Upload — a file, drag-dropped or chosen from a file picker.
• Fetch by URL — paste a URL and the server downloads and stores the file itself.

There is no Embed mode for Attachment (unlike Video/Audio) — a downloadable file doesn't fit an embed-snippet model.

Accepted file types are a fixed allowlist, not "any file whatsoever": PDF, plain text, zip, RTF, Word (.doc/.docx), Excel (.xls/.xlsx), and PowerPoint (.ppt/.pptx).

Fields

• The file itself (mandatory) — a locally-stored file. Immutable once created, same as every Content Type.
• Caption (optional) — shown as a short note beneath the link (Additional Information) or beneath the caption field in the admin editor; not the link's own visible text — see below.
• Search text (specialist, read-only) — for a PDF or plain text file, the visible text is extracted at ingestion time and stored, for a future search feature to index. Not extracted for any other file type, and nothing queries it yet — see /_docs/roadmap.

Semantic HTML and accessibility

Renders as a plain <a> link pointing at the file's address (AttachmentRow.tsx/AttachmentRow's raw-HTML sibling for the inline path) — a recognized file-type icon (decorative, aria-hidden) followed by the file's own real filename as the visible, accessible link text. Kartotek never previews, embeds, or extracts the file itself for display — it only identifies it and links to it; the browser (or an installed application) decides whether to display, download, or hand it off. A PDF or plain text file opens inline in the browser tab it's clicked from (the server serves it with an inline Content-Disposition); every other file type prompts a download instead. This is decided server-side, not by an HTML download attribute, so the same link behaves consistently wherever it's clicked from.

File-type icon

Selected purely from the filename's own extension — never from file-content inspection or a generated preview. A small fixed category set: PDF, Office document (Word/RTF/OpenDocument), Spreadsheet, Presentation, Archive, Text, Image, Audio, Video, and a generic fallback for anything unrecognized. An icon mismatch or an unrecognized extension never blocks access to the file — the filename itself, always present, is what's authoritative.

Role, Rank, and Reference

A Post can hold several Attachments at once, each with its own Role, or several sharing the same Role, distinguished by Rank — see /_docs/posts. Every Attachment also has an optional Reference — a separate, Post-unique name for addressing it inline instead of by Role/Rank — see /_docs/posts's "Reference: inline addressing" for the full detail.

Editing

In the admin Post editor, the Attachments section holds one block per file, with Upload / Fetch by URL controls, a Role field, a Position (Rank) field, and a caption field. Every Post Type's editor shows the same Attachments section regardless of which Type is active.

Rendering contexts

Inline

A single-Role Attachment can be inline-embedded from markdown the same way as an Image, e.g. {{quarterly-report}} — see /_docs/markdown for the full content reference syntax. Renders as one compact row (icon + linked filename) at that spot in the text — the exact same row shape Additional Information uses below.

Additional Information group

Every Post Type's shared Additional Information container's Attachments group — every eligible Attachment on the resolved Post, ordered by Rank then stable Version order, each the same icon + linked-filename row as inline, with its caption shown beneath if present.

Post metadata-page traversal

Every Attachment the Post has ever held (current Version, or full history via /metadata/history) is enumerated with its caption and URL as JSON-LD/native JSON — see /_docs/posts's Metadata page section.

Standalone Content Element page

/_element/attachment/:id shows the same icon + linked-filename row plus its caption, followed by whatever technical facts are known and public (file size, MIME type) — no preview or embedded viewer, same as everywhere else — gated exactly like the owning Post's own page.