[{"data":1,"prerenderedAt":26},["ShallowReactive",2],{"clay-page:\u002F3.x\u002Fversions-and-languages\u002Fversions":3},{"html":4,"toc":5,"description":22,"hero":23,"list":24,"socialImage":25},"\u003Ch1 id=\"versions\">Versions\u003C\u002Fh1>\n\u003Cp>When a release changes how your project works, readers of older releases still need the old docs. Clay keeps older versions of the docs online next to the current ones, each with its own navigation, search and URLs.\u003C\u002Fp>\n\u003Ch2 id=\"how-versions-work\">\u003Ca class=\"heading-anchor\" href=\"#how-versions-work\" aria-label=\"Link to this section\" data-route=\"#how-versions-work\">#\u003C\u002Fa>How versions work\u003C\u002Fh2>\n\u003Cul>\n\u003Cli>\u003Ccode>docs\u002F\u003C\u002Fcode> is always the \u003Cstrong>latest\u003C\u002Fstrong> version. It lives at the root of the site: \u003Ccode>\u002Fguides\u002Fsetup\u003C\u002Fcode>.\u003C\u002Fli>\n\u003Cli>Each folder in \u003Ccode>docs-archive\u002F\u003C\u002Fcode> is an \u003Cstrong>older\u003C\u002Fstrong> version, a copy of \u003Ccode>docs\u002F\u003C\u002Fcode> saved when that version was current. \u003Ccode>docs-archive\u002F1.x\u002F\u003C\u002Fcode> lives under \u003Ccode>\u002F1.x\u003C\u002Fcode>: \u003Ccode>\u002F1.x\u002Fguides\u002Fsetup\u003C\u002Fcode>.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cdiv class=\"code-block\">\u003Cpre class=\"shiki shiki-themes light-plus dark-plus\" style=\"--shiki-light:#000000;--shiki-dark:#D4D4D4;--shiki-light-bg:#FFFFFF;--shiki-dark-bg:#1E1E1E\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan>my-project\u002F\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan>├── clay.yaml\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan>├── docs\u002F                 # latest, at \u002F\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan>└── docs-archive\u002F\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan>    ├── 2.x\u002F              # at \u002F2.x\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan>    │   ├── index.md\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan>    │   └── guides\u002F\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan>    └── 1.x\u002F              # at \u002F1.x\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>\u003Cbutton type=\"button\" class=\"copy-code btn btn-sm btn-square btn-ghost\" title=\"Copy code\" aria-label=\"Copy code\">\u003Ci class=\"fa-solid fa-copy\">\u003C\u002Fi>\u003C\u002Fbutton>\u003C\u002Fdiv>\n\u003Cp>Most projects never need versions: without \u003Ccode>docs-archive\u002F\u003C\u002Fcode>, Clay shows no version switcher at all.\u003C\u002Fp>\n\u003Ch2 id=\"saving-a-version\">\u003Ca class=\"heading-anchor\" href=\"#saving-a-version\" aria-label=\"Link to this section\" data-route=\"#saving-a-version\">#\u003C\u002Fa>Saving a version\u003C\u002Fh2>\n\u003Cp>Right before a release changes the docs, save the current state:\u003C\u002Fp>\n\u003Cdiv class=\"code-block is-terminal has-bar\">\u003Cdiv class=\"code-terminal\" aria-hidden=\"true\">\u003Cspan>\u003C\u002Fspan>\u003Cspan>\u003C\u002Fspan>\u003Cspan>\u003C\u002Fspan>\u003C\u002Fdiv>\u003Cpre class=\"shiki shiki-themes light-plus dark-plus\" style=\"--shiki-light:#000000;--shiki-dark:#D4D4D4;--shiki-light-bg:#FFFFFF;--shiki-dark-bg:#1E1E1E\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line command\">\u003Cspan style=\"--shiki-light:#695221;--shiki-dark:#DCDCAA\">npx\u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#A31515;--shiki-dark:#CE9178\"> clay\u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#A31515;--shiki-dark:#CE9178\"> version\u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#A31515;--shiki-dark:#CE9178\"> 2.x\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>\u003Cbutton type=\"button\" class=\"copy-code btn btn-sm btn-square btn-ghost\" title=\"Copy code\" aria-label=\"Copy code\">\u003Ci class=\"fa-solid fa-copy\">\u003C\u002Fi>\u003C\u002Fbutton>\u003C\u002Fdiv>\n\u003Cp>This copies \u003Ccode>docs\u002F\u003C\u002Fcode> into \u003Ccode>docs-archive\u002F2.x\u002F\u003C\u002Fcode>. In \u003Ccode>clay edit\u003C\u002Fcode>, \u003Ckbd>V\u003C\u002Fkbd> does the same and switches the editor to the new version. Then update \u003Ccode>docs\u002F\u003C\u002Fcode> for the new release, and give it a label in \u003Ccode>clay.yaml\u003C\u002Fcode>:\u003C\u002Fp>\n\u003Cdiv class=\"code-block\">\u003Cpre class=\"shiki shiki-themes light-plus dark-plus\" style=\"--shiki-light:#000000;--shiki-dark:#D4D4D4;--shiki-light-bg:#FFFFFF;--shiki-dark-bg:#1E1E1E\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"--shiki-light:#800000;--shiki-dark:#569CD6\">version\u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#000000;--shiki-dark:#D4D4D4\">: \u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#A31515;--shiki-dark:#CE9178\">\"3.x\"\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>\u003Cbutton type=\"button\" class=\"copy-code btn btn-sm btn-square btn-ghost\" title=\"Copy code\" aria-label=\"Copy code\">\u003Ci class=\"fa-solid fa-copy\">\u003C\u002Fi>\u003C\u002Fbutton>\u003C\u002Fdiv>\n\u003Cp>Without \u003Ccode>version\u003C\u002Fcode>, the switcher calls the latest docs “Latest”.\u003C\u002Fp>\n\u003Cdiv class=\"markdown-alert markdown-alert-tip\">\n\u003Cp class=\"markdown-alert-title text-primary\">\u003Ci class=\"fa-solid fa-lightbulb mr-2\">\u003C\u002Fi>Tip\u003C\u002Fp>\n\u003Cp>A typical release flow: \u003Ccode>npx clay version 2.x\u003C\u002Fcode>, commit, set \u003Ccode>version: \"3.x\"\u003C\u002Fcode>, update the docs, release. The old docs are online at \u003Ccode>\u002F2.x\u003C\u002Fcode> from the first build.\u003C\u002Fp>\n\u003C\u002Fdiv>\n\u003Cp>Version names become part of URLs, so they may contain letters, digits, \u003Ccode>.\u003C\u002Fcode>, \u003Ccode>-\u003C\u002Fcode> and \u003Ccode>_\u003C\u002Fcode>. \u003Ccode>docs\u003C\u002Fcode>, \u003Ccode>api\u003C\u002Fcode>, \u003Ccode>_clay\u003C\u002Fcode> and \u003Ccode>_nuxt\u003C\u002Fcode> are reserved.\u003C\u002Fp>\n\u003Ch2 id=\"the-version-switcher\">\u003Ca class=\"heading-anchor\" href=\"#the-version-switcher\" aria-label=\"Link to this section\" data-route=\"#the-version-switcher\">#\u003C\u002Fa>The version switcher\u003C\u002Fh2>\n\u003Cp>As soon as there is a folder in \u003Ccode>docs-archive\u002F\u003C\u002Fcode>, the navbar shows a version switcher, newest first. Switching keeps the page you are reading when the other version has it, and otherwise opens that version’s start page. It keeps the \u003Ca href=\"\u002Fclay-example-repo\u002F3.x\u002Fversions-and-languages\u002Ftranslations\" data-route=\"\u002F3.x\u002Fversions-and-languages\u002Ftranslations\">language\u003C\u002Fa> too.\u003C\u002Fp>\n\u003Cp>Pages of older versions show a banner that says which version they belong to and links to the same page in the latest version.\u003C\u002Fp>\n\u003Ch2 id=\"what-each-version-has-of-its-own\">\u003Ca class=\"heading-anchor\" href=\"#what-each-version-has-of-its-own\" aria-label=\"Link to this section\" data-route=\"#what-each-version-has-of-its-own\">#\u003C\u002Fa>What each version has of its own\u003C\u002Fh2>\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>\u003C\u002Fth>\n\u003Cth>Per version\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd>Pages, images and files\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>docs-archive\u002F<name>\u002F\u003C\u002Fcode>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Start page, folder names, icons and order\u003C\u002Ftd>\n\u003Ctd>The version’s \u003Ccode>index.md\u003C\u002Fcode> files\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Search index\u003C\u002Ftd>\n\u003Ctd>Results stay within the version\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Edit links\u003C\u002Ftd>\n\u003Ctd>Lead into \u003Ccode>docs-archive\u002F<name>\u002F\u003C\u002Fcode>\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Translations\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>*.de.md\u003C\u002Fcode> files inside the version’s folder\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\u003C\u002Ftable>\n\u003Cp>\u003Ccode>clay.yaml\u003C\u002Fcode> is shared: all versions have the same title and navbar.\u003C\u002Fp>\n\u003Ch2 id=\"editing-older-versions\">\u003Ca class=\"heading-anchor\" href=\"#editing-older-versions\" aria-label=\"Link to this section\" data-route=\"#editing-older-versions\">#\u003C\u002Fa>Editing older versions\u003C\u002Fh2>\n\u003Cp>Older versions are plain files: fix a typo in \u003Ccode>docs-archive\u002F1.x\u002F\u003C\u002Fcode> like anywhere else, or switch \u003Ccode>clay edit\u003C\u002Fcode> to the version with \u003Ckbd>v\u003C\u002Fkbd>. Links inside an older version stay in that version, as long as they are relative: \u003Ccode>[Setup](setup.md)\u003C\u002Fcode> links to \u003Ccode>\u002F1.x\u002Fsetup\u003C\u002Fcode>. Links starting with \u003Ccode>\u002F\u003C\u002Fcode> lead to the latest version.\u003C\u002Fp>\n\u003Cdiv class=\"markdown-alert markdown-alert-note\">\n\u003Cp class=\"markdown-alert-title text-base-content\">\u003Ci class=\"fa-solid fa-sticky-note mr-2\">\u003C\u002Fi>Note\u003C\u002Fp>\n\u003Cp>Each saved version adds its pages to the build. Keep the versions your users actually run, and delete the folders of versions nobody uses anymore.\u003C\u002Fp>\n\u003C\u002Fdiv>\n",[6,10,13,16,19],{"id":7,"text":8,"level":9},"how-versions-work","How versions work",2,{"id":11,"text":12,"level":9},"saving-a-version","Saving a version",{"id":14,"text":15,"level":9},"the-version-switcher","The version switcher",{"id":17,"text":18,"level":9},"what-each-version-has-of-its-own","What each version has of its own",{"id":20,"text":21,"level":9},"editing-older-versions","Editing older versions","Keep the docs of older releases online, with a version switcher and a banner that leads to the latest docs.",null,false,"\u002F_clay\u002Fsocial\u002F3.x\u002Fversions-and-languages\u002Fversions.png",1792666368999]