---
title: "documents.tt Template"
url: "https://docs.chinaski.net/en/theming/documents-tt/"
type: "page"
language: "en"
description: "How documents.tt renders the public /documents/ listing: the card grid, type icons and meta badges, the empty state, and which documents are included."
updated: "2026-09-29"
generated: "Markdown rendition of the HTML page at url, built by Chinaski"
---

# documents.tt Template

`documents.tt` renders the public **documents listing page**, the site’s browsable grid of downloadable files, built at `/documents/` in each language. It’s a fully-themed template: header and footer partials included, standard head, and sortable-by-design card grid.

## What it renders

A card per document, linking to its download (`/documents/<slug>`):

- **Type icon**: chosen by the file’s MIME type (PDf, image, else a generic paperclip).
- **Title + description**: the card’s link text and optional lead-in.
- **Meta badges**: file size (KB or MB, computed), language code (upper-cased), folder name.
- An **empty state** (“No documents available.”) when the language’s listing comes up empty.

## What gets included

Only safe content ships in the listing, per language at build time:

- **Published only**: unpublished documents never appear.
- **Schedule windows respected**: documents not yet inside a scheduled publish window, or past their unpublish window, are excluded.
- **That language only**: documents for `en` don’t appear in the `es` listing.
- Ordered by title, canonicalized to the language’s `/documents/` URL.

## Theme considerations

- The template lives in `builder/site_templates/` (or your theme’s directory, which is searched first: the standard search rule from the template-files page).
- You can replace it wholesale per theme: the grid class names (`documents-grid`, `documents-card`, icon/title/desc/meta spans) plus `page_title` and `documents` in the stash are the template’s full surface; the standard header/footer partials and cache-modal attributes apply as usual.
- The cards link to URL-prefixed doc pages (e.g. `<url_base>/documents/<slug>`), and the download itself is served by the CMS, hence the `/documents/` proxy route on the hosting page (the built page is presentational; the dynamic download happens through the proxy).

## Build requirements

- The listing only appears when the **documents feature is in use**; a language with no published documents renders the empty state, and the build log’s `docs : /<lang>/documents/` line tracks its presence.
