# 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 3.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/3.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/3.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.

## Pages

- [Introduction](https://clay-doc.github.io/clay-example-repo/3.x/introduction.md): What Clay is, what it does for you and how a Clay site comes together.

## Getting Started

- [Getting Started](https://clay-doc.github.io/clay-example-repo/3.x/getting-started.md): Install Clay, build a first site in five minutes and learn which file does what.
  - [Installation](https://clay-doc.github.io/clay-example-repo/3.x/getting-started/installation.md): Install Clay into a project with npm, or try it without installing anything.
  - [Quick Start](https://clay-doc.github.io/clay-example-repo/3.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/3.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/3.x/writing.md): Everything about the content of a page: Markdown, code blocks, alerts, links, images and HTML.
  - [Pages](https://clay-doc.github.io/clay-example-repo/3.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/3.x/writing/markdown.md): The Markdown syntax Clay supports, from headings and lists to tables and task lists, with examples.
  - [Code Blocks](https://clay-doc.github.io/clay-example-repo/3.x/writing/code-blocks.md): Syntax highlighting for over 200 languages, highlighted lines, diffs, focus and a copy button.
  - [Alerts](https://clay-doc.github.io/clay-example-repo/3.x/writing/alerts.md): Six kinds of callouts for notes, tips and warnings, written with GitHub's alert syntax.
  - [Links & Images](https://clay-doc.github.io/clay-example-repo/3.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/3.x/writing/html.md): Using HTML inside Markdown, and what Clay removes to keep your site safe.

## Organizing

- [Organizing](https://clay-doc.github.io/clay-example-repo/3.x/organizing.md): How pages and folders become navigation, how folders get their pages, and how clay edit keeps it all in order.
  - [Navigation](https://clay-doc.github.io/clay-example-repo/3.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/3.x/organizing/folders.md): Group pages into folders, and give folders a name, an icon, an order and a page of their own with index.md.
  - [Index Pages](https://clay-doc.github.io/clay-example-repo/3.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.
  - [Editing with clay edit](https://clay-doc.github.io/clay-example-repo/3.x/organizing/clay-edit.md): Create, edit, order, rename, move and delete pages and folders, translate them and edit the settings, for every version and language.

## Configuration

- [Configuration](https://clay-doc.github.io/clay-example-repo/3.x/configuration.md): Reference of clay.yaml, of the front matter of pages and folders, and of the environment variables that override settings at build time.
  - [clay.yaml](https://clay-doc.github.io/clay-example-repo/3.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/3.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/3.x/configuration/environment-variables.md): Override settings from clay.yaml at build time, for example in CI or for a staging site.

## Features

- [Features](https://clay-doc.github.io/clay-example-repo/3.x/features.md): What every Clay site comes with: search, search engine optimization, page details like the table of contents, and themes and icons.
  - [Search](https://clay-doc.github.io/clay-example-repo/3.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/3.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/3.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/3.x/features/themes-and-icons.md): Light and dark mode, and how to use Font Awesome icons and kits in Clay.

## Versions & Languages

- [Versions & Languages](https://clay-doc.github.io/clay-example-repo/3.x/versions-and-languages.md): Keep the docs of older releases online, and translate your docs page by page.
  - [Versions](https://clay-doc.github.io/clay-example-repo/3.x/versions-and-languages/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/3.x/versions-and-languages/translations.md): Translate your docs page by page, with a language switcher, fallbacks for untranslated pages and an interface in twelve languages.

## Command Line

- [Command Line](https://clay-doc.github.io/clay-example-repo/3.x/cli.md): The clay command: its subcommands and options, and the checks every build runs.
  - [Commands](https://clay-doc.github.io/clay-example-repo/3.x/cli/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/3.x/cli/build-checks.md): The problems clay build reports, how --strict turns them into errors, and what to do when a build fails.

## Deployment

- [Deployment](https://clay-doc.github.io/clay-example-repo/3.x/deployment.md): A Clay build is a folder of static files. Publish it on GitHub Pages with a ready-made workflow, or on any other host.
  - [GitHub Pages](https://clay-doc.github.io/clay-example-repo/3.x/deployment/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/3.x/deployment/other-hosts.md): Deploy a Clay site to Netlify, Cloudflare Pages, GitLab Pages or your own web server.

## Guides

- [Guides](https://clay-doc.github.io/clay-example-repo/3.x/guides.md): Upgrading from earlier versions of Clay, and solutions for common problems.
  - [Upgrading to Clay 3](https://clay-doc.github.io/clay-example-repo/3.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/.
  - [Migrating from Clay 1](https://clay-doc.github.io/clay-example-repo/3.x/guides/migrating-from-clay-1.md): Move a Clay 1 site built with Clay Oven to Clay 2, step by step.
  - [Troubleshooting](https://clay-doc.github.io/clay-example-repo/3.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/3.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, English](https://clay-doc.github.io/clay-example-repo/4.x/llms.txt)
- [version 4.x, Deutsch](https://clay-doc.github.io/clay-example-repo/4.x/de/llms.txt)
- [version 3.x, Deutsch](https://clay-doc.github.io/clay-example-repo/3.x/de/llms.txt)