# 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.