# Clay

> Turn a folder of Markdown files into a fast, searchable documentation website. Everything you need to write, organize and publish docs with Clay.

This is the documentation (version 4.x, English) as Markdown for language models and agents. Every link leads to the Markdown of a page; [llms-full.txt](https://clay-doc.github.io/clay-example-repo/4.x/llms-full.txt) holds all pages in one file. Each page of the website is also available as Markdown at its own address with ".md" appended.

## Start

- [Clay Documentation](https://clay-doc.github.io/clay-example-repo/4.x/index.md): Turn a folder of Markdown files into a fast, searchable documentation website. Everything you need to write, organize and publish docs with Clay.

## Getting Started

- [Getting Started](https://clay-doc.github.io/clay-example-repo/4.x/getting-started.md): What Clay is, how to install it and how to build a first site in five minutes.
  - [Introduction](https://clay-doc.github.io/clay-example-repo/4.x/getting-started/introduction.md): What Clay is, what it does for you and how a Clay site comes together.
  - [Installation](https://clay-doc.github.io/clay-example-repo/4.x/getting-started/installation.md): Install Clay into a project with npm, pnpm or yarn, or run it without installing anything.
  - [Quick Start](https://clay-doc.github.io/clay-example-repo/4.x/getting-started/quick-start.md): Build your first Clay site from an empty folder in five minutes.
  - [Project Structure](https://clay-doc.github.io/clay-example-repo/4.x/getting-started/project-structure.md): The files of a Clay project, what each one does and what belongs in git.

## Writing

- [Writing](https://clay-doc.github.io/clay-example-repo/4.x/writing.md): Everything about the content of a page, from Markdown and code blocks to components, links and images.
  - [Pages](https://clay-doc.github.io/clay-example-repo/4.x/writing/pages.md): How Markdown files become pages, how pages get their titles and which front matter fields Clay reads.
  - [Markdown](https://clay-doc.github.io/clay-example-repo/4.x/writing/markdown.md): Clay Flavored Markdown - GitHub's Markdown plus alerts, components, math and diagrams - from headings and lists to tables and task lists, with examples.
  - [Code Blocks](https://clay-doc.github.io/clay-example-repo/4.x/writing/code-blocks.md): Syntax highlighting for over 200 languages, file names, highlighted lines, diffs, focus and a copy button.
  - [Alerts](https://clay-doc.github.io/clay-example-repo/4.x/writing/alerts.md): Six kinds of callouts for notes, tips and warnings, written with GitHub's alert syntax.
  - [Components](https://clay-doc.github.io/clay-example-repo/4.x/writing/components.md): Tabs, steps, cards, folded sections, prompts, badges, math, diagrams and file trees, written in plain Markdown.
    - [Tabs and Code Groups](https://clay-doc.github.io/clay-example-repo/4.x/writing/components/tabs.md): Alternatives in one place, like instructions per system or the same command for npm, pnpm and yarn; the reader's choice is remembered.
    - [Steps](https://clay-doc.github.io/clay-example-repo/4.x/writing/components/steps.md): A numbered list as a guide, with a numbered circle for each step and a line that leads to the next.
    - [Cards](https://clay-doc.github.io/clay-example-repo/4.x/writing/components/cards.md): Links as a grid of cards, with the icon and description of the pages they lead to, or ones of your own.
    - [Details](https://clay-doc.github.io/clay-example-repo/4.x/writing/components/details.md): Folded sections that readers open when they need them, like FAQs, long logs and background.
    - [Prompts](https://clay-doc.github.io/clay-example-repo/4.x/writing/components/prompts.md): A suggested prompt for AI assistants and coding agents, shown as written, with a button to copy it.
    - [Badges](https://clay-doc.github.io/clay-example-repo/4.x/writing/components/badges.md): Small labels in text and headings, like "New", "Beta" or "Deprecated", in the colors of the alerts.
    - [Math](https://clay-doc.github.io/clay-example-repo/4.x/writing/components/math.md): Formulas in LaTeX, inline or on a line of their own, typeset with KaTeX when the site is built.
    - [Diagrams](https://clay-doc.github.io/clay-example-repo/4.x/writing/components/diagrams.md): Flowcharts, sequence diagrams, pie charts and more from text with Mermaid, in the colors of your site.
    - [File Trees](https://clay-doc.github.io/clay-example-repo/4.x/writing/components/file-trees.md): Folders and files from an indented list, with icons by file type, comments and folders that fold.
  - [Links & Images](https://clay-doc.github.io/clay-example-repo/4.x/writing/links-and-images.md): Linking between pages like on GitHub, linking to sections, adding images and offering downloads.
  - [HTML](https://clay-doc.github.io/clay-example-repo/4.x/writing/html.md): Using HTML inside Markdown, videos and embeds, and what Clay removes to keep your site safe.
  - [Snippets & Variables](https://clay-doc.github.io/clay-example-repo/4.x/writing/snippets-and-variables.md): Write a text once and use it on many pages, include code from your project, and fill in values like the current version.
  - [Generated Docs](https://clay-doc.github.io/clay-example-repo/4.x/writing/generated-docs.md): API reference from your code, and other pages that tools write, generated before every build.

## Organizing

- [Organizing](https://clay-doc.github.io/clay-example-repo/4.x/organizing.md): How pages and folders become the navigation, how folders get their pages, and how versions and languages work.
  - [Navigation](https://clay-doc.github.io/clay-example-repo/4.x/organizing/navigation.md): How Clay builds the sidebar, breadcrumbs and previous/next links, and how to put pages in order.
  - [Folders](https://clay-doc.github.io/clay-example-repo/4.x/organizing/folders.md): Group pages into folders, and give folders a title, an icon, an order and a page of their own with index.md.
  - [Index Pages](https://clay-doc.github.io/clay-example-repo/4.x/organizing/index-pages.md): The start page and the page of every folder are Markdown files named index.md, with an optional list of pages and a large header.
  - [Versions](https://clay-doc.github.io/clay-example-repo/4.x/organizing/versions.md): Keep the docs of older releases online, with a version switcher and a banner that leads to the latest docs.
  - [Translations](https://clay-doc.github.io/clay-example-repo/4.x/organizing/translations.md): Translate your docs page by page, with a language switcher, fallbacks for untranslated pages and an interface in twelve languages.
  - [Editing with clay edit](https://clay-doc.github.io/clay-example-repo/4.x/organizing/clay-edit.md): Create, edit, order, rename, move and delete pages and folders, translate them and edit the settings - in an editor in the terminal, or one command at a time for scripts and AI agents.
  - [Redirects](https://clay-doc.github.io/clay-example-repo/4.x/organizing/redirects.md): Keep old addresses working when a page moves or gets a new name, for bookmarks, search engines and links from other sites.

## Features

- [Features](https://clay-doc.github.io/clay-example-repo/4.x/features.md): What every Clay site comes with - docs for AI assistants and agents, search, page details, themes and icons, and search engine optimization.
  - [AI & Agents](https://clay-doc.github.io/clay-example-repo/4.x/features/ai-and-agents.md): Every Clay site is ready for language models - each page as Markdown, an llms.txt index - and clay edit and clay check let AI agents change and check the docs.
  - [Search](https://clay-doc.github.io/clay-example-repo/4.x/features/search.md): Full-text search over every page and section, with typo tolerance, highlighted matches and keyboard shortcuts.
  - [SEO](https://clay-doc.github.io/clay-example-repo/4.x/features/seo.md): Titles, descriptions, canonical URLs, Open Graph tags, structured data and a sitemap that Clay creates for search engines.
  - [Page Details](https://clay-doc.github.io/clay-example-repo/4.x/features/page-details.md): The table of contents, last-updated dates, edit links and previous/next links around each page.
  - [Themes & Icons](https://clay-doc.github.io/clay-example-repo/4.x/features/themes-and-icons.md): Light and dark mode, your own colors and fonts, and how to use Font Awesome icons and kits in Clay.
  - [Analytics](https://clay-doc.github.io/clay-example-repo/4.x/features/analytics.md): Count page views and learn what readers search for in vain, with services that set no cookies.

## Configuration

- [Configuration](https://clay-doc.github.io/clay-example-repo/4.x/configuration.md): Reference of clay.yaml, of the front matter of pages and folders, and of the environment variables.
  - [clay.yaml](https://clay-doc.github.io/clay-example-repo/4.x/configuration/clay-yaml.md): Reference of every setting in clay.yaml, with defaults and a complete example.
  - [Front Matter](https://clay-doc.github.io/clay-example-repo/4.x/configuration/front-matter.md): Reference of every front matter field of pages, folders (index.md) and the start page, with defaults and examples.
  - [Environment Variables](https://clay-doc.github.io/clay-example-repo/4.x/configuration/environment-variables.md): Override settings from clay.yaml at build time, for example in CI or for a staging site.

## Publishing

- [Publishing](https://clay-doc.github.io/clay-example-repo/4.x/publishing.md): The clay commands, the checks every build runs, and how to put the site online on GitHub Pages or any other host.
  - [Commands](https://clay-doc.github.io/clay-example-repo/4.x/publishing/commands.md): Every clay command and option, from the live preview to building, previewing, editing and saving versions.
  - [Build Checks](https://clay-doc.github.io/clay-example-repo/4.x/publishing/build-checks.md): The problems clay build reports, how --strict turns them into errors, and what to do when a build fails.
  - [GitHub Pages](https://clay-doc.github.io/clay-example-repo/4.x/publishing/github-pages.md): Publish a Clay site on GitHub Pages with a workflow that checks and deploys the docs on every push.
  - [Other Hosts](https://clay-doc.github.io/clay-example-repo/4.x/publishing/other-hosts.md): Deploy a Clay site to Netlify, Cloudflare Pages, GitLab Pages or your own web server.
  - [CLI Reference](https://clay-doc.github.io/clay-example-repo/4.x/publishing/cli-reference.md): Every command and option of clay, as its help lists them.

## Guides

- [Guides](https://clay-doc.github.io/clay-example-repo/4.x/guides.md): Upgrading from earlier versions of Clay, and solutions for common problems.
  - [Upgrading to Clay 4](https://clay-doc.github.io/clay-example-repo/4.x/guides/upgrading-to-clay-4.md): Move a Clay 3 site to Clay 4 - the cards front matter field is now called list, files starting with _ are snippets, and older versions move into docs/.
  - [Upgrading to Clay 3](https://clay-doc.github.io/clay-example-repo/4.x/guides/upgrading-to-clay-3.md): Move a Clay 2 site to Clay 3 - index.md files instead of dir-meta.yaml, the start page in docs/index.md and older versions in docs-archive/.
  - [Upgrading to Clay 2](https://clay-doc.github.io/clay-example-repo/4.x/guides/upgrading-to-clay-2.md): Move a Clay 1 site built with Clay Oven to Clay 2 - one npm package instead of the frontend and Clay Oven.
  - [Troubleshooting](https://clay-doc.github.io/clay-example-repo/4.x/guides/troubleshooting.md): Solutions for the most common problems with Clay sites, from missing styles to missing dates.

## Optional

- [All pages in one file](https://clay-doc.github.io/clay-example-repo/4.x/llms-full.txt)
- [English](https://clay-doc.github.io/clay-example-repo/llms.txt)
- [Deutsch](https://clay-doc.github.io/clay-example-repo/de/llms.txt)
- [version 4.x, Deutsch](https://clay-doc.github.io/clay-example-repo/4.x/de/llms.txt)
- [version 3.x, English](https://clay-doc.github.io/clay-example-repo/3.x/llms.txt)
- [version 3.x, Deutsch](https://clay-doc.github.io/clay-example-repo/3.x/de/llms.txt)