Glossary
Short definitions of the terms used across the guide, grouped by where you meet them, with links to the pages that explain them. For everyone.
On this page
This page defines the words the guide uses. Each entry is short. Follow the link for the full explanation.
Content and the lake
Workspace. One organisation’s content in the CMS: its documents, media, tags, people, sites and tokens. Each workspace has its own lake. See What is mdlake.
Lake. The Git repository of a workspace. It holds the published documents as Markdown files and the published media with their metadata. Drafts are not in it. See Lake format.
Document. A piece of knowledge written in the editor and stored as one Markdown file with frontmatter. It has an ID, a title, a summary, tags, a status and a slug. See Writing documents.
Draft. The unpublished version of a document or media metadata. It lives in the CMS’s database, not in the lake. See Publishing.
Published. In the lake. Publishing writes the document to Git and makes a site able to use it. Unpublishing removes it.
Frontmatter. The block of key: value lines at the top of a document, between two --- lines. It carries the document’s facts.
Summary. A plain-text paragraph of at most 300 characters that says what a document is about. Tools and sites use it in cards, search results and descriptions.
Slug. The last part of a page’s address, in lowercase words with hyphens. A document can set its own.
Tag. A short label (up to 50 characters, up to 20 per document) used to group documents and media. See Folders and tags.
ID (ULID). The 26-character code that identifies a document or a media file for ever. Links and sites use the ID, never the path, so renaming or moving does not break them.
lake:// link. A link in a document’s body that points to another document by ID.
asset:// link. A link or image in a body that points to a media file by ID.
Media, asset. An image or a document file (such as a PDF) in the media library. See Media library.
Sidecar. The JSON file next to a published media file, with the same ID. It holds alt text, caption, focal point, rights, tags and the public address (url).
Alt text. The text that describes an image for people who cannot see it. It lives in the media library and is checked on every site build.
Focal point. The part of an image that must stay in view when a site crops it.
Order. A number on a document (in its frontmatter) or on a folder (in its _folder.yaml) that places it among the items of its own folder, lower first. Items without one follow, by title or name. Editors set it by dragging. See Reorder documents and folders and Lake format.
_folder.yaml. The optional file inside a lake folder that holds the folder’s order. It exists only while the folder has a number and published content.
Manifest. _manifest.json, the index of everything published, rewritten on every publish.
Collection. A list of documents that a site selects by folder and tags and sorts in a stated way.
Trash. Where deleted documents and media wait before they are removed for good. See Trash.
Mirror. A private GitHub repository that the CMS keeps in step with a workspace’s lake. See Connect GitHub.
Webhook. An address the CMS calls after a publish. See CMS configuration.
People and access
Admin. A user who manages the installation: users, invitations, workspaces and settings. Developers are admins.
Editor. A user who writes and publishes content in the workspaces they belong to.
Magic link. A one-time sign-in link sent by email. The CMS has no passwords.
Passkey. A sign-in method that uses your device’s lock (fingerprint, face or PIN) instead of a password.
Invitation. An email that lets a new person join, after which they sign in with a magic link. See Users and invites.
Workspace token. A secret that gives a tool read access to one workspace: scope published for published content, preview for drafts. Some tokens can also import Markdown or report AI usage. See Workspace tokens.
Signed link. A temporary address for a file that is not published yet. It expires.
Building sites
Builder. The set of tools that turns a lake into a site: the plugin for Claude Code, the site kit and the lake loader. See Install the builder.
Plugin (mdlake-builder). The Claude Code plugin with the skills, hooks and the lake MCP server.
Skill. A written procedure that Claude Code follows, such as add-form. See Skills.
MCP. A way for Claude Code to call tools. The lake server lets it look at the CMS’s content. It is for looking; sites are built from the lake clone.
Site kit. The @mdlake/site-kit package. It holds the page routes, modules, layout, checks and the mdlake command. A site depends on it and does not copy it.
Lake loader. The @mdlake/lake-loader package that reads and validates a lake.
Ruleset. The set of rules for sites, written in the site’s CLAUDE.md, plus the site types. Its version is in .mdlake/ruleset.json.
Site type. A kind of site, such as corporate or documentation, with the content slots it needs. See Site types.
Slot. A named place a site type needs content for, such as about or services. lake.config.ts binds each slot to a document, a collection or a media file.
Binding. The link from a site to lake content, by ID for a document or by query for a collection. Content is bound, never copied into code.
Brief. The answers to the planning interview: purpose, audience, main call to action, scope, must-have pages, tone, mode and what to avoid. It is the top of plan.md.
plan.md. The approved plan of a site: pages, modules, content kinds, generated copy and gaps.
design.md. The site’s design: tone, colours, fonts and shape. Approved with the plan.
Module. A ready-made block of a page, such as a hero, a feature grid, a testimonial or a call to action.
Content kind. How a module gets its words. Rendered: the document as it is. Shaped: parts taken from a document by reading rules. Generated: copy written from several documents, with sources recorded. See How sites work.
Generated copy. Marketing text written by the generate-copy skill into src/content/generated/<key>.md, with the sources and hashes it came from. See Generated copy.
Provenance. The record of where generated copy came from, and provenance.json, the record of which files are the kit’s, generated or the site’s.
Snapshot mode. The site is built from one locked lake commit and moves only when a developer refreshes it. The default.
Live mode. The site follows the latest lake commit and does not check the lock.
lake.lock. The file that records the locked commit. See Lake format.
Managed lake clone. .mdlake/lake, the copy of the lake the kit fetches at the locked commit. Do not edit it.
Refresh. Moving a snapshot site to newer lake content as a reviewable change. See Refresh content.
Route snapshot. site-snapshot.json, a summary of every page of a build, used to show what a refresh changes.
Candidate. A lake commit being checked for a refresh before the lock moves.
Preview. The site shown with the CMS’s drafts, for editors. Never deployed to production. See Preview drafts.
Ownership zones. The three kinds of file in a site: kit (written by tools, never edited), generated (written by skills from the plan and the lake) and site (yours). See Ownership zones.
Adopt. Move a generated file to the site zone so that no tool overwrites it again.
Migration. A step run by npx mdlake migrate to bring a site to a newer kit version. See Upgrade and migrate.
Hosting and servers
Hosting model. Static, server or split. See Choose a hosting model.
Static. Pages only, on Azure Static Web Apps.
Server. Pages plus Astro server routes, on a Linux App Service running Node.
Split. Static pages on Static Web Apps (Standard) plus a separate backend in api/, linked so /api/* is on the site’s own domain.
On-demand route. An Astro route that runs on the server for each request (export const prerender = false).
Backend. The separate server project in api/ (Node or .NET). See A separate backend.
OpenAPI document. api/openapi.json, the description of the backend’s endpoints.
Orval. The tool that writes the typed client and Zod schemas from the OpenAPI document.
Linked backend. The Static Web Apps feature that proxies /api/* to an App Service.
Form definition. src/forms/<name>.ts: the fields, validation, subject and settings of one form. See Forms.
Honeypot. A hidden field that people leave empty and simple bots fill in.
Rate limit. A cap on how often one address can submit a form.
Turnstile. Cloudflare’s bot check for forms. Off by default. See Turnstile.
Resend. The email service that sends form mail in production. See Mail.
Bicep. Azure’s language for describing resources. The kit writes the files and you deploy them with az. See Azure and Bicep.
Key Vault. The Azure service that holds secrets. The app reads them through Key Vault references.
Managed identity. The identity an Azure app has so that it can read the Key Vault without a password.
OpenID Connect (OIDC). The way a pipeline signs in to Azure without a stored secret. See GitHub Actions.
Service connection. The Azure DevOps object that lets a pipeline use an Azure subscription. See Azure DevOps.
Deployment token. The secret a pipeline uses to upload to a Static Web App.
The local stack
Azurite. The local emulator of Azure Blob Storage.
Mailpit. A local mail inbox that catches the CMS’s email. Open it at http://localhost:8025.
MarkItDown. The converter that turns Word, PowerPoint, PDF and Excel files into Markdown.