Chapter 22Reference

Reference

Variables, commands, options, tokens, attributes, error codes, glossary. What you come to look up without wanting to re-read a chapter.

4 min read11 sectionsChapter 22 / 22

Environment variables

All documented in .env.example, the only versioned environment file. Locally: .dev.vars. In production: the host configuration, as runtime secrets. Never the repository.

Variable	Required	Role
`EDITOR_KEY_HASH`	yes	argon2id hash of the site key. Without it, no editing is possible — that is the default state.
`SESSION_SECRET`	yes	Session cookie signature. 32 characters minimum. Replacing it closes every session.
`EDITOR_NAME`	recommended	Author name for publications. Default: “Éditeur du site”.
`EDITOR_EMAIL`	recommended	Author address for publications.
`GIT_PROVIDER`	yes	`github` or `gitlab` (not implemented). Default: `github`.
`GIT_REPO`	yes	`owner/repo` on GitHub; `group/project` or numeric id on GitLab.
`GIT_BRANCH`	yes	Publishing branch. Default: `main`.
`GIT_TOKEN`	yes	Write token of the machine account. Scoped to that repository only.
`GIT_API_BASE`	no	Alternative API root: self-hosted instance, or the fake local service (`http://127.0.0.1:8787`).
`RATE_LIMIT`	in production	A key-value binding, not a text variable. Without it, counting falls back to memory.

Commands

Command	Where	Role
`npm create inline@latest <folder>`	anywhere	Creates a site. Options: `--nom`, `--courriel`, `--langue`.
`npm run dev`	site, repo	Astro server alone — layout, without editing.
`npm run build`	site, repo	Production build. Fails if content is invalid.
`npm run serve:functions`	site, repo	Site + functions on `http://127.0.0.1:8788`. This is where you edit.
`npm run mock:git`	site, repo	Fake local Git repository on `:8787`. Port: `MOCK_PORT`.
`npm run check`	site, repo	Raw HTML, language parity, logs, secrets.
`npm test`	repo	The whole suite, build included.
`npm run create:site`	repo	A site's credentials. Options: `--nom`, `--depot`, `--branche`, `--auteur`, `--courriel`, `--ecrire`.
`npm run make:key`	site, repo	A key and its hash — rotation. Shipped with the site since `create-inline` 1.1.0.
`npm run bootstrap`	repo	Bootstrapping. Options: `--html`, `--page`, `--langue`, `--essai`, `--sortie`.
`npm run test:scaffold`	repo	Site created from scratch, installed, built, checked.
`npm run test:pack`	repo	Same, from publication archives.
`npm run pack:core` / `pack:cli`	repo	Builds the archives.
`npm run release:core` / `release:cli`	repo	Publishes to the registry.

Integration options

js js

inline({
  locales: ['fr', 'en'],                    // required — reference language first
  support: { email: 'contact@agency.com' }, // shown to the client on /admin and /aide
  theme: 'src/styles/theme.css',            // default
  pages: { admin: true, help: true },       // false to provide your own
})

inline({
  locales: ['fr', 'en'],                    // required — reference language first
  support: { email: 'contact@agency.com' }, // shown to the client on /admin and /aide
  theme: 'src/styles/theme.css',            // default
  pages: { admin: true, help: true },       // false to provide your own
})

Style tokens

Key	Values	Class produced	Variable expected
`size`	`xs sm base lg xl 2xl 3xl`	`.cms-size-*`	`--size-*`
`weight`	`thin light regular medium semibold bold`	`.cms-weight-*`	`--weight-*`
`italic`	`true false`	`.cms-italic`	—
`align`	`left center right`	`.cms-align-*`	—
`color`	`primary secondary muted accent inverse`	`.cms-color-*`	`--color-*`

Field types

text text

text      { type, value, style }                                headings, labels, plain paragraphs
richtext  { type, value }                                       emphasis, links, lists — 7 tags
image     { type, kind:'image', src, alt, width, height }        file from src/media
video     { type, kind:'video', provider, videoId, title }       YouTube or Vimeo, never a file

text      { type, value, style }                                headings, labels, plain paragraphs
richtext  { type, value }                                       emphasis, links, lists — 7 tags
image     { type, kind:'image', src, alt, width, height }        file from src/media
video     { type, kind:'video', provider, videoId, title }       YouTube or Vimeo, never a file

Attributes placed in the HTML

Attribute	Value
`data-cms`	Field path, e.g. `blocks.hero.title`
`data-cms-type`	`text` · `richtext` · `media`
`data-cms-kind`	`image` · `video`
`data-cms-untranslated`	`true` if the field comes from the reference language
`data-cms-list`	`collections.{name}`
`data-cms-item`	The item id
`data-cms-template`	Name of the list it is the model for
`data-cms-blank`	JSON of a blank item
`data-cms-file`	The page's content file (on `body`)
`data-cms-locale` · `data-cms-page`	Current language and page (on `body`)
`data-cms-locales`	Site languages: code, address, label (on `body`)

Naming rules

Object	Shape	Example
Page file	lowercase, digits, hyphens	`our-services.json`
Write path	`src/content/pages/{language}/{page}.json`	`src/content/pages/en/home.json`
Media file	`[a-z0-9]+(-[a-z0-9]+)*.(jpg\|png\|webp)`	`bakehouse-at-dawn.webp`
Item id	one letter, a hyphen, 3+ digits	`t-001`
Language code	two lowercase letters	`en`
Commit message	one line, 120 characters	`content(en): home — hero.title`

Error codes

Internal code	HTTP	Meaning
`bad_request`	400	Invalid body or path.
`unauthorized`	401 / 502	Missing session (401) or repository refusing access (502).
`method_not_allowed`	405	Method not expected on this route.
`not_found`	404 / 502	File or repository not found.
`conflict`	409	Stale version: someone published in the meantime.
`too_large`	413	Size cap exceeded.
`unsupported_format`	415	Unrecognised image format or out-of-range dimensions.
`invalid_content`	422	Schema, media, ids or markup refused.
—	429	Rate exceeded. `retry-after` header.
`unavailable`	502	The repository did not answer.

Ports

`4321`	`npm run dev`	Astro alone
`8788`	`npm run serve:functions`	Site + functions
`8787`	`npm run mock:git`	Fake Git repository

Glossary

Term	What it is	What the client reads
Overlay	The editing interface layered over the page.	—
Site key	The shared secret, hashed with argon2id.	“your key”
Edit marker	Secret-free cookie that triggers loading the overlay.	—
Optimistic lock	Version comparison before writing.	“someone published in the meantime”
Version	Opaque fingerprint of a file's state (blob SHA on GitHub).	—
Publication	A commit, then a site rebuild.	“Publish”
Draft	Changes saved in the browser.	“unpublished changes”
Style token	A schema enum value.	a button in the bar
Bootstrapping	Extracting content from an annotated HTML page.	—

Where to read the code

Question	File
What shape is the content?	`inline-core/src/schema.ts`
Which style variants exist?	`inline-core/src/style-tokens.ts`
Who is allowed to write?	`inline-core/src/server/auth.ts`
Which caps, paths, budgets?	`inline-core/src/server/guard.ts`
How do we talk to the repository?	`inline-core/src/server/git-provider.ts`, `github.ts`
What does publishing do, in order?	`inline-core/src/server/routes/save.ts`
How does the overlay link DOM and JSON?	`inline-core/src/editor/index.ts`
What is placed in the page?	`inline-core/astro/index.ts`
How is a video address read?	`inline-core/src/video.ts`
How does the translation fallback work?	`inline-core/src/translate.ts`

Environment variables#

Commands#

Integration options#

Style tokens#

Field types#

Attributes placed in the HTML#

Naming rules#

Error codes#

Ports#

Glossary#

Where to read the code#