mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-12 16:47:26 +02:00
16 lines
No EOL
11 KiB
HTML
16 lines
No EOL
11 KiB
HTML
<html><head><meta charset="utf-8"/><meta http-equiv="X-UA-Compatible" content="IE=edge, chrome=1"/><title>Versioning · Docusaurus</title><meta name="viewport" content="width=device-width"/><meta property="og:title" content="Versioning · Docusaurus"/><meta property="og:type" content="website"/><meta property="og:url" content="https://docusaurus.io/index.html"/><meta property="og:description" content="Users can use the `version` script to cut a new documentation version based on the latest content in the `docs` folder. That specific set of documentation will then be preserved and accessible even as the documentation in the `docs` folder changes moving forward."/><meta name="robots" content="noindex"/><link rel="shortcut icon" href="/img/docusaurus.ico"/><link rel="stylesheet" href="/css/main.css"/><script async="" defer="" src="https://buttons.github.io/buttons.js"></script></head><body class="sideNavVisible"><div class="fixedHeaderContainer"><div class="headerWrapper wrapper"><header><a href="/"><img src="/img/docusaurus.svg"/><h2>Docusaurus</h2></a><div class="navigationWrapper navigationSlider"><nav class="slidingNav"><ul class="nav-site nav-site-internal"><li><a href="/docs/installation.html" target="_self">Docs</a></li><li><a href="/en/help.html" target="_self">Help</a></li><li><a href="https://github.com/facebookexperimental/docusaurus" target="_self">GitHub</a></li></ul></nav></div></header></div></div><div class="navPusher"><div class="docMainWrapper wrapper"><div class="container docsNavContainer" id="docsNav"><nav class="toc"><div class="toggleNav"><section class="navWrapper wrapper"><div class="navBreadcrumb wrapper"><div class="navToggle" id="navToggler"><i></i></div><h2><i>›</i><span>Guides</span></h2></div><div class="navGroups"><div class="navGroup navGroupActive"><h3>Getting Started</h3><ul><li class="navListItem"><a class="navItem" href="/docs/installation.html#content">Installation</a></li><li class="navListItem"><a class="navItem" href="/docs/site-preparation.html#content">Site Preparation</a></li><li class="navListItem"><a class="navItem" href="/docs/site-creation.html#content">Creating your site</a></li></ul></div><div class="navGroup navGroupActive"><h3>Guides</h3><ul><li class="navListItem"><a class="navItem" href="/docs/custom-pages.html#content">Custom Pages</a></li><li class="navListItem"><a class="navItem" href="/docs/navigation.html#content">Navigation and Sidebars</a></li><li class="navListItem"><a class="navItem" href="/docs/blog.html#content">Adding a Blog</a></li><li class="navListItem"><a class="navItem" href="/docs/translation.html#content">Translations</a></li><li class="navListItem"><a class="navItem" href="/docs/search.html#content">Enabling Search</a></li><li class="navListItem navListItemActive"><a class="navItem navItemActive" href="/docs/versioning.html#content">Versioning</a></li></ul></div><div class="navGroup navGroupActive"><h3>API</h3><ul><li class="navListItem"><a class="navItem" href="/docs/commands.html#content">CLI Commands</a></li><li class="navListItem"><a class="navItem" href="/docs/api-pages.html#content">Pages and Styles</a></li><li class="navListItem"><a class="navItem" href="/docs/site-config.html#content">siteConfig.js</a></li><li class="navListItem"><a class="navItem" href="/docs/doc-markdown.html#content">Markdown Features</a></li></ul></div></div></section></div><script>
|
||
var toggler = document.getElementById('navToggler');
|
||
var nav = document.getElementById('docsNav');
|
||
toggler.onclick = function() {
|
||
nav.classList.toggle('docsSliderActive');
|
||
};
|
||
</script></nav></div><div class="container mainContainer"><div class="wrapper"><div class="post"><header class="postHeader"><a class="edit-page-link button" href="https://github.com/facebookexperimental/docusaurus/edit/master/docs/guides-versioning.md" target="_blank">Edit this Doc</a><h1>Versioning</h1></header><article><div><p>Users can use the <code>version</code> script to cut a new documentation version based on the latest content in the <code>docs</code> folder. That specific set of documentation will then be preserved and accessible even as the documentation in the <code>docs</code> folder changes moving forward.</p><h2><a class="anchor" name="how-to-create-new-versions"></a>How to Create New Versions <a class="hash-link" href="#how-to-create-new-versions">#</a></h2><p>Add the following script to your <code>package.json</code> file:</p><pre class="prism language-json">...
|
||
<span class="token property">"scripts"</span><span class="token operator">:</span> <span class="token punctuation">{</span>
|
||
<span class="token property">"version"</span><span class="token operator">:</span> <span class="token string">"docusaurus-version"</span>
|
||
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
||
...</pre><p>Run the script with a command line argument of the version you wish to create. e.g.,</p><pre class="prism language-bash"><span class="token function">npm</span> run version 1.0.0</pre><p>This will preserve all documents currently in the <code>docs</code> folder and make them available as documentation for version <code>1.0.0</code>.</p><p>If, for example, you ran the version script with 1.0.0 as the version number, version 1.0.0 is considered the latest release version for your project, and the site will display the version number next to the title in the header.</p><p>Documents in the <code>docs</code> folder will be considered part of version <code>next</code> and they are available, for example, at the url <code>docs/next/doc1.html</code>. Documents from the latest version use the url <code>docs/doc1.html</code>.</p><p>Running the script again with <code>npm run version 2.0.0</code> will create a version <code>2.0.0</code>, making version 2.0.0 the most recent set of documentation. Documents from version <code>1.0.0</code> will use the url <code>docs/1.0.0/doc1.html</code> while <code>2.0.0</code> will use <code>docs/doc1.html</code>.</p><h2><a class="anchor" name="versioning-patterns"></a>Versioning Patterns <a class="hash-link" href="#versioning-patterns">#</a></h2><p>Users can create version numbers in whatever format they wish, and a new version can be created with any version number as long as it does not match an existing version. Version ordering is determined by the order in which versions are created, independently of how they are numbered.</p><h2><a class="anchor" name="storing-files-for-each-version"></a>Storing Files for Each Version <a class="hash-link" href="#storing-files-for-each-version">#</a></h2><p>Versioned documents are placed into <code>website/versioned_docs/version-${version}</code>, where <code>${version}</code> is the version number you supplied the <code>version</code> script. </p><p>The markdown header for each versioned doc is altered by appending <code>"version-${version}-"</code> to the id and by adding an <code>original_id</code> field.</p><p>Versioned sidebars are copied into <code>website/versioned_sidebars</code> and are named as <code>version-${version}-sidebar.json</code>. </p><p>A <code>website/versions.json</code> file is created the first time you cut a version and is used by Docusaurus to detect what versions exist. Each time a new version is added, it gets added to the <code>versions.json</code> file. </p><p>If you wish to change the documentation for a past version, you can access the files for that respective version. </p><h2><a class="anchor" name="fallback-functionality"></a>Fallback Functionality <a class="hash-link" href="#fallback-functionality">#</a></h2><p>Only files in the <code>docs</code> folder and sidebar files that differ from those of the latest version will get copied each time a new version is specified. If there is no change across versions, Docusaurus will use the file from the latest version with that file.</p><p>For example, a document with the original id <code>doc1</code> exists for the latest version, <code>1.0.0</code>, and has the same content as the document with the id <code>doc1</code> in the <code>docs</code> folder. When a new version <code>2.0.0</code> is created, the file for <code>doc1</code> will not be copied into <code>versioned_docs/version-2.0.0/</code>. There will still be a page for <code>docs/2.0.0/doc1.html</code>, but it will use the file from version <code>1.0.0</code>.</p><h2><a class="anchor" name="renaming-existing-versions"></a>Renaming Existing Versions <a class="hash-link" href="#renaming-existing-versions">#</a></h2><p>To rename an existing version number to something else, first make sure the following script is in your <code>package.json</code> file:</p><pre class="prism language-json">...
|
||
<span class="token property">"scripts"</span><span class="token operator">:</span> <span class="token punctuation">{</span>
|
||
<span class="token property">"rename-version"</span><span class="token operator">:</span> <span class="token string">"docusaurus-rename-version"</span>
|
||
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
||
...</pre><p>Run the script with command line arguments of first, the current version name, then second, the new version name. e.g.,</p><pre class="prism language-bash"><span class="token function">npm</span> run rename-version 1.0.0 1.0.1</pre><h2><a class="anchor" name="versioning-and-translations"></a>Versioning and Translations <a class="hash-link" href="#versioning-and-translations">#</a></h2><p>If you wish to use versioning and translations features, the <code>crowdin.yaml</code> file should be set up to upload and download versioned documents to and from Crowdin for translation. Translated, versioned files will go into the folder <code>translated_docs/${language}/version-${version}/</code>. For more information, check out the <a href="translation.md" target="_blank">translations guide</a>.</p></div></article></div><div class="docs-prevnext"><a class="docs-prev button" href="search.html#content">← Previous</a><a class="docs-next button" href="commands.html#content">Next →</a></div></div></div></div><footer class="nav-footer" id="footer"><section class="sitemap"><a href="/" class="nav-home"><img src="/img/docusaurus_monochrome.svg" alt="Docusaurus" width="66" height="58"/></a><div><h5>Docs</h5><a href="
|
||
/docs/installation.html">Getting Started</a></div><div><h5>Community</h5><a href="/en/users.html">User Showcase</a></div><div><h5>More</h5><a href="https://github.com/facebookexperimental/docusaurus">GitHub</a><a class="github-button" href="https://github.com/facebookexperimental/docusaurus" data-icon="octicon-star" data-count-href="/facebookexperimental/docusaurus/stargazers" data-count-api="/repos/facebookexperimental/docusaurus#stargazers_count" data-count-aria-label="# stargazers on GitHub" aria-label="Star this project on GitHub">Star</a></div></section><a href="https://code.facebook.com/projects/" target="_blank" class="fbOpenSource"><img src="/img/oss_logo.png" alt="Facebook Open Source" width="170" height="45"/></a><section class="copyright">Copyright © 2017 Facebook Inc.</section></footer></div></body></html> |