# How this site is built: TUFTE, llms.txt, JSON-LD and a build that refuses broken pages

## How this site is built: TUFTE, llms.txt, JSON-LD and a build that refuses broken pages

This site is generated by TUFTE, the Tiling User Form Topology Engine, from a flat directory of Markdown files. Each file with `visibility: public` becomes a page with structured data, a Markdown twin, an entry in `llms.txt` and `llms-full.txt`, three feeds and a sitemap line, and a file that breaks the rules is refused rather than published. The details below come from the engine's documentation (version 0.16.0) and from inspecting the build output of this very article on 2026-10-22.

### What is TUFTE, and what does it publish?

TUFTE is the Group's graphical interface engine for web servers and platforms. It renders documents as tiles with a stable reading order, and the same package exports a *publication application*: given a catalog of admitted cells (documents) and a site description, it renders article pages, home and archive indices, search, error pages, feeds and machine-readable artifacts from one set of route declarations. Per its documentation, "a static publisher consumes the same route declarations; it does not carry a second rendering path", so what the build writes is what the server would serve. The source executes as plain JavaScript, with no TypeScript build or generated runtime copy. Static pages without enhancement emit no framework JavaScript.

The engine's source repository is not public at the time of writing, so this article describes its documented behavior and output, not code you can clone.

### How does a Markdown file become a page?

A file in `content/` has a front matter block that the catalog checks:

```yaml
---
title: "Specific, keyword-forward title"
summary: "A 120-160 character claim, never 'This article...'"
date-created: 2026-10-21
type: article
status: active
visibility: public
tags: [x402, agent-payments, http-402]
---
```

The file name is the URL: `content/x402-seller-design.md` becomes `https://engineering.561.group/x402-seller-design/`. The catalog refuses a cell that lacks a title or an ISO `date-created`. This site's acceptance rule is explicit: only cells with `visibility: public` are published. Another file in the same directory, a draft with `status: potential` and no `visibility` field, is reported as "withheld" on every build. The engine's documentation describes why this is a consumer decision: "A corpus being readable does not make every document publishable." The `includeCell` predicate runs before any route is projected, and only a literal `true` admits a cell.

### Which files does each page produce?

For this article the build wrote these artifacts (names relative to the site root):

| Artifact | Purpose |
| --- | --- |
| `/how-this-site-is-built-tufte/index.html` | The page, with canonical URL, Open Graph and Twitter tags, JSON-LD |
| `/how-this-site-is-built-tufte/index.md` | A Markdown twin, advertised with `<link rel="alternate" type="text/markdown">` |
| `/llms.txt` | Site intro and one line per article with its summary, per [llmstxt.org](https://llmstxt.org/) |
| `/llms-full.txt` | Every published article as Markdown in one file (about 100 KB for the first twelve pages) |
| `/feed.rss.xml`, `/feed.atom.xml`, `/feed.json` | Three feeds, each with the organizational author |
| `/sitemap.xml` | Every page with a `<lastmod>` taken from the article's date |
| `/search/` and a generated index | Client-side search with no server |
| `/robots.txt` | Allows all, and names GPTBot, OAI-SearchBot, ChatGPT-User, ClaudeBot, Claude-SearchBot, PerplexityBot, Google-Extended, Applebot-Extended, CCBot and Bingbot explicitly |

The robots file is a statement, not a technical necessity: `User-agent: *` with `Allow: /` already permits those crawlers, but naming them removes doubt about whether an AI crawler is welcome. We allow them because the purpose of these pages is to be read, quoted and cited.

The `llms.txt` header on this site is built from `site.json`: a one-line description as a blockquote, an introductory paragraph, then sections of links ("Machine interfaces", "561 Group") that we authored, then the article list. The Markdown twin is rebuilt from each cell's parsed blocks. Front matter is dropped; wikilinks and citations are resolved to plain links and labels. One imperfection we observed: the twin begins with the title as a heading and then repeats it as the first heading of the body. It does not affect the HTML.

### What structured data does each page carry?

Every article has a JSON-LD graph. From the live page for [the seller-design article](https://engineering.561.group/x402-seller-design/):

```json
{"@id":"https://engineering.561.group/x402-seller-design/","@type":"Article",
 "headline":"What an x402 seller should do that the spec doesn't require",
 "datePublished":"2026-10-21","inLanguage":"en","wordCount":1469,
 "keywords":"x402, agent-payments, http-402, seller-engineering, usdc",
 "publisher":{"@type":"Organization","name":"Red Cup Engineering","url":"https://engineering.561.group/"},
 "author":{"@type":"Organization","name":"Red Cup Engineering","url":"https://engineering.561.group/"},
 "isPartOf":{"@id":"https://engineering.561.group/#website"},
 "identifier":"ni:///sha-256;eYeU9-p__RrwPbHiZnrC57lHyutIZuOVM1uKEXxajHU"}
```

Three decisions here are deliberate.

**Organizational authorship.** The site declares `author` as an Organization in `site.json`. The engine's rule is "`site.author` wins; front-matter `authors:` is read only when the site declares none", and a site that declares an author "never emits a name from a source paper". Our articles are attributed to the engineering company, with the `publisher` chain running up to the parent organization, the 561 Group, through `parentOrganization` and `sameAs` links.

**A content address as identifier.** The `identifier` is the RFC 6920 `ni:` name of the cell, the same kind of name described in [Content-addressed names](https://engineering.561.group/content-addressed-names-ni-rfc-6920/). The JSON feed uses the same style of `id` per item. A reader or agent can attach evidence to the cell's name rather than to a URL that might later serve different words.

**Fediverse attribution.** Each page head carries `fediverse:creator` and a `rel="me"` link naming the organization's ActivityPub identity. The handle `@engineering@engineering.561.group` is declared in `site.json`. At the time of writing, a WebFinger request to this site for that account does not yet return a JSON resource: the actor is being launched separately, and the tags are forward-declared. The design of the provider is in [ActivityPub publication provider](https://engineering.561.group/activitypub-publication-provider/).

For scholarly material, the engine adds Google Scholar's Highwire `citation_*` tags and Dublin Core `DC.*` tags when a cell is a `paper`, a theorem-like type, or sets `scholarly: true`, using the cell's `doi`, `pdf`, `abstract` and `keywords`. These articles are `type: article`, so they do not emit Highwire tags.

### What does the build refuse?

The build reports a count in one line, for example:

```
engineering.561.group: 12 accepted, 1 withheld, 0 refused, 141 artifacts
```

"Refused" is the interesting column. While preparing these articles we tripped two of its checks by accident:

- `refused mt: unknown citation key "foo"`: a body cited `[@foo]` and the front matter's `references` map had no such entry. The page was not published with a dangling citation.
- `refused mt: heading level skips from h1 to h3`: a body that began with a second-level heading, where the engine's convention is a first-level title that the page then renders one level down.

Both are the engine enforcing the document's accessibility and citation contracts instead of emitting HTML that looks acceptable and is not. The same discipline runs through the rest of the Group's publishing: a draft is not a publication, and a commit is not a deployment.

### What are the honest limits?

The build output is a set of static files. Nothing about producing them proves they are deployed, indexed or cited; the engine's documentation distinguishes source, package, installed host and independent receiving as separate facts, and so do we. Publishing the machine-readable surfaces does not guarantee that a search engine ranks the page or that an answer engine quotes it. We cannot observe either, and report no such results. And the engine is early software: the Markdown twin duplicates its heading, the engine's source is private, and the math rendering described in [Math on the web without JavaScript](https://engineering.561.group/mathml-without-javascript-markdown/) is a capability of the Markdown package that this site's publication pipeline does not yet apply to its own pages.

If you want a starting point, the Apache-2.0 [x402 boundary reference](https://github.com/561-group/x402-boundary-reference) and the other public repositories under the [Red Cup Engineering organization](https://github.com/red-cup-engineering) are the places to read code today. The [article index](https://engineering.561.group/start-here/) groups everything published here.