# Build a website Tusk-ready, from the first line of code You are an AI coding agent about to build a new website (or a new page of one) that its owner will later edit in Tusk CMS. This document tells you how to build it so that it is Tusk-ready while you write it: every piece of content the owner may change carries its mark the moment it exists, the build already pulls published content, and connecting the site to Tusk afterwards is a formality with a scan that finds exactly what you meant. Read it once, then build. It is about BUILDING; the connect grammar it relies on is in the connect guide, which you read when you reach the handoff: https://tuskcms.com/llms-full.txt the connect guide (grammar, kinds, hosts) https://tuskcms.com/starter/README.md a complete Tusk-ready starter site to copy https://tuskcms.com/examples/marked-site.html one page with every kind on it Canonical copy of this document: https://tuskcms.com/llms-build.txt The one line a developer pastes to start you off, with or without a slug: "Build this website Tusk-ready. Read https://tuskcms.com/llms-build.txt first and follow it exactly." "Build this website Tusk-ready for the site . Read https://tuskcms.com/llms-build.txt first and follow it exactly." If the line names a slug, the site already exists in Tusk (the developer pressed New site in the dashboard). Use that slug as TUSK_SITE in step 6 and give it to the connect step at the end. If there is no slug, the connect step creates the site. Tusk is for sites built by AI tools like you, deployed as static files or a static build on the developer's own host. Nothing of Tusk runs between a visitor and the site. The owner edits in Tusk; a publish rebuilds the site through the host's deploy hook and the two build scripts write the published values into your marked HTML. =============================================================================== ## 0. The rule =============================================================================== Every piece of content the owner may want to change gets a `data-tusk` mark AS YOU WRITE IT. Not after. Not "we will mark it when we connect". When you type a headline, you type its attribute in the same breath: ```html

A headline the owner can change.

``` The test for "may want to change": would the owner ever ask a developer to change these words, this photo, this link, this list? Then mark it now. The words you write become the starting content in Tusk; there is nothing to migrate later. Two consequences you design for from the start: - Every marked element holds its content directly: the words inside it, the `src` on it, the `href` on it. The attribute goes on the element that holds the content, not on a parent and not on a child. - Mark every piece of content as you write it. Tusk also makes whatever you leave unmarked editable by its own reading of the page, so nothing is locked away from the owner, but a mark is what gives a field the right name, kind and label and keeps it stable when the markup moves. =============================================================================== ## 1. Pages and page keys =============================================================================== One `data-tusk-page` per page, on ``, with the human name of the page. It names the page in the owner's editor and settles the page key (the name, slugged: `About Us` becomes `about-us`). ```html ``` Put it on every page, including pages with only one editable line. With it set, a bare field name is allowed (`data-tusk="headline"` is `home.headline` on the Home page); writing the full `page.field` is clearer and never wrong. File layout: plain HTML pages (`index.html`, `about.html`, `contact.html`, or `about/index.html`) are the simplest and what the starter uses. A framework site (Next, Astro, Eleventy, Hugo) puts the same marks in its templates and reads the pulled JSON there; see the connect guide, PART TWO, section F. Key rules you follow while naming: - Field ids are `snake_case`: letters, digits and `_` only. `home.services_heading`. - Reserved ids the scanner silently drops, never use them as a field or sub-field id: `id`, `key`, `kind`, `title`, `url`, `order`, `state`, `portal`, `updatedAt`, `tenant`. So the browser tab title is `page_title`, a card's heading is `name` or `heading`, and a link's destination is never a field of its own: mark the `` itself and it is a `link`. - One key, one element per page. The same key marked twice: the first wins, the rest vanish. - Text that repeats on every page (a footer line, a phone number) uses the page key `globals`: `data-tusk="globals.footer_line"`. Put the same mark in every page's footer so the build fills it everywhere; Tusk shows it once, as site-wide text. =============================================================================== ## 2. The marks: which kind, and when =============================================================================== Nine kinds. Tusk infers the kind from the tag and the content; add `data-tusk-kind` only when the inference would be wrong. Add `data-tusk-label="..."` whenever the owner would not know what the field is from its id alone ("Small line above the headline", "Hero photo"). **text** (the default): one line. A heading, an eyebrow, a label, a name. ```html

What you do

A headline the owner can change.

``` A heading that wraps a styled ``, a `
` or a leading inline icon is still plain `text`: Tusk edits only the words and keeps the decoration. A heading longer than 140 characters would be inferred as textarea; add `data-tusk-kind="text"` if it must stay one line. **textarea**: paragraphs. Inferred when the element contains `

` tags or its text is longer than 140 characters. Force it with `data-tusk-kind="textarea"` on a wrapper of several `

`, or on short multi-line text the owner should be able to add lines to (opening hours). ```html

Two or three sentences long enough to be a paragraph ...

First paragraph.

Second paragraph.

``` Values come back with a blank line between paragraphs; the build writes one `

` per paragraph. **html** (opt-in only): a line whose inline markup the owner edits too, a link or a highlight inside the sentence. `data-tusk-kind="html"`. Safe inline tags only survive. Reach for it rarely; most copy is `text` or `textarea`. **photos**: an image slot. Inferred for ``, ``, `

`, and for any element with an inline `style="background-image: url(...)"` and no `` inside (the photo goes into the style). Add `data-tusk-aspect` (`16:9`, `4:3`, `1:1`, `4:5`) so the editor's cropper matches your design. Give every `` real `width` and `height` so the layout holds when the owner swaps the photo. ```html ...

A line over the banner.

``` Ship real placeholder images (PNG, JPEG or WebP) at the right size so the page looks finished before the owner uploads anything. SVG is not imported as a photo. **file**: a download. Inferred for an `
` whose `href` ends in `.pdf`, `.doc`, `.docx`, `.xls`, `.xlsx` or `.zip`. Ship the placeholder file too, so the link works before the owner uploads the real one. ```html brochure ``` **link**: a button or link whose words AND destination are the owner's. Inferred for an `` with a real `href` (not `#`, not a document). `mailto:` and `tel:` are links too. Want only the words editable? Add `data-tusk-kind="text"`. ```html Get in touch hello@example.com ``` **embed**: a video or a map, one https address written into `src`. Inferred for ` ``` **toggle** (opt-in only): a section, bar or line the owner shows or hides. `data-tusk-kind="toggle"` on the wrapper; the build writes or removes its `hidden` attribute and nothing else. Mark the words inside as fields of their own. Make sure your CSS honours `[hidden]` on that element. ```html ``` Use a toggle for a promo bar, a seasonal notice, an optional section. Give the owner that control from day one instead of a "can you hide the banner" email later. **SEO: the title and the description**: mark `` and `<meta name="description">` in `<head>` on every page, as `page_title` and `meta_description`. They are `text`; the meta's value is its `content`. ```html <title data-tusk="home.page_title">Your Business | What you do ``` **list**: see the next section. =============================================================================== ## 3. Repeatable groups are lists =============================================================================== Anything the owner may add to, remove from or reorder is a list: services, team members, testimonials, logos, FAQs, projects, locations, prices. Build it as a list from the start; never as three hand-written cards the owner would have to ask you to make four. Three attributes, three levels, exactly this arrangement: ```html
``` Rules you build to: - `data-tusk-list="page.field"` on the wrapper; `data-tusk-item` on each repeated child; `data-tusk-field="part"` on each part inside an item. - THE FIRST ITEM DEFINES THE SHAPE. Give it every sub-field with its label, kind and aspect. Later items carry content only. A part missing from the first item does not exist. - Sub-field kinds are `text`, `textarea`, `link` and `photo` (singular, one photo per entry). At most 12 sub-fields, from the first item. - Mark every item you write, so each becomes one starting entry. - A plain `data-tusk` inside a list wrapper is ignored; everything inside a list belongs to the list. Do not nest a list in a list. - `data-tusk-max` caps how many entries the owner may add; set it to what the layout can take. - Design the card so one entry more or fewer still looks right: a grid with `auto-fit` columns and equal-height cards, not a layout that assumes three. =============================================================================== ## 4. The menu: it becomes the editor's sections =============================================================================== The scanner reads the site's primary navigation and groups the owner's page list by it, so the editor's sidebar mirrors the site's own menu. Build the menu so that it reads cleanly: - A `