On this page

Quick Start

From an empty folder to a finished documentation site in about five minutes.

Create the project.

mkdir my-docs && cd my-docs
npm init -y
npm install --save-dev clay-doc

Configure the site. Create clay.yaml in the project folder. Only the title is required:
clay.yaml
```
title: "My Project"
```
Write the first page. Create docs/introduction.md:
docs/introduction.md
```
---
title: Introduction
icon: fa-solid fa-door-open
---

# Introduction

Welcome to **My Project**. This is the first page of its documentation.
```
The part between the --- lines is front matter. It is optional; without it, Clay takes the title from the first heading. See pages.
Preview while you write.
```
npx clay dev
```
Open http://localhost:3000 and click your page. Edit the Markdown file and save: the browser shows your change right away.
Add a section. Pages in a folder become a section of the navigation. Create docs/guides/setup.md:
docs/guides/setup.md
```
# Setup

How to set up My Project.
```
The sidebar now shows Guides. To give the folder another title, an icon and a page of its own, add docs/guides/index.md:
docs/guides/index.md
```
---
title: User Guides
icon: fa-solid fa-book
list: true
---

# User Guides

Everything you need to use My Project, step by step.
```
See index pages.
Build the site.
```
npx clay build
```
Clay checks your docs, renders every page and writes a static site to publish/public. Check it the way a web host would serve it with npx clay preview.

Your project now looks like this:

my-docs
- clay.yaml
- docs
  - introduction.md
  - guides
    index.md
    setup.md
- node_modules
- package.json
- publishthe built site, ready to upload

Note

Add publish/ and node_modules/ to your .gitignore. The build output is created fresh on every build and does not belong in the repository.

#Coming from another tool

Docs written for MkDocs, Docusaurus, VitePress or another tool are Markdown too. A coding agent can move them to Clay:

Suggested prompt

Read https://clay-doc.github.io/clay-example-repo/llms-full.txt to learn how Clay
works. Then move the documentation in this repository to Clay: its settings to
clay.yaml, its navigation to folders, index.md files and `order`, and the old
tool's own syntax, like admonitions and tabs, to Clay Flavored Markdown.
Remove the old tool's files once `npx clay build --strict` passes.

#Where to go from here

GitHub PagesPublish a Clay site on GitHub Pages with a workflow that checks and deploys the docs on every push.Index PagesThe start page and the page of every folder are Markdown files named index.md, with an optional list of pages and a large header.NavigationHow Clay builds the sidebar, breadcrumbs and previous/next links, and how to put pages in order.ComponentsTabs, steps, cards, folded sections, prompts, badges, math, diagrams and file trees, written in plain Markdown.