Skip to content
logoClay
These are the docs for Clay 4.x. Go to the latest version (5.x)
On this page

Organizing

Clay builds the navigation from your files: every folder in docs/ is a section, every Markdown file a page. You decide titles, icons and order in front matter, or let clay edit do it for you. Older releases and other languages are folders and files too.

NavigationHow Clay builds the sidebar, breadcrumbs and previous/next links, and how to put pages in order.FoldersGroup pages into folders, and give folders a title, an icon, an order and a page of their own with index.md.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.VersionsKeep the docs of older releases online, with a version switcher and a banner that leads to the latest docs.TranslationsTranslate your docs page by page, with a language switcher, fallbacks for untranslated pages and an interface in twelve languages.Editing with clay editCreate, 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.RedirectsKeep old addresses working when a page moves or gets a new name, for bookmarks, search engines and links from other sites.

#From files to navigation

  • docs
    • index.mdthe start page
    • introduction.mdorder: 1
    • guides
      • index.mdtitle: Guides, order: 2
      • setup.md
      • deploying.md
    • reference
      • api.md

#One project, many editions

Versions and languages multiply the same structure. Each edition gets its own address, navigation and search:

  • my-project
    • docs
      • latestlatest, English: /
        • setup.md
        • setup.de.mdlatest, German: /de/setup
      • 1.xversion 1.x: /1.x
        • setup.md

Readers switch versions and languages in the navbar and stay on the page they are reading.

#Key ideas

  • The file tree is the navigation. Move a file, and it moves in the sidebar.
  • order puts entries in order. Entries without it follow alphabetically.
  • A folder’s index.md describes the folder. Its front matter names it; its text, if any, is the folder’s page.
  • The latest version is docs/, or docs/latest/ once there are versions. Older ones are copies next to it, like docs/1.x/.
  • Translate as much as you like. Pages without a translation show the original, with a note.

Tip

npx clay edit does all of this in the terminal: create, order, rename, move and translate pages, without writing front matter by hand. See clay edit.

Type to search all pages.