Skip to content
logoClay
On this page

Writing

Every page is a Markdown file in docs/, written in Clay Flavored Markdown (CFM): the Markdown you know from GitHub, plus syntax highlighting, alerts and components. Clay checks your links on every build.

PagesHow Markdown files become pages, how pages get their titles and which front matter fields Clay reads.MarkdownClay Flavored Markdown - GitHub's Markdown plus alerts, components, math and diagrams - from headings and lists to tables and task lists, with examples.Code BlocksSyntax highlighting for over 200 languages, file names, terminals, highlighted lines, diffs, focus and a copy button.AlertsSix kinds of callouts for notes, tips and warnings, written with GitHub's alert syntax.ComponentsTabs, steps, cards, folded sections, prompts, badges, math, diagrams and file trees, written in plain Markdown.Links & ImagesLinking between pages like on GitHub, linking to sections, adding images and offering downloads.HTMLUsing HTML inside Markdown, videos and embeds, and what Clay removes to keep your site safe.Snippets & VariablesWrite a text once and use it on many pages, include code from your project, and fill in values like the current version.Generated DocsAPI reference from your code, and other pages that tools write, generated before every build.

#A page at a glance

One file, from front matter to components:

Setup is the page’s title in the sidebar; its text starts like this:

Tip

Already installed? Skip to the configuration.

npm install --save-dev clay-doc

#What to use when

You want to … Use
Show a command or a file a code block, with its file name, highlighted lines or a diff
Show the same thing for npm, pnpm and yarn, or for each system tabs or a code group
Walk readers through something in order steps
Point out a tip, a warning or a risk an alert
Hide what only some readers need details
Lead readers to other pages cards or links
Explain how parts fit together a diagram or a file tree
Suggest what to ask an AI assistant or agent a prompt
Mark something as new or deprecated a badge

#Key ideas

  • One file, one page. docs/guides/setup.md becomes /guides/setup.
  • Links work like on GitHub. Link to the .md file; Clay turns it into the page’s URL and reports links that lead nowhere.
  • Files next to your pages are published. Images and downloads in docs/ keep their relative paths.
  • Plain text stays plain. Components are written as text too, so every page reads well in an editor and on GitHub.

Type to search all pages.