mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-12 00:27:21 +02:00
Website Deployment Script
parent
daf63274f7
commit
5d4d0d0423
2334 changed files with 12240 additions and 12240 deletions
|
|
@ -71,7 +71,7 @@
|
|||
<p><img src="/img/slash-upandrunning.png" alt="Slash Up and Running"></p>
|
||||
<p>At its core, we wanted sites running Docusaurus to be simple to use. With one <a href="https://docusaurus.io/docs/en/installation.html">installation</a> command and some simple <a href="https://docusaurus.io/docs/en/site-preparation.html">configuration</a>, you can actually have a default running website.</p>
|
||||
<p>When you run <code>docusaurus-init</code>, you will see a structure similar to:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs-examples-from-docusaurus
|
||||
│ ├── doc1.md
|
||||
│ ├── doc2.md
|
||||
|
|
@ -94,7 +94,7 @@
|
|||
<p>With the exception of node_modules and package.json, all the directories and files you see are where you customize and add content to your Docusaurus-based website. The docs folder is where you add your markdown that represents your documentation; the blog folder is where you add your markdown for your <a href="https://docusaurus.io/docs/en/blog.html">blog posts</a>; <code>siteConfig.js</code> is where you make most of the <a href="https://docusaurus.io/docs/en/site-config.html">customizations</a> for your site; <code>sidebars.json</code> is where you maintain the layout and content of the <a href="https://docusaurus.io/docs/en/navigation.html">sidebar</a> for your documentation; the <code>pages</code> folder is where you add <a href="https://docusaurus.io/docs/en/custom-pages.html">custom</a> pages for your site; the <code>static</code> folder is where all of your static assets go (e.g., CSS stylesheets and images); and the <code>core</code> folder is where you can customize core components of the site, in this case the footer.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="how-does-docusaurus-work"></a><a href="#how-does-docusaurus-work" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>How does Docusaurus work?</h2>
|
||||
<p>Docusaurus is written primarily in JavaScript and <a href="https://facebook.github.io/react">React</a>, replacing Jekyll which we used in the old template. We use <a href="https://github.com/jonschlinkert/remarkable">Remarkable</a> for our markdown rendering and <a href="https://highlightjs.org/">highlight.js</a> for our code block syntax highlighting. The core of Docusaurus' functionality is in the <a href="https://github.com/facebookexperimental/Docusaurus/tree/master/lib">lib directory</a> of the <a href="https://github.com/facebook/Docusaurus/">Docusaurus repo</a>. The general structure looks like:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-Docusaurus
|
||||
<pre><code class="hljs css languages-bash">root-of-Docusaurus
|
||||
├── lib
|
||||
│ ├── core
|
||||
│ ├── server
|
||||
|
|
@ -127,7 +127,7 @@
|
|||
</ol>
|
||||
<p>Note that this process does not take into full account how translations or versioning works. The underlying details of those features will be saved for future blog posts.</p>
|
||||
<p>The final structure of your compiled site will look similar to:</p>
|
||||
<pre><code class="hljs css languages- bash">build
|
||||
<pre><code class="hljs css languages-bash">build
|
||||
├── website
|
||||
│ ├── CNAME
|
||||
│ ├── blog
|
||||
|
|
|
|||
|
|
@ -71,7 +71,7 @@
|
|||
<p><img src="/img/slash-upandrunning.png" alt="Slash Up and Running"></p>
|
||||
<p>At its core, we wanted sites running Docusaurus to be simple to use. With one <a href="https://docusaurus.io/docs/en/installation.html">installation</a> command and some simple <a href="https://docusaurus.io/docs/en/site-preparation.html">configuration</a>, you can actually have a default running website.</p>
|
||||
<p>When you run <code>docusaurus-init</code>, you will see a structure similar to:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs-examples-from-docusaurus
|
||||
│ ├── doc1.md
|
||||
│ ├── doc2.md
|
||||
|
|
@ -94,7 +94,7 @@
|
|||
<p>With the exception of node_modules and package.json, all the directories and files you see are where you customize and add content to your Docusaurus-based website. The docs folder is where you add your markdown that represents your documentation; the blog folder is where you add your markdown for your <a href="https://docusaurus.io/docs/en/blog.html">blog posts</a>; <code>siteConfig.js</code> is where you make most of the <a href="https://docusaurus.io/docs/en/site-config.html">customizations</a> for your site; <code>sidebars.json</code> is where you maintain the layout and content of the <a href="https://docusaurus.io/docs/en/navigation.html">sidebar</a> for your documentation; the <code>pages</code> folder is where you add <a href="https://docusaurus.io/docs/en/custom-pages.html">custom</a> pages for your site; the <code>static</code> folder is where all of your static assets go (e.g., CSS stylesheets and images); and the <code>core</code> folder is where you can customize core components of the site, in this case the footer.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="how-does-docusaurus-work"></a><a href="#how-does-docusaurus-work" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>How does Docusaurus work?</h2>
|
||||
<p>Docusaurus is written primarily in JavaScript and <a href="https://facebook.github.io/react">React</a>, replacing Jekyll which we used in the old template. We use <a href="https://github.com/jonschlinkert/remarkable">Remarkable</a> for our markdown rendering and <a href="https://highlightjs.org/">highlight.js</a> for our code block syntax highlighting. The core of Docusaurus' functionality is in the <a href="https://github.com/facebookexperimental/Docusaurus/tree/master/lib">lib directory</a> of the <a href="https://github.com/facebook/Docusaurus/">Docusaurus repo</a>. The general structure looks like:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-Docusaurus
|
||||
<pre><code class="hljs css languages-bash">root-of-Docusaurus
|
||||
├── lib
|
||||
│ ├── core
|
||||
│ ├── server
|
||||
|
|
@ -127,7 +127,7 @@
|
|||
</ol>
|
||||
<p>Note that this process does not take into full account how translations or versioning works. The underlying details of those features will be saved for future blog posts.</p>
|
||||
<p>The final structure of your compiled site will look similar to:</p>
|
||||
<pre><code class="hljs css languages- bash">build
|
||||
<pre><code class="hljs css languages-bash">build
|
||||
├── website
|
||||
│ ├── CNAME
|
||||
│ ├── blog
|
||||
|
|
|
|||
|
|
@ -59,7 +59,7 @@
|
|||
<h3><a class="anchor" aria-hidden="true" id="complibrarymarkdownblock"></a><a href="#complibrarymarkdownblock" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><code>CompLibrary.MarkdownBlock</code></h3>
|
||||
<p>A React component that parses markdown and renders to HTML.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token keyword">const</span> MarkdownBlock <span class="token operator">=</span> CompLibrary<span class="token punctuation">.</span>MarkdownBlock<span class="token punctuation">;</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token keyword">const</span> MarkdownBlock <span class="token operator">=</span> CompLibrary<span class="token punctuation">.</span>MarkdownBlock<span class="token punctuation">;</span>
|
||||
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>MarkdownBlock</span><span class="token punctuation">></span></span><span class="token punctuation">[</span>Markdown syntax <span class="token keyword">for</span> a link<span class="token punctuation">]</span><span class="token punctuation">(</span>http<span class="token punctuation">:</span><span class="token operator">/</span><span class="token operator">/</span>www<span class="token punctuation">.</span>example<span class="token punctuation">.</span>com<span class="token punctuation">)</span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>MarkdownBlock</span><span class="token punctuation">></span></span>
|
||||
</code></pre>
|
||||
|
|
@ -77,7 +77,7 @@
|
|||
</tbody>
|
||||
</table>
|
||||
<p><strong>Example</strong></p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>Container</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>Container</span>
|
||||
<span class="token attr-name">padding</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">[</span><span class="token string">'bottom'</span><span class="token punctuation">,</span> <span class="token string">'top'</span><span class="token punctuation">]</span><span class="token punctuation">}</span></span>
|
||||
<span class="token attr-name">background</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>light<span class="token punctuation">"</span></span>
|
||||
<span class="token attr-name">className</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>myCustomClass<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
|
|
@ -142,15 +142,15 @@
|
|||
<h2><a class="anchor" aria-hidden="true" id="translating-strings"></a><a href="#translating-strings" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Translating Strings</h2>
|
||||
<p>When translations are enabled, any pages inside <code>website/pages/en</code> will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the <code>languages.js</code> file. E.g. The url for a French page of <code>website/pages/en/help.js</code> would be found at <code>${baseUrl}fr/help.html</code>.</p>
|
||||
<p>When writing pages that you wish to translate, wrap any strings to be translated inside a <code><translate></code> tag. e.g.,</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span><span class="token punctuation">></span></span><span class="token constant">I</span> like translations<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>p</span><span class="token punctuation">></span></span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span><span class="token punctuation">></span></span><span class="token constant">I</span> like translations<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>p</span><span class="token punctuation">></span></span>
|
||||
</code></pre>
|
||||
<p>You can also provide an optional description attribute to provide context for translators. e.g,</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>a</span> <span class="token attr-name">href</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>/community<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>a</span> <span class="token attr-name">href</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>/community<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span> <span class="token attr-name">desc</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>Footer link to page referring to community GitHub and Slack<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Community<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>a</span><span class="token punctuation">></span></span>
|
||||
</code></pre>
|
||||
<p>Add the following require statement as well:</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> translate = <span class="hljs-built_in">require</span>(<span class="hljs-string">"../../server/translate.js"</span>).translate;
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> translate = <span class="hljs-built_in">require</span>(<span class="hljs-string">"../../server/translate.js"</span>).translate;
|
||||
</code></pre>
|
||||
<p>Note that this path is valid for files inside <code>pages/en</code> and should be adjusted accordingly if files are in different locations, as discussed <a href="#page-require-paths">above</a>.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="using-static-assets"></a><a href="#using-static-assets" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Using Static Assets</h2>
|
||||
|
|
|
|||
|
|
@ -59,7 +59,7 @@
|
|||
<h3><a class="anchor" aria-hidden="true" id="complibrarymarkdownblock"></a><a href="#complibrarymarkdownblock" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><code>CompLibrary.MarkdownBlock</code></h3>
|
||||
<p>A React component that parses markdown and renders to HTML.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token keyword">const</span> MarkdownBlock <span class="token operator">=</span> CompLibrary<span class="token punctuation">.</span>MarkdownBlock<span class="token punctuation">;</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token keyword">const</span> MarkdownBlock <span class="token operator">=</span> CompLibrary<span class="token punctuation">.</span>MarkdownBlock<span class="token punctuation">;</span>
|
||||
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>MarkdownBlock</span><span class="token punctuation">></span></span><span class="token punctuation">[</span>Markdown syntax <span class="token keyword">for</span> a link<span class="token punctuation">]</span><span class="token punctuation">(</span>http<span class="token punctuation">:</span><span class="token operator">/</span><span class="token operator">/</span>www<span class="token punctuation">.</span>example<span class="token punctuation">.</span>com<span class="token punctuation">)</span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>MarkdownBlock</span><span class="token punctuation">></span></span>
|
||||
</code></pre>
|
||||
|
|
@ -77,7 +77,7 @@
|
|||
</tbody>
|
||||
</table>
|
||||
<p><strong>Example</strong></p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>Container</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>Container</span>
|
||||
<span class="token attr-name">padding</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">[</span><span class="token string">'bottom'</span><span class="token punctuation">,</span> <span class="token string">'top'</span><span class="token punctuation">]</span><span class="token punctuation">}</span></span>
|
||||
<span class="token attr-name">background</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>light<span class="token punctuation">"</span></span>
|
||||
<span class="token attr-name">className</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>myCustomClass<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
|
|
@ -142,15 +142,15 @@
|
|||
<h2><a class="anchor" aria-hidden="true" id="translating-strings"></a><a href="#translating-strings" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Translating Strings</h2>
|
||||
<p>When translations are enabled, any pages inside <code>website/pages/en</code> will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the <code>languages.js</code> file. E.g. The url for a French page of <code>website/pages/en/help.js</code> would be found at <code>${baseUrl}fr/help.html</code>.</p>
|
||||
<p>When writing pages that you wish to translate, wrap any strings to be translated inside a <code><translate></code> tag. e.g.,</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span><span class="token punctuation">></span></span><span class="token constant">I</span> like translations<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>p</span><span class="token punctuation">></span></span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span><span class="token punctuation">></span></span><span class="token constant">I</span> like translations<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span><span class="token tag"><span class="token tag"><span class="token punctuation"></</span>p</span><span class="token punctuation">></span></span>
|
||||
</code></pre>
|
||||
<p>You can also provide an optional description attribute to provide context for translators. e.g,</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>a</span> <span class="token attr-name">href</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>/community<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>a</span> <span class="token attr-name">href</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>/community<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span> <span class="token attr-name">desc</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>Footer link to page referring to community GitHub and Slack<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Community<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>a</span><span class="token punctuation">></span></span>
|
||||
</code></pre>
|
||||
<p>Add the following require statement as well:</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> translate = <span class="hljs-built_in">require</span>(<span class="hljs-string">"../../server/translate.js"</span>).translate;
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> translate = <span class="hljs-built_in">require</span>(<span class="hljs-string">"../../server/translate.js"</span>).translate;
|
||||
</code></pre>
|
||||
<p>Note that this path is valid for files inside <code>pages/en</code> and should be adjusted accordingly if files are in different locations, as discussed <a href="#page-require-paths">above</a>.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="using-static-assets"></a><a href="#using-static-assets" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Using Static Assets</h2>
|
||||
|
|
|
|||
|
|
@ -100,7 +100,7 @@
|
|||
<li><code>USE_SSH</code>: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.</li>
|
||||
</ul>
|
||||
<p>e.g.,</p>
|
||||
<pre><code class="hljs css languages- bash">GIT_USER=docusaurus-bot USE_SSH=<span class="hljs-literal">true</span> yarn run publish-gh-pages
|
||||
<pre><code class="hljs css languages-bash">GIT_USER=docusaurus-bot USE_SSH=<span class="hljs-literal">true</span> yarn run publish-gh-pages
|
||||
</code></pre>
|
||||
<p>The following environment variables are <a href="https://circleci.com/docs/1.0/environment-variables/">set by CircleCI</a> during the build process.</p>
|
||||
<ul>
|
||||
|
|
|
|||
|
|
@ -100,7 +100,7 @@
|
|||
<li><code>USE_SSH</code>: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.</li>
|
||||
</ul>
|
||||
<p>e.g.,</p>
|
||||
<pre><code class="hljs css languages- bash">GIT_USER=docusaurus-bot USE_SSH=<span class="hljs-literal">true</span> yarn run publish-gh-pages
|
||||
<pre><code class="hljs css languages-bash">GIT_USER=docusaurus-bot USE_SSH=<span class="hljs-literal">true</span> yarn run publish-gh-pages
|
||||
</code></pre>
|
||||
<p>The following environment variables are <a href="https://circleci.com/docs/1.0/environment-variables/">set by CircleCI</a> during the build process.</p>
|
||||
<ul>
|
||||
|
|
|
|||
|
|
@ -53,7 +53,7 @@
|
|||
<p>You can <a href="/docs/en/1.0.11/site-preparation#verifying-installation">start</a> your local server and go to <code>http://localhost:3000</code> to see what the example home page looks like. From there, edit the <code>website/pages/en/index.js</code> file and its various components to use the images and text you want for your project.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="adding-other-custom-pages"></a><a href="#adding-other-custom-pages" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Adding Other Custom Pages</h2>
|
||||
<p>Docusaurus provides some simple example pages in the <code>website/pages/en</code> directory, including <code>index.js</code>, <code>users.js</code>, and <code>help.js</code>. These are good examples to showcase how to create a custom page for Docusaurus.</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs
|
||||
└── website
|
||||
│ └── blog
|
||||
|
|
@ -85,7 +85,7 @@
|
|||
<p>Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.</p>
|
||||
<p>Your footer will automatically get applied to all pages on your site, including docs and blog posts. The sole exception to this is any static html pages you include.</p>
|
||||
<p>If you do not want a footer for your site, change the <code>render</code> function of <code>core/Footer.js</code> to return <code>null</code>. e.g.,</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token keyword">const</span> React <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">"react"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token keyword">const</span> React <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">"react"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token keyword">class</span> <span class="token class-name">Footer</span> <span class="token keyword">extends</span> <span class="token class-name">React<span class="token punctuation">.</span>Component</span> <span class="token punctuation">{</span>
|
||||
<span class="token function">render</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
|
|
|
|||
|
|
@ -53,7 +53,7 @@
|
|||
<p>You can <a href="/docs/en/1.0.11/site-preparation#verifying-installation">start</a> your local server and go to <code>http://localhost:3000</code> to see what the example home page looks like. From there, edit the <code>website/pages/en/index.js</code> file and its various components to use the images and text you want for your project.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="adding-other-custom-pages"></a><a href="#adding-other-custom-pages" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Adding Other Custom Pages</h2>
|
||||
<p>Docusaurus provides some simple example pages in the <code>website/pages/en</code> directory, including <code>index.js</code>, <code>users.js</code>, and <code>help.js</code>. These are good examples to showcase how to create a custom page for Docusaurus.</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs
|
||||
└── website
|
||||
│ └── blog
|
||||
|
|
@ -85,7 +85,7 @@
|
|||
<p>Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.</p>
|
||||
<p>Your footer will automatically get applied to all pages on your site, including docs and blog posts. The sole exception to this is any static html pages you include.</p>
|
||||
<p>If you do not want a footer for your site, change the <code>render</code> function of <code>core/Footer.js</code> to return <code>null</code>. e.g.,</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token keyword">const</span> React <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">"react"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token keyword">const</span> React <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">"react"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token keyword">class</span> <span class="token class-name">Footer</span> <span class="token keyword">extends</span> <span class="token class-name">React<span class="token punctuation">.</span>Component</span> <span class="token punctuation">{</span>
|
||||
<span class="token function">render</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
|
|
|
|||
|
|
@ -55,7 +55,7 @@
|
|||
<p><code>hide_title</code>: Whether to hide the title at the top of the doc.</p>
|
||||
<p><code>sidebar_label</code>: The text shown in the document sidebar for this document. If this field is not present, the document's <code>sidebar_label</code> will default to its <code>title</code>.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
id: doc1
|
||||
title: My Document
|
||||
<span class="hljs-section">sidebar_label: Document
|
||||
|
|
@ -63,7 +63,7 @@ title: My Document
|
|||
</code></pre>
|
||||
<p>Versioned documents have their ids altered to include the version number when they get copied. The new <code>id</code> is <code>version-${version}-${id}</code> where <code>${version}</code> is the version number of that document and <code>${id}</code> is the original <code>id</code>. Additionally, versioned documents get an added <code>original_id</code> field with the original document id.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
id: version-1.0.0-doc1
|
||||
title: My Document
|
||||
sidebar_label: Document
|
||||
|
|
@ -72,7 +72,7 @@ sidebar_label: Document
|
|||
</code></pre>
|
||||
<p><code>custom_edit_url</code>: The url for editing this document. If this field is not present, the document's edit url will fallback to <code>editUrl</code> from optional fields of <code>siteConfig.js</code>. See <a href="site-config.md">siteConfig.js</a> docs for more information.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
id: doc-markdown
|
||||
title: Markdown Features
|
||||
<span class="hljs-section">custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
|
||||
|
|
@ -85,7 +85,7 @@ title: Markdown Features
|
|||
<p><code>authorURL</code>: A page to link to when a site user clicks the author's name. If this field is omitted, the author's name will not link to anything.</p>
|
||||
<p><code>authorFBID</code>: The author's Facebook id, used only to get the author's profile picture to display with the blog post. If this field is omitted, no author picture will be shown for the blog post.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
title: My First Blog Post
|
||||
author: Frank Li
|
||||
authorURL: http://twitter.com/franchementli
|
||||
|
|
@ -97,20 +97,20 @@ authorURL: http://twitter.com/franchementli
|
|||
<h3><a class="anchor" aria-hidden="true" id="linking-other-documents"></a><a href="#linking-other-documents" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Linking other Documents</h3>
|
||||
<p>You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- markdown">[<span class="hljs-string">This links to another document</span>](<span class="hljs-link">other-document.md</span>)
|
||||
<pre><code class="hljs css languages-markdown">[<span class="hljs-string">This links to another document</span>](<span class="hljs-link">other-document.md</span>)
|
||||
</code></pre>
|
||||
<p>This markdown will automatically get converted into a link to <code>/docs/other-document.html</code> (or the appropriately translated/versioned link) once it gets rendered.</p>
|
||||
<p>This can help when you want to navigate through docs on GitHub since the links there will be functional links to other documents (still on GitHub), but the documents will have the correct html links when they get rendered.</p>
|
||||
<h3><a class="anchor" aria-hidden="true" id="linking-to-images-and-other-assets"></a><a href="#linking-to-images-and-other-assets" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Linking to Images and Other Assets</h3>
|
||||
<p>Static assets can be linked to in the same way that documents are, using relative urls. Static assets used in documents and blogs should go into <code>docs/assets</code> and <code>website/blog/assets</code>, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- markdown">![<span class="hljs-string">alt-text</span>](<span class="hljs-link">/docs/assets/doc-image.png</span>)
|
||||
<pre><code class="hljs css languages-markdown">![<span class="hljs-string">alt-text</span>](<span class="hljs-link">/docs/assets/doc-image.png</span>)
|
||||
</code></pre>
|
||||
<h3><a class="anchor" aria-hidden="true" id="generating-table-of-contents"></a><a href="#generating-table-of-contents" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Generating Table of Contents</h3>
|
||||
<p>You can make an autogenerated list of links, which can be useful as a table of contents for API docs.</p>
|
||||
<p>In your markdown file, insert a line with the text <<code>AUTOGENERATED_TABLE_OF_CONTENTS</code>>. Write your documentation using <code>h3</code> headers for each function inside a code block. These will be found by Docusaurus and a list of links to these sections will inserted at the text <<code>AUTOGENERATED_TABLE_OF_CONTENTS</code>>.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- markdown"><span class="hljs-section">### `docusaurus.function(a, b)`</span>
|
||||
<pre><code class="hljs css languages-markdown"><span class="hljs-section">### `docusaurus.function(a, b)`</span>
|
||||
|
||||
Text describing my function
|
||||
|
||||
|
|
@ -120,7 +120,7 @@ Text describing my function
|
|||
Text describing my function
|
||||
</code></pre>
|
||||
<p>will lead to a table of contents of the functions:</p>
|
||||
<pre><code class="hljs css languages- markdown"><span class="hljs-bullet">- </span><span class="hljs-code">`docusaurus.function(a, b)`</span>
|
||||
<pre><code class="hljs css languages-markdown"><span class="hljs-bullet">- </span><span class="hljs-code">`docusaurus.function(a, b)`</span>
|
||||
<span class="hljs-bullet">- </span><span class="hljs-code">`docdoc(file)`</span>
|
||||
</code></pre>
|
||||
<p>and each function will link to their corresponding sections in the page.</p>
|
||||
|
|
@ -134,20 +134,20 @@ ReactDOM.render(
|
|||
```
|
||||
</code></pre>
|
||||
<p>...would be rendered with syntax highlighting like so:</p>
|
||||
<pre><code class="hljs css languages- javascript">ReactDOM.render(
|
||||
<pre><code class="hljs css languages-javascript">ReactDOM.render(
|
||||
<span class="xml"><span class="hljs-tag"><<span class="hljs-name">h1</span>></span>Hello, world!<span class="hljs-tag"></<span class="hljs-name">h1</span>></span></span>,
|
||||
<span class="hljs-built_in">document</span>.getElementById(<span class="hljs-string">'root'</span>)
|
||||
);
|
||||
</code></pre>
|
||||
<p>Highlighting is provided by <a href="https://highlightjs.org">Highlight.js</a> using the theme specified in your <code>siteConfig.js</code> file as part of the <code>highlight</code> key:</p>
|
||||
<pre><code class="hljs css languages- javascript">highlight: {
|
||||
<pre><code class="hljs css languages-javascript">highlight: {
|
||||
<span class="hljs-attr">theme</span>: <span class="hljs-string">'default'</span>
|
||||
}
|
||||
</code></pre>
|
||||
<p>You can find the full list of supported themes in the Highlight.js <a href="https://github.com/isagalaev/highlight.js/tree/master/src/styles"><code>styles</code></a> directory.</p>
|
||||
<h3><a class="anchor" aria-hidden="true" id="registering-additional-languages"></a><a href="#registering-additional-languages" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Registering additional languages</h3>
|
||||
<p>While Highlight.js provides support for <a href="https://highlightjs.org/static/demo/">many popular languages out of the box</a>, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the <code>hljs</code> constant as part of the <code>highlight</code> config key. This in turn allows you to call <a href="http://highlightjs.readthedocs.io/en/latest/api.html#registerlanguage-name-language"><code>registerLanguage</code></a>:</p>
|
||||
<pre><code class="hljs css languages- javascript">highlight: {
|
||||
<pre><code class="hljs css languages-javascript">highlight: {
|
||||
<span class="hljs-attr">theme</span>: <span class="hljs-string">'default'</span>,
|
||||
<span class="hljs-attr">hljs</span>: <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">hljs</span>) </span>{
|
||||
hljs.registerLanguage(<span class="hljs-string">'galacticbasic'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">hljs</span>) </span>{
|
||||
|
|
|
|||
|
|
@ -55,7 +55,7 @@
|
|||
<p><code>hide_title</code>: Whether to hide the title at the top of the doc.</p>
|
||||
<p><code>sidebar_label</code>: The text shown in the document sidebar for this document. If this field is not present, the document's <code>sidebar_label</code> will default to its <code>title</code>.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
id: doc1
|
||||
title: My Document
|
||||
<span class="hljs-section">sidebar_label: Document
|
||||
|
|
@ -63,7 +63,7 @@ title: My Document
|
|||
</code></pre>
|
||||
<p>Versioned documents have their ids altered to include the version number when they get copied. The new <code>id</code> is <code>version-${version}-${id}</code> where <code>${version}</code> is the version number of that document and <code>${id}</code> is the original <code>id</code>. Additionally, versioned documents get an added <code>original_id</code> field with the original document id.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
id: version-1.0.0-doc1
|
||||
title: My Document
|
||||
sidebar_label: Document
|
||||
|
|
@ -72,7 +72,7 @@ sidebar_label: Document
|
|||
</code></pre>
|
||||
<p><code>custom_edit_url</code>: The url for editing this document. If this field is not present, the document's edit url will fallback to <code>editUrl</code> from optional fields of <code>siteConfig.js</code>. See <a href="site-config.md">siteConfig.js</a> docs for more information.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
id: doc-markdown
|
||||
title: Markdown Features
|
||||
<span class="hljs-section">custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
|
||||
|
|
@ -85,7 +85,7 @@ title: Markdown Features
|
|||
<p><code>authorURL</code>: A page to link to when a site user clicks the author's name. If this field is omitted, the author's name will not link to anything.</p>
|
||||
<p><code>authorFBID</code>: The author's Facebook id, used only to get the author's profile picture to display with the blog post. If this field is omitted, no author picture will be shown for the blog post.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
title: My First Blog Post
|
||||
author: Frank Li
|
||||
authorURL: http://twitter.com/franchementli
|
||||
|
|
@ -97,20 +97,20 @@ authorURL: http://twitter.com/franchementli
|
|||
<h3><a class="anchor" aria-hidden="true" id="linking-other-documents"></a><a href="#linking-other-documents" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Linking other Documents</h3>
|
||||
<p>You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- markdown">[<span class="hljs-string">This links to another document</span>](<span class="hljs-link">other-document.md</span>)
|
||||
<pre><code class="hljs css languages-markdown">[<span class="hljs-string">This links to another document</span>](<span class="hljs-link">other-document.md</span>)
|
||||
</code></pre>
|
||||
<p>This markdown will automatically get converted into a link to <code>/docs/other-document.html</code> (or the appropriately translated/versioned link) once it gets rendered.</p>
|
||||
<p>This can help when you want to navigate through docs on GitHub since the links there will be functional links to other documents (still on GitHub), but the documents will have the correct html links when they get rendered.</p>
|
||||
<h3><a class="anchor" aria-hidden="true" id="linking-to-images-and-other-assets"></a><a href="#linking-to-images-and-other-assets" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Linking to Images and Other Assets</h3>
|
||||
<p>Static assets can be linked to in the same way that documents are, using relative urls. Static assets used in documents and blogs should go into <code>docs/assets</code> and <code>website/blog/assets</code>, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- markdown">![<span class="hljs-string">alt-text</span>](<span class="hljs-link">/docs/assets/doc-image.png</span>)
|
||||
<pre><code class="hljs css languages-markdown">![<span class="hljs-string">alt-text</span>](<span class="hljs-link">/docs/assets/doc-image.png</span>)
|
||||
</code></pre>
|
||||
<h3><a class="anchor" aria-hidden="true" id="generating-table-of-contents"></a><a href="#generating-table-of-contents" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Generating Table of Contents</h3>
|
||||
<p>You can make an autogenerated list of links, which can be useful as a table of contents for API docs.</p>
|
||||
<p>In your markdown file, insert a line with the text <<code>AUTOGENERATED_TABLE_OF_CONTENTS</code>>. Write your documentation using <code>h3</code> headers for each function inside a code block. These will be found by Docusaurus and a list of links to these sections will inserted at the text <<code>AUTOGENERATED_TABLE_OF_CONTENTS</code>>.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- markdown"><span class="hljs-section">### `docusaurus.function(a, b)`</span>
|
||||
<pre><code class="hljs css languages-markdown"><span class="hljs-section">### `docusaurus.function(a, b)`</span>
|
||||
|
||||
Text describing my function
|
||||
|
||||
|
|
@ -120,7 +120,7 @@ Text describing my function
|
|||
Text describing my function
|
||||
</code></pre>
|
||||
<p>will lead to a table of contents of the functions:</p>
|
||||
<pre><code class="hljs css languages- markdown"><span class="hljs-bullet">- </span><span class="hljs-code">`docusaurus.function(a, b)`</span>
|
||||
<pre><code class="hljs css languages-markdown"><span class="hljs-bullet">- </span><span class="hljs-code">`docusaurus.function(a, b)`</span>
|
||||
<span class="hljs-bullet">- </span><span class="hljs-code">`docdoc(file)`</span>
|
||||
</code></pre>
|
||||
<p>and each function will link to their corresponding sections in the page.</p>
|
||||
|
|
@ -134,20 +134,20 @@ ReactDOM.render(
|
|||
```
|
||||
</code></pre>
|
||||
<p>...would be rendered with syntax highlighting like so:</p>
|
||||
<pre><code class="hljs css languages- javascript">ReactDOM.render(
|
||||
<pre><code class="hljs css languages-javascript">ReactDOM.render(
|
||||
<span class="xml"><span class="hljs-tag"><<span class="hljs-name">h1</span>></span>Hello, world!<span class="hljs-tag"></<span class="hljs-name">h1</span>></span></span>,
|
||||
<span class="hljs-built_in">document</span>.getElementById(<span class="hljs-string">'root'</span>)
|
||||
);
|
||||
</code></pre>
|
||||
<p>Highlighting is provided by <a href="https://highlightjs.org">Highlight.js</a> using the theme specified in your <code>siteConfig.js</code> file as part of the <code>highlight</code> key:</p>
|
||||
<pre><code class="hljs css languages- javascript">highlight: {
|
||||
<pre><code class="hljs css languages-javascript">highlight: {
|
||||
<span class="hljs-attr">theme</span>: <span class="hljs-string">'default'</span>
|
||||
}
|
||||
</code></pre>
|
||||
<p>You can find the full list of supported themes in the Highlight.js <a href="https://github.com/isagalaev/highlight.js/tree/master/src/styles"><code>styles</code></a> directory.</p>
|
||||
<h3><a class="anchor" aria-hidden="true" id="registering-additional-languages"></a><a href="#registering-additional-languages" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Registering additional languages</h3>
|
||||
<p>While Highlight.js provides support for <a href="https://highlightjs.org/static/demo/">many popular languages out of the box</a>, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the <code>hljs</code> constant as part of the <code>highlight</code> config key. This in turn allows you to call <a href="http://highlightjs.readthedocs.io/en/latest/api.html#registerlanguage-name-language"><code>registerLanguage</code></a>:</p>
|
||||
<pre><code class="hljs css languages- javascript">highlight: {
|
||||
<pre><code class="hljs css languages-javascript">highlight: {
|
||||
<span class="hljs-attr">theme</span>: <span class="hljs-string">'default'</span>,
|
||||
<span class="hljs-attr">hljs</span>: <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">hljs</span>) </span>{
|
||||
hljs.registerLanguage(<span class="hljs-string">'galacticbasic'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">hljs</span>) </span>{
|
||||
|
|
|
|||
|
|
@ -61,7 +61,7 @@
|
|||
<p>After docusaurus is installed, moving forward, you can check your current version of Docusaurus by going into the <code>website</code> directory and typing <code>npm list docusaurus</code>. You can update to the <a href="https://www.npmjs.com/package/docusaurus">latest version</a> of Docusaurus by typing <code>npm update</code>.</p>
|
||||
</blockquote>
|
||||
<p>Along with previously existing files and directories, your root directory will now contain a structure similar to:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs-examples-from-docusaurus
|
||||
│ └── doc1.md
|
||||
│ └── doc2.md
|
||||
|
|
|
|||
|
|
@ -61,7 +61,7 @@
|
|||
<p>After docusaurus is installed, moving forward, you can check your current version of Docusaurus by going into the <code>website</code> directory and typing <code>npm list docusaurus</code>. You can update to the <a href="https://www.npmjs.com/package/docusaurus">latest version</a> of Docusaurus by typing <code>npm update</code>.</p>
|
||||
</blockquote>
|
||||
<p>Along with previously existing files and directories, your root directory will now contain a structure similar to:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs-examples-from-docusaurus
|
||||
│ └── doc1.md
|
||||
│ └── doc2.md
|
||||
|
|
|
|||
|
|
@ -87,7 +87,7 @@
|
|||
</ul>
|
||||
<p>Once you have the parameter value information, you can go ahead and run the publish script, ensuring you have inserted your own values inside the various parameter placeholders:</p>
|
||||
<p>To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate.</p>
|
||||
<pre><code class="hljs css languages- bash">GIT_USER=<GIT_USER> \
|
||||
<pre><code class="hljs css languages-bash">GIT_USER=<GIT_USER> \
|
||||
CURRENT_BRANCH=master \
|
||||
USE_SSH=<span class="hljs-literal">true</span> \
|
||||
yarn run publish-gh-pages <span class="hljs-comment"># or `npm run publish-gh-pages`</span>
|
||||
|
|
@ -111,7 +111,7 @@
|
|||
<li>Create a <code>.circleci</code> folder and create a <code>config.yml</code> under that folder.</li>
|
||||
<li>Copy the text below into <code>.circleci/config.yml</code>.</li>
|
||||
</ol>
|
||||
<pre><code class="hljs css languages- yml"><span class="hljs-comment"># If you only one circle to run on direct commits to master, you can uncomment this out</span>
|
||||
<pre><code class="hljs css languages-yml"><span class="hljs-comment"># If you only one circle to run on direct commits to master, you can uncomment this out</span>
|
||||
<span class="hljs-comment"># and uncomment the filters: *filter-only-master down below too</span>
|
||||
<span class="hljs-comment">#</span>
|
||||
<span class="hljs-comment"># aliases:</span>
|
||||
|
|
@ -158,7 +158,7 @@
|
|||
</blockquote>
|
||||
<h3><a class="anchor" aria-hidden="true" id="tips-tricks"></a><a href="#tips-tricks" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Tips & Tricks</h3>
|
||||
<p>When initially deploying to a <code>gh-pages</code> branch using Circle CI, you may notice that some jobs triggered by commits to the <code>gh-pages</code> branch fail to run successfully due to a lack of tests. You can easily work around this by creating a basic Circle CI config with the following contents:</p>
|
||||
<pre><code class="hljs css languages- yml"><span class="hljs-comment"># Circle CI 2.0 Config File</span>
|
||||
<pre><code class="hljs css languages-yml"><span class="hljs-comment"># Circle CI 2.0 Config File</span>
|
||||
<span class="hljs-comment"># This config file will prevent tests from being run on the gh-pages branch.</span>
|
||||
<span class="hljs-attr">version:</span> <span class="hljs-number">2</span>
|
||||
<span class="hljs-attr">jobs:</span>
|
||||
|
|
|
|||
|
|
@ -87,7 +87,7 @@
|
|||
</ul>
|
||||
<p>Once you have the parameter value information, you can go ahead and run the publish script, ensuring you have inserted your own values inside the various parameter placeholders:</p>
|
||||
<p>To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate.</p>
|
||||
<pre><code class="hljs css languages- bash">GIT_USER=<GIT_USER> \
|
||||
<pre><code class="hljs css languages-bash">GIT_USER=<GIT_USER> \
|
||||
CURRENT_BRANCH=master \
|
||||
USE_SSH=<span class="hljs-literal">true</span> \
|
||||
yarn run publish-gh-pages <span class="hljs-comment"># or `npm run publish-gh-pages`</span>
|
||||
|
|
@ -111,7 +111,7 @@
|
|||
<li>Create a <code>.circleci</code> folder and create a <code>config.yml</code> under that folder.</li>
|
||||
<li>Copy the text below into <code>.circleci/config.yml</code>.</li>
|
||||
</ol>
|
||||
<pre><code class="hljs css languages- yml"><span class="hljs-comment"># If you only one circle to run on direct commits to master, you can uncomment this out</span>
|
||||
<pre><code class="hljs css languages-yml"><span class="hljs-comment"># If you only one circle to run on direct commits to master, you can uncomment this out</span>
|
||||
<span class="hljs-comment"># and uncomment the filters: *filter-only-master down below too</span>
|
||||
<span class="hljs-comment">#</span>
|
||||
<span class="hljs-comment"># aliases:</span>
|
||||
|
|
@ -158,7 +158,7 @@
|
|||
</blockquote>
|
||||
<h3><a class="anchor" aria-hidden="true" id="tips-tricks"></a><a href="#tips-tricks" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Tips & Tricks</h3>
|
||||
<p>When initially deploying to a <code>gh-pages</code> branch using Circle CI, you may notice that some jobs triggered by commits to the <code>gh-pages</code> branch fail to run successfully due to a lack of tests. You can easily work around this by creating a basic Circle CI config with the following contents:</p>
|
||||
<pre><code class="hljs css languages- yml"><span class="hljs-comment"># Circle CI 2.0 Config File</span>
|
||||
<pre><code class="hljs css languages-yml"><span class="hljs-comment"># Circle CI 2.0 Config File</span>
|
||||
<span class="hljs-comment"># This config file will prevent tests from being run on the gh-pages branch.</span>
|
||||
<span class="hljs-attr">version:</span> <span class="hljs-number">2</span>
|
||||
<span class="hljs-attr">jobs:</span>
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@
|
|||
</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/facebook/docusaurus/edit/master/docs/guides-search.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 class="postHeaderTitle">Enabling Search</h1></header><article><div><span><p>Docusaurus supports search using <a href="https://community.algolia.com/docsearch/">Algolia DocSearch</a>. Once you have set up your site, <a href="https://community.algolia.com/docsearch/">enter your site information</a> to have Algolia crawl your website's documentation pages. Algolia will then send you an API key and index name for your site.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="enabling-the-search-bar"></a><a href="#enabling-the-search-bar" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Enabling the Search Bar</h2>
|
||||
<p>Enter your search-only API key and index name into <code>siteConfig.js</code> in the <code>algolia</code> section to enable search for your site.</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
...
|
||||
algolia: {
|
||||
<span class="hljs-attr">apiKey</span>: <span class="hljs-string">"my-search-only-api-key-1234"</span>,
|
||||
|
|
@ -61,7 +61,7 @@
|
|||
</code></pre>
|
||||
<h2><a class="anchor" aria-hidden="true" id="extra-search-options"></a><a href="#extra-search-options" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Extra Search Options</h2>
|
||||
<p>You can also specify extra <a href="https://community.algolia.com/docsearch/documentation/">search options used by Algolia</a> by using an <code>algoliaOptions</code> field in <code>algolia</code>. This may be useful if you want to provide different search results for the different versions or languages of your docs. Any occurrences of "VERSION" or "LANGUAGE" will be replaced by the version or language of the current page, respectively. More details about search options can be <a href="https://www.algolia.com/doc/api-reference/api-parameters/#overview">found here</a>.</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
...
|
||||
algolia: {
|
||||
...
|
||||
|
|
@ -75,7 +75,7 @@
|
|||
<h2><a class="anchor" aria-hidden="true" id="controlling-the-location-of-the-search-bar"></a><a href="#controlling-the-location-of-the-search-bar" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Controlling the Location of the Search Bar</h2>
|
||||
<p>By default, the search bar will be the rightmost element in the top navigation bar.</p>
|
||||
<p>If you want to change the default location, add the <code>searchBar</code> flag in the <code>headerLinks</code> field of <code>siteConfig.js</code> in your desired location. For example, you may want the search bar in between your internal and external links.</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
...
|
||||
headerLinks: [
|
||||
{...}
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@
|
|||
</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/facebook/docusaurus/edit/master/docs/guides-search.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 class="postHeaderTitle">Enabling Search</h1></header><article><div><span><p>Docusaurus supports search using <a href="https://community.algolia.com/docsearch/">Algolia DocSearch</a>. Once you have set up your site, <a href="https://community.algolia.com/docsearch/">enter your site information</a> to have Algolia crawl your website's documentation pages. Algolia will then send you an API key and index name for your site.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="enabling-the-search-bar"></a><a href="#enabling-the-search-bar" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Enabling the Search Bar</h2>
|
||||
<p>Enter your search-only API key and index name into <code>siteConfig.js</code> in the <code>algolia</code> section to enable search for your site.</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
...
|
||||
algolia: {
|
||||
<span class="hljs-attr">apiKey</span>: <span class="hljs-string">"my-search-only-api-key-1234"</span>,
|
||||
|
|
@ -61,7 +61,7 @@
|
|||
</code></pre>
|
||||
<h2><a class="anchor" aria-hidden="true" id="extra-search-options"></a><a href="#extra-search-options" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Extra Search Options</h2>
|
||||
<p>You can also specify extra <a href="https://community.algolia.com/docsearch/documentation/">search options used by Algolia</a> by using an <code>algoliaOptions</code> field in <code>algolia</code>. This may be useful if you want to provide different search results for the different versions or languages of your docs. Any occurrences of "VERSION" or "LANGUAGE" will be replaced by the version or language of the current page, respectively. More details about search options can be <a href="https://www.algolia.com/doc/api-reference/api-parameters/#overview">found here</a>.</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
...
|
||||
algolia: {
|
||||
...
|
||||
|
|
@ -75,7 +75,7 @@
|
|||
<h2><a class="anchor" aria-hidden="true" id="controlling-the-location-of-the-search-bar"></a><a href="#controlling-the-location-of-the-search-bar" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Controlling the Location of the Search Bar</h2>
|
||||
<p>By default, the search bar will be the rightmost element in the top navigation bar.</p>
|
||||
<p>If you want to change the default location, add the <code>searchBar</code> flag in the <code>headerLinks</code> field of <code>siteConfig.js</code> in your desired location. For example, you may want the search bar in between your internal and external links.</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
...
|
||||
headerLinks: [
|
||||
{...}
|
||||
|
|
|
|||
|
|
@ -66,7 +66,7 @@
|
|||
<p><code>headerIcon</code> - url for icon used in header navigation bar.</p>
|
||||
<p><code>headerLinks</code> - Links that will be used in the header navigation bar. The <code>label</code> field of each object will be the link text and will also be translated for each language.</p>
|
||||
<p>Example Usage:</p>
|
||||
<pre><code class="hljs css languages- js">headerLinks: [
|
||||
<pre><code class="hljs css languages-js">headerLinks: [
|
||||
<span class="hljs-comment">// Links to document with id doc1 for current language/version</span>
|
||||
{ <span class="hljs-attr">doc</span>: <span class="hljs-string">"doc1"</span>, <span class="hljs-attr">label</span>: <span class="hljs-string">"Getting Started"</span> },
|
||||
<span class="hljs-comment">// Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language</span>
|
||||
|
|
@ -97,9 +97,9 @@
|
|||
<p><code>blogSidebarCount</code> - Control the number of blog posts that show up in the sidebar. See the <a href="/docs/en/1.0.11/adding-blog#changing-how-many-blog-posts-show-on-sidebar">adding a blog docs</a> for more information.</p>
|
||||
<p><code>cname</code> - The CNAME for your website. It will go into a <code>CNAME</code> file when your site it built.</p>
|
||||
<p><code>customDocsPath</code> - By default, Docusaurus expects your documentation to be in a directory called <code>docs</code>. This directory is at the same level as the <code>website</code> directory (i.e., not inside the <code>website</code> directory). You can specify a custom path to your documentation with this field. <strong>Note that all of your documentation <code>*.md</code> files must still reside in a flat hierarchy. You cannot have your documents in nested directories</strong>.</p>
|
||||
<pre><code class="hljs css languages- js">customDocsPath: <span class="hljs-string">"docs/site"</span>
|
||||
<pre><code class="hljs css languages-js">customDocsPath: <span class="hljs-string">"docs/site"</span>
|
||||
</code></pre>
|
||||
<pre><code class="hljs css languages- js">customDocsPath: <span class="hljs-string">"website-docs"</span>
|
||||
<pre><code class="hljs css languages-js">customDocsPath: <span class="hljs-string">"website-docs"</span>
|
||||
</code></pre>
|
||||
<p><code>disableHeaderTitle</code> - An option to disable showing the title in the header next to the header icon. Exclude this field to keep the header as normal, otherwise set to <code>true</code>.</p>
|
||||
<p><code>disableTitleTagline</code> - An option to disable showing the tagline in the title of main pages. Exclude this field to keep page titles as <code>Title • Tagline</code>. Set to <code>true</code> to make page titles just <code>Title</code>.</p>
|
||||
|
|
|
|||
|
|
@ -66,7 +66,7 @@
|
|||
<p><code>headerIcon</code> - url for icon used in header navigation bar.</p>
|
||||
<p><code>headerLinks</code> - Links that will be used in the header navigation bar. The <code>label</code> field of each object will be the link text and will also be translated for each language.</p>
|
||||
<p>Example Usage:</p>
|
||||
<pre><code class="hljs css languages- js">headerLinks: [
|
||||
<pre><code class="hljs css languages-js">headerLinks: [
|
||||
<span class="hljs-comment">// Links to document with id doc1 for current language/version</span>
|
||||
{ <span class="hljs-attr">doc</span>: <span class="hljs-string">"doc1"</span>, <span class="hljs-attr">label</span>: <span class="hljs-string">"Getting Started"</span> },
|
||||
<span class="hljs-comment">// Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language</span>
|
||||
|
|
@ -97,9 +97,9 @@
|
|||
<p><code>blogSidebarCount</code> - Control the number of blog posts that show up in the sidebar. See the <a href="/docs/en/1.0.11/adding-blog#changing-how-many-blog-posts-show-on-sidebar">adding a blog docs</a> for more information.</p>
|
||||
<p><code>cname</code> - The CNAME for your website. It will go into a <code>CNAME</code> file when your site it built.</p>
|
||||
<p><code>customDocsPath</code> - By default, Docusaurus expects your documentation to be in a directory called <code>docs</code>. This directory is at the same level as the <code>website</code> directory (i.e., not inside the <code>website</code> directory). You can specify a custom path to your documentation with this field. <strong>Note that all of your documentation <code>*.md</code> files must still reside in a flat hierarchy. You cannot have your documents in nested directories</strong>.</p>
|
||||
<pre><code class="hljs css languages- js">customDocsPath: <span class="hljs-string">"docs/site"</span>
|
||||
<pre><code class="hljs css languages-js">customDocsPath: <span class="hljs-string">"docs/site"</span>
|
||||
</code></pre>
|
||||
<pre><code class="hljs css languages- js">customDocsPath: <span class="hljs-string">"website-docs"</span>
|
||||
<pre><code class="hljs css languages-js">customDocsPath: <span class="hljs-string">"website-docs"</span>
|
||||
</code></pre>
|
||||
<p><code>disableHeaderTitle</code> - An option to disable showing the title in the header next to the header icon. Exclude this field to keep the header as normal, otherwise set to <code>true</code>.</p>
|
||||
<p><code>disableTitleTagline</code> - An option to disable showing the tagline in the title of main pages. Exclude this field to keep page titles as <code>Title • Tagline</code>. Set to <code>true</code> to make page titles just <code>Title</code>.</p>
|
||||
|
|
|
|||
|
|
@ -51,7 +51,7 @@
|
|||
<p>After <a href="/docs/en/1.0.11/installation">installation</a> and <a href="/docs/en/1.0.11/site-preparation">preparation</a>, much of the work to create a basic site for your docs is already complete.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="site-structure"></a><a href="#site-structure" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Site Structure</h2>
|
||||
<p>Your site structure looks like the following:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs
|
||||
└── website
|
||||
│ └── blog
|
||||
|
|
|
|||
|
|
@ -51,7 +51,7 @@
|
|||
<p>After <a href="/docs/en/1.0.11/installation">installation</a> and <a href="/docs/en/1.0.11/site-preparation">preparation</a>, much of the work to create a basic site for your docs is already complete.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="site-structure"></a><a href="#site-structure" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Site Structure</h2>
|
||||
<p>Your site structure looks like the following:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs
|
||||
└── website
|
||||
│ └── blog
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@
|
|||
</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/facebook/docusaurus/edit/master/docs/getting-started-preparation.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 class="postHeaderTitle">Site Preparation</h1></header><article><div><span><p>After <a href="/docs/en/1.0.11/installation">installing Docusaurus</a>, you now have a skeleton to work from for your specific website. The following discusses the rest of the Docusaurus structure in order for you to prepare your site.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="directory-structure"></a><a href="#directory-structure" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Directory Structure</h2>
|
||||
<p>As shown after you <a href="/docs/en/1.0.11/installation">installed Docusaurus</a>, the initialization script created a directory structure similar to:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs-examples-from-docusaurus
|
||||
│ └── doc1.md
|
||||
│ └── doc2.md
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@
|
|||
</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/facebook/docusaurus/edit/master/docs/getting-started-preparation.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 class="postHeaderTitle">Site Preparation</h1></header><article><div><span><p>After <a href="/docs/en/1.0.11/installation">installing Docusaurus</a>, you now have a skeleton to work from for your specific website. The following discusses the rest of the Docusaurus structure in order for you to prepare your site.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="directory-structure"></a><a href="#directory-structure" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Directory Structure</h2>
|
||||
<p>As shown after you <a href="/docs/en/1.0.11/installation">installed Docusaurus</a>, the initialization script created a directory structure similar to:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs-examples-from-docusaurus
|
||||
│ └── doc1.md
|
||||
│ └── doc2.md
|
||||
|
|
|
|||
|
|
@ -76,7 +76,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<p>Pages allow you to customize layout and specific content of pages like a custom index page or help page.</p>
|
||||
<p>Pages with text that you want translated should be placed in <code>website/pages/en</code> folder.</p>
|
||||
<p>Wrap strings you want translated in a <code><translate></code> tag, and add the following <code>require</code> statement to the top of the file:</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token operator">...</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token operator">...</span>
|
||||
<span class="token keyword">const</span> translate <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">"../../server/translate.js"</span><span class="token punctuation">)</span><span class="token punctuation">.</span>translate<span class="token punctuation">;</span>
|
||||
<span class="token operator">...</span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>h2</span><span class="token punctuation">></span></span>
|
||||
|
|
@ -85,7 +85,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<span class="token operator">...</span>
|
||||
</code></pre>
|
||||
<p>You can also include an optional description attribute to give more context to a translator about how to translate the string:</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span> <span class="token attr-name">desc</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>flower, not verb<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Rose<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
</code></pre>
|
||||
|
|
@ -95,7 +95,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<h2><a class="anchor" aria-hidden="true" id="gathering-strings-to-translate"></a><a href="#gathering-strings-to-translate" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Gathering Strings to Translate</h2>
|
||||
<p>The strings within localized Pages must be extracted and provided to Crowdin.</p>
|
||||
<p>Add the following script to your <code>website/package.json</code> file, if it does not exist already:</p>
|
||||
<pre><code class="hljs css languages- json">...
|
||||
<pre><code class="hljs css languages-json">...
|
||||
"scripts": {
|
||||
"write-translations": "docusaurus-write-translations"
|
||||
},
|
||||
|
|
@ -133,7 +133,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
</blockquote>
|
||||
<p>The example below can be automatically generated by the Docusaurus cli with the <code>examples</code> script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.</p>
|
||||
<p>Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.</p>
|
||||
<pre><code class="hljs css languages- yaml"><span class="hljs-attr">project_identifier_env:</span> <span class="hljs-string">CROWDIN_DOCUSAURUS_PROJECT_ID</span>
|
||||
<pre><code class="hljs css languages-yaml"><span class="hljs-attr">project_identifier_env:</span> <span class="hljs-string">CROWDIN_DOCUSAURUS_PROJECT_ID</span>
|
||||
<span class="hljs-attr">api_key_env:</span> <span class="hljs-string">CROWDIN_DOCUSAURUS_API_KEY</span>
|
||||
<span class="hljs-attr">base_path:</span> <span class="hljs-string">"./"</span>
|
||||
<span class="hljs-attr">preserve_hierarchy:</span> <span class="hljs-literal">true</span>
|
||||
|
|
@ -158,7 +158,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<h3><a class="anchor" aria-hidden="true" id="setup-the-crowdin-scripts"></a><a href="#setup-the-crowdin-scripts" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Setup the Crowdin Scripts</h3>
|
||||
<p>You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in <code>/docs</code> as well as translatable strings in <code>website/i18n/en.json</code>. (These strings can be generated by running <code>yarn write-translations</code>.)</p>
|
||||
<p>You can add the following to your <code>package.json</code> to manually trigger Crowdin.</p>
|
||||
<pre><code class="hljs css languages- json">"scripts": {
|
||||
<pre><code class="hljs css languages-json">"scripts": {
|
||||
"crowdin-upload": "crowdin --config ../crowdin.yaml upload sources --auto-update -b master",
|
||||
"crowdin-download": "crowdin --config ../crowdin.yaml download -b master"
|
||||
},
|
||||
|
|
@ -183,7 +183,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<h3><a class="anchor" aria-hidden="true" id="automated-file-sync-using-circleci"></a><a href="#automated-file-sync-using-circleci" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Automated File Sync Using CircleCI</h3>
|
||||
<p>You can automate pulling down and uploading translations for your files using the <a href="https://circleci.com">CircleCI</a> web continuous integration service.</p>
|
||||
<p>First, update the <code>circle.yml</code> file in your project directory to include steps to upload English files to be translated and download translated files using the Crowdin CLI. Here is an example <code>circle.yml</code> file:</p>
|
||||
<pre><code class="hljs css languages- yaml"><span class="hljs-attr">machine:</span>
|
||||
<pre><code class="hljs css languages-yaml"><span class="hljs-attr">machine:</span>
|
||||
<span class="hljs-attr"> node:</span>
|
||||
<span class="hljs-attr"> version:</span> <span class="hljs-number">6.10</span><span class="hljs-number">.3</span>
|
||||
<span class="hljs-attr"> npm:</span>
|
||||
|
|
@ -219,7 +219,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<p>If you wish to use Crowdin on your machine locally, you can install the <a href="https://support.crowdin.com/cli-tool/">Crowdin CLI tool</a> and run the same commands found in the <code>circle.yaml</code> file. The only difference is that you must set <code>project_identifier</code> and <code>api_key</code> values in the <code>crowdin.yaml</code> file since you will not have Circle environment variables set up.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="versioned-translations"></a><a href="#versioned-translations" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Versioned Translations</h2>
|
||||
<p>If you wish to have translation and versioning for your documentation, add the following section to the end of your <code>crowdin.yaml</code> file:</p>
|
||||
<pre><code class="hljs css languages- yaml"><span class="hljs-bullet"> -</span>
|
||||
<pre><code class="hljs css languages-yaml"><span class="hljs-bullet"> -</span>
|
||||
<span class="hljs-attr"> source:</span> <span class="hljs-string">'/website/versioned_docs/**/*.md'</span>
|
||||
<span class="hljs-attr"> translation:</span> <span class="hljs-string">'/website/translated_docs/%locale%/**/%original_file_name%'</span>
|
||||
<span class="hljs-attr"> languages_mapping:</span> <span class="hljs-meta">*anchor</span>
|
||||
|
|
|
|||
|
|
@ -76,7 +76,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<p>Pages allow you to customize layout and specific content of pages like a custom index page or help page.</p>
|
||||
<p>Pages with text that you want translated should be placed in <code>website/pages/en</code> folder.</p>
|
||||
<p>Wrap strings you want translated in a <code><translate></code> tag, and add the following <code>require</code> statement to the top of the file:</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token operator">...</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token operator">...</span>
|
||||
<span class="token keyword">const</span> translate <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">"../../server/translate.js"</span><span class="token punctuation">)</span><span class="token punctuation">.</span>translate<span class="token punctuation">;</span>
|
||||
<span class="token operator">...</span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>h2</span><span class="token punctuation">></span></span>
|
||||
|
|
@ -85,7 +85,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<span class="token operator">...</span>
|
||||
</code></pre>
|
||||
<p>You can also include an optional description attribute to give more context to a translator about how to translate the string:</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span> <span class="token attr-name">desc</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>flower, not verb<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Rose<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
</code></pre>
|
||||
|
|
@ -95,7 +95,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<h2><a class="anchor" aria-hidden="true" id="gathering-strings-to-translate"></a><a href="#gathering-strings-to-translate" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Gathering Strings to Translate</h2>
|
||||
<p>The strings within localized Pages must be extracted and provided to Crowdin.</p>
|
||||
<p>Add the following script to your <code>website/package.json</code> file, if it does not exist already:</p>
|
||||
<pre><code class="hljs css languages- json">...
|
||||
<pre><code class="hljs css languages-json">...
|
||||
"scripts": {
|
||||
"write-translations": "docusaurus-write-translations"
|
||||
},
|
||||
|
|
@ -133,7 +133,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
</blockquote>
|
||||
<p>The example below can be automatically generated by the Docusaurus cli with the <code>examples</code> script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.</p>
|
||||
<p>Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.</p>
|
||||
<pre><code class="hljs css languages- yaml"><span class="hljs-attr">project_identifier_env:</span> <span class="hljs-string">CROWDIN_DOCUSAURUS_PROJECT_ID</span>
|
||||
<pre><code class="hljs css languages-yaml"><span class="hljs-attr">project_identifier_env:</span> <span class="hljs-string">CROWDIN_DOCUSAURUS_PROJECT_ID</span>
|
||||
<span class="hljs-attr">api_key_env:</span> <span class="hljs-string">CROWDIN_DOCUSAURUS_API_KEY</span>
|
||||
<span class="hljs-attr">base_path:</span> <span class="hljs-string">"./"</span>
|
||||
<span class="hljs-attr">preserve_hierarchy:</span> <span class="hljs-literal">true</span>
|
||||
|
|
@ -158,7 +158,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<h3><a class="anchor" aria-hidden="true" id="setup-the-crowdin-scripts"></a><a href="#setup-the-crowdin-scripts" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Setup the Crowdin Scripts</h3>
|
||||
<p>You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in <code>/docs</code> as well as translatable strings in <code>website/i18n/en.json</code>. (These strings can be generated by running <code>yarn write-translations</code>.)</p>
|
||||
<p>You can add the following to your <code>package.json</code> to manually trigger Crowdin.</p>
|
||||
<pre><code class="hljs css languages- json">"scripts": {
|
||||
<pre><code class="hljs css languages-json">"scripts": {
|
||||
"crowdin-upload": "crowdin --config ../crowdin.yaml upload sources --auto-update -b master",
|
||||
"crowdin-download": "crowdin --config ../crowdin.yaml download -b master"
|
||||
},
|
||||
|
|
@ -183,7 +183,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<h3><a class="anchor" aria-hidden="true" id="automated-file-sync-using-circleci"></a><a href="#automated-file-sync-using-circleci" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Automated File Sync Using CircleCI</h3>
|
||||
<p>You can automate pulling down and uploading translations for your files using the <a href="https://circleci.com">CircleCI</a> web continuous integration service.</p>
|
||||
<p>First, update the <code>circle.yml</code> file in your project directory to include steps to upload English files to be translated and download translated files using the Crowdin CLI. Here is an example <code>circle.yml</code> file:</p>
|
||||
<pre><code class="hljs css languages- yaml"><span class="hljs-attr">machine:</span>
|
||||
<pre><code class="hljs css languages-yaml"><span class="hljs-attr">machine:</span>
|
||||
<span class="hljs-attr"> node:</span>
|
||||
<span class="hljs-attr"> version:</span> <span class="hljs-number">6.10</span><span class="hljs-number">.3</span>
|
||||
<span class="hljs-attr"> npm:</span>
|
||||
|
|
@ -219,7 +219,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<p>If you wish to use Crowdin on your machine locally, you can install the <a href="https://support.crowdin.com/cli-tool/">Crowdin CLI tool</a> and run the same commands found in the <code>circle.yaml</code> file. The only difference is that you must set <code>project_identifier</code> and <code>api_key</code> values in the <code>crowdin.yaml</code> file since you will not have Circle environment variables set up.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="versioned-translations"></a><a href="#versioned-translations" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Versioned Translations</h2>
|
||||
<p>If you wish to have translation and versioning for your documentation, add the following section to the end of your <code>crowdin.yaml</code> file:</p>
|
||||
<pre><code class="hljs css languages- yaml"><span class="hljs-bullet"> -</span>
|
||||
<pre><code class="hljs css languages-yaml"><span class="hljs-bullet"> -</span>
|
||||
<span class="hljs-attr"> source:</span> <span class="hljs-string">'/website/versioned_docs/**/*.md'</span>
|
||||
<span class="hljs-attr"> translation:</span> <span class="hljs-string">'/website/translated_docs/%locale%/**/%original_file_name%'</span>
|
||||
<span class="hljs-attr"> languages_mapping:</span> <span class="hljs-meta">*anchor</span>
|
||||
|
|
|
|||
|
|
@ -50,19 +50,19 @@
|
|||
</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/facebook/docusaurus/edit/master/docs/guides-versioning.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 class="postHeaderTitle">Versioning</h1></header><article><div><span><p>You 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" aria-hidden="true" id="how-to-create-new-versions"></a><a href="#how-to-create-new-versions" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>How to Create New Versions</h2>
|
||||
<p>Run the following script to generate a starter versions page listing all the site versions:</p>
|
||||
<pre><code class="hljs css languages- bash">yarn examples versions
|
||||
<pre><code class="hljs css languages-bash">yarn examples versions
|
||||
</code></pre>
|
||||
<p>This creates the <code>pages/en/versions.js</code> file.</p>
|
||||
<p>You can edit this file later on to customize how you display the versions.</p>
|
||||
<p>Add the following script to your <code>package.json</code> file if it doesn't already exist:</p>
|
||||
<pre><code class="hljs css languages- json">...
|
||||
<pre><code class="hljs css languages-json">...
|
||||
"scripts": {
|
||||
"version": "docusaurus-version"
|
||||
},
|
||||
...
|
||||
</code></pre>
|
||||
<p>Run the script with a command line argument of the version you wish to create. e.g.,</p>
|
||||
<pre><code class="hljs css languages- bash">yarn run version 1.0.0
|
||||
<pre><code class="hljs css languages-bash">yarn run version 1.0.0
|
||||
</code></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 <code>1.0.0</code> as the version number, version <code>1.0.0</code> is considered the latest release version for your project. The site will display the version number next to the title in the header. This version number links to a versions page that you created earlier.</p>
|
||||
|
|
@ -81,14 +81,14 @@
|
|||
<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" aria-hidden="true" id="renaming-existing-versions"></a><a href="#renaming-existing-versions" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Renaming Existing Versions</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><code class="hljs css languages- json">...
|
||||
<pre><code class="hljs css languages-json">...
|
||||
"scripts": {
|
||||
"rename-version": "docusaurus-rename-version"
|
||||
},
|
||||
...
|
||||
</code></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><code class="hljs css languages- bash">yarn run rename-version 1.0.0 1.0.1
|
||||
<pre><code class="hljs css languages-bash">yarn run rename-version 1.0.0 1.0.1
|
||||
</code></pre>
|
||||
<h2><a class="anchor" aria-hidden="true" id="versioning-and-translations"></a><a href="#versioning-and-translations" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Versioning and Translations</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="/docs/en/1.0.11/translation">translations guide</a>.</p>
|
||||
|
|
|
|||
|
|
@ -50,19 +50,19 @@
|
|||
</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/facebook/docusaurus/edit/master/docs/guides-versioning.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 class="postHeaderTitle">Versioning</h1></header><article><div><span><p>You 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" aria-hidden="true" id="how-to-create-new-versions"></a><a href="#how-to-create-new-versions" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>How to Create New Versions</h2>
|
||||
<p>Run the following script to generate a starter versions page listing all the site versions:</p>
|
||||
<pre><code class="hljs css languages- bash">yarn examples versions
|
||||
<pre><code class="hljs css languages-bash">yarn examples versions
|
||||
</code></pre>
|
||||
<p>This creates the <code>pages/en/versions.js</code> file.</p>
|
||||
<p>You can edit this file later on to customize how you display the versions.</p>
|
||||
<p>Add the following script to your <code>package.json</code> file if it doesn't already exist:</p>
|
||||
<pre><code class="hljs css languages- json">...
|
||||
<pre><code class="hljs css languages-json">...
|
||||
"scripts": {
|
||||
"version": "docusaurus-version"
|
||||
},
|
||||
...
|
||||
</code></pre>
|
||||
<p>Run the script with a command line argument of the version you wish to create. e.g.,</p>
|
||||
<pre><code class="hljs css languages- bash">yarn run version 1.0.0
|
||||
<pre><code class="hljs css languages-bash">yarn run version 1.0.0
|
||||
</code></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 <code>1.0.0</code> as the version number, version <code>1.0.0</code> is considered the latest release version for your project. The site will display the version number next to the title in the header. This version number links to a versions page that you created earlier.</p>
|
||||
|
|
@ -81,14 +81,14 @@
|
|||
<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" aria-hidden="true" id="renaming-existing-versions"></a><a href="#renaming-existing-versions" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Renaming Existing Versions</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><code class="hljs css languages- json">...
|
||||
<pre><code class="hljs css languages-json">...
|
||||
"scripts": {
|
||||
"rename-version": "docusaurus-rename-version"
|
||||
},
|
||||
...
|
||||
</code></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><code class="hljs css languages- bash">yarn run rename-version 1.0.0 1.0.1
|
||||
<pre><code class="hljs css languages-bash">yarn run rename-version 1.0.0 1.0.1
|
||||
</code></pre>
|
||||
<h2><a class="anchor" aria-hidden="true" id="versioning-and-translations"></a><a href="#versioning-and-translations" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Versioning and Translations</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="/docs/en/1.0.11/translation">translations guide</a>.</p>
|
||||
|
|
|
|||
|
|
@ -59,7 +59,7 @@
|
|||
<h3><a class="anchor" aria-hidden="true" id="complibrarymarkdownblock"></a><a href="#complibrarymarkdownblock" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><code>CompLibrary.MarkdownBlock</code></h3>
|
||||
<p>A React component that parses markdown and renders to HTML.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token keyword">const</span> MarkdownBlock <span class="token operator">=</span> CompLibrary<span class="token punctuation">.</span>MarkdownBlock<span class="token punctuation">;</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token keyword">const</span> MarkdownBlock <span class="token operator">=</span> CompLibrary<span class="token punctuation">.</span>MarkdownBlock<span class="token punctuation">;</span>
|
||||
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>MarkdownBlock</span><span class="token punctuation">></span></span>
|
||||
<span class="token punctuation">[</span>Markdown syntax <span class="token keyword">for</span> a link<span class="token punctuation">]</span><span class="token punctuation">(</span>http<span class="token punctuation">:</span><span class="token operator">/</span><span class="token operator">/</span>www<span class="token punctuation">.</span>example<span class="token punctuation">.</span>com<span class="token punctuation">)</span>
|
||||
|
|
@ -79,7 +79,7 @@
|
|||
</tbody>
|
||||
</table>
|
||||
<p><strong>Example</strong></p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>Container</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>Container</span>
|
||||
<span class="token attr-name">padding</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">[</span><span class="token string">'bottom'</span><span class="token punctuation">,</span> <span class="token string">'top'</span><span class="token punctuation">]</span><span class="token punctuation">}</span></span>
|
||||
<span class="token attr-name">background</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>light<span class="token punctuation">"</span></span>
|
||||
<span class="token attr-name">className</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>myCustomClass<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
|
|
@ -144,19 +144,19 @@
|
|||
<h2><a class="anchor" aria-hidden="true" id="translating-strings"></a><a href="#translating-strings" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Translating Strings</h2>
|
||||
<p>When translations are enabled, any pages inside <code>website/pages/en</code> will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the <code>languages.js</code> file. E.g. The url for a French page of <code>website/pages/en/help.js</code> would be found at <code>${baseUrl}fr/help.html</code>.</p>
|
||||
<p>When writing pages that you wish to translate, wrap any strings to be translated inside a <code><translate></code> tag. e.g.,</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span><span class="token punctuation">></span></span><span class="token constant">I</span> like translations<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>p</span><span class="token punctuation">></span></span>
|
||||
</code></pre>
|
||||
<p>You can also provide an optional description attribute to provide context for translators. e.g,</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>a</span> <span class="token attr-name">href</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>/community<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>a</span> <span class="token attr-name">href</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>/community<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span> <span class="token attr-name">desc</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>Footer link to page referring to community GitHub and Slack<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
Community
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>a</span><span class="token punctuation">></span></span>
|
||||
</code></pre>
|
||||
<p>Add the following require statement as well:</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> translate = <span class="hljs-built_in">require</span>(<span class="hljs-string">'../../server/translate.js'</span>).translate;
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> translate = <span class="hljs-built_in">require</span>(<span class="hljs-string">'../../server/translate.js'</span>).translate;
|
||||
</code></pre>
|
||||
<p>Note that this path is valid for files inside <code>pages/en</code> and should be adjusted accordingly if files are in different locations, as discussed <a href="#page-require-paths">above</a>.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="using-static-assets"></a><a href="#using-static-assets" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Using Static Assets</h2>
|
||||
|
|
|
|||
|
|
@ -59,7 +59,7 @@
|
|||
<h3><a class="anchor" aria-hidden="true" id="complibrarymarkdownblock"></a><a href="#complibrarymarkdownblock" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><code>CompLibrary.MarkdownBlock</code></h3>
|
||||
<p>A React component that parses markdown and renders to HTML.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token keyword">const</span> MarkdownBlock <span class="token operator">=</span> CompLibrary<span class="token punctuation">.</span>MarkdownBlock<span class="token punctuation">;</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token keyword">const</span> MarkdownBlock <span class="token operator">=</span> CompLibrary<span class="token punctuation">.</span>MarkdownBlock<span class="token punctuation">;</span>
|
||||
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>MarkdownBlock</span><span class="token punctuation">></span></span>
|
||||
<span class="token punctuation">[</span>Markdown syntax <span class="token keyword">for</span> a link<span class="token punctuation">]</span><span class="token punctuation">(</span>http<span class="token punctuation">:</span><span class="token operator">/</span><span class="token operator">/</span>www<span class="token punctuation">.</span>example<span class="token punctuation">.</span>com<span class="token punctuation">)</span>
|
||||
|
|
@ -79,7 +79,7 @@
|
|||
</tbody>
|
||||
</table>
|
||||
<p><strong>Example</strong></p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>Container</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>Container</span>
|
||||
<span class="token attr-name">padding</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">[</span><span class="token string">'bottom'</span><span class="token punctuation">,</span> <span class="token string">'top'</span><span class="token punctuation">]</span><span class="token punctuation">}</span></span>
|
||||
<span class="token attr-name">background</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>light<span class="token punctuation">"</span></span>
|
||||
<span class="token attr-name">className</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>myCustomClass<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
|
|
@ -144,19 +144,19 @@
|
|||
<h2><a class="anchor" aria-hidden="true" id="translating-strings"></a><a href="#translating-strings" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Translating Strings</h2>
|
||||
<p>When translations are enabled, any pages inside <code>website/pages/en</code> will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the <code>languages.js</code> file. E.g. The url for a French page of <code>website/pages/en/help.js</code> would be found at <code>${baseUrl}fr/help.html</code>.</p>
|
||||
<p>When writing pages that you wish to translate, wrap any strings to be translated inside a <code><translate></code> tag. e.g.,</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span><span class="token punctuation">></span></span><span class="token constant">I</span> like translations<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>p</span><span class="token punctuation">></span></span>
|
||||
</code></pre>
|
||||
<p>You can also provide an optional description attribute to provide context for translators. e.g,</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>a</span> <span class="token attr-name">href</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>/community<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>a</span> <span class="token attr-name">href</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>/community<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span> <span class="token attr-name">desc</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>Footer link to page referring to community GitHub and Slack<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
Community
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>a</span><span class="token punctuation">></span></span>
|
||||
</code></pre>
|
||||
<p>Add the following require statement as well:</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> translate = <span class="hljs-built_in">require</span>(<span class="hljs-string">'../../server/translate.js'</span>).translate;
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> translate = <span class="hljs-built_in">require</span>(<span class="hljs-string">'../../server/translate.js'</span>).translate;
|
||||
</code></pre>
|
||||
<p>Note that this path is valid for files inside <code>pages/en</code> and should be adjusted accordingly if files are in different locations, as discussed <a href="#page-require-paths">above</a>.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="using-static-assets"></a><a href="#using-static-assets" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Using Static Assets</h2>
|
||||
|
|
|
|||
|
|
@ -100,7 +100,7 @@
|
|||
<li><code>USE_SSH</code>: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.</li>
|
||||
</ul>
|
||||
<p>e.g.,</p>
|
||||
<pre><code class="hljs css languages- bash">GIT_USER=docusaurus-bot USE_SSH=<span class="hljs-literal">true</span> yarn run publish-gh-pages
|
||||
<pre><code class="hljs css languages-bash">GIT_USER=docusaurus-bot USE_SSH=<span class="hljs-literal">true</span> yarn run publish-gh-pages
|
||||
</code></pre>
|
||||
<p>The following environment variables are <a href="https://circleci.com/docs/1.0/environment-variables/">set by CircleCI</a> during the build process.</p>
|
||||
<ul>
|
||||
|
|
|
|||
|
|
@ -100,7 +100,7 @@
|
|||
<li><code>USE_SSH</code>: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.</li>
|
||||
</ul>
|
||||
<p>e.g.,</p>
|
||||
<pre><code class="hljs css languages- bash">GIT_USER=docusaurus-bot USE_SSH=<span class="hljs-literal">true</span> yarn run publish-gh-pages
|
||||
<pre><code class="hljs css languages-bash">GIT_USER=docusaurus-bot USE_SSH=<span class="hljs-literal">true</span> yarn run publish-gh-pages
|
||||
</code></pre>
|
||||
<p>The following environment variables are <a href="https://circleci.com/docs/1.0/environment-variables/">set by CircleCI</a> during the build process.</p>
|
||||
<ul>
|
||||
|
|
|
|||
|
|
@ -53,7 +53,7 @@
|
|||
<p>You can <a href="/docs/en/1.0.12/site-preparation#verifying-installation">start</a> your local server and go to <code>http://localhost:3000</code> to see what the example home page looks like. From there, edit the <code>website/pages/en/index.js</code> file and its various components to use the images and text you want for your project.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="adding-other-custom-pages"></a><a href="#adding-other-custom-pages" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Adding Other Custom Pages</h2>
|
||||
<p>Docusaurus provides some simple example pages in the <code>website/pages/en</code> directory, including <code>index.js</code>, <code>users.js</code>, and <code>help.js</code>. These are good examples to showcase how to create a custom page for Docusaurus.</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs
|
||||
└── website
|
||||
│ └── blog
|
||||
|
|
@ -85,7 +85,7 @@
|
|||
<p>Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.</p>
|
||||
<p>Your footer will automatically get applied to all pages on your site, including docs and blog posts. The sole exception to this is any static html pages you include.</p>
|
||||
<p>If you do not want a footer for your site, change the <code>render</code> function of <code>core/Footer.js</code> to return <code>null</code>. e.g.,</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token keyword">const</span> React <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">"react"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token keyword">const</span> React <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">"react"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token keyword">class</span> <span class="token class-name">Footer</span> <span class="token keyword">extends</span> <span class="token class-name">React<span class="token punctuation">.</span>Component</span> <span class="token punctuation">{</span>
|
||||
<span class="token function">render</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
|
|
|
|||
|
|
@ -53,7 +53,7 @@
|
|||
<p>You can <a href="/docs/en/1.0.12/site-preparation#verifying-installation">start</a> your local server and go to <code>http://localhost:3000</code> to see what the example home page looks like. From there, edit the <code>website/pages/en/index.js</code> file and its various components to use the images and text you want for your project.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="adding-other-custom-pages"></a><a href="#adding-other-custom-pages" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Adding Other Custom Pages</h2>
|
||||
<p>Docusaurus provides some simple example pages in the <code>website/pages/en</code> directory, including <code>index.js</code>, <code>users.js</code>, and <code>help.js</code>. These are good examples to showcase how to create a custom page for Docusaurus.</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs
|
||||
└── website
|
||||
│ └── blog
|
||||
|
|
@ -85,7 +85,7 @@
|
|||
<p>Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.</p>
|
||||
<p>Your footer will automatically get applied to all pages on your site, including docs and blog posts. The sole exception to this is any static html pages you include.</p>
|
||||
<p>If you do not want a footer for your site, change the <code>render</code> function of <code>core/Footer.js</code> to return <code>null</code>. e.g.,</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token keyword">const</span> React <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">"react"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token keyword">const</span> React <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">"react"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token keyword">class</span> <span class="token class-name">Footer</span> <span class="token keyword">extends</span> <span class="token class-name">React<span class="token punctuation">.</span>Component</span> <span class="token punctuation">{</span>
|
||||
<span class="token function">render</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
|
|
|
|||
|
|
@ -55,7 +55,7 @@
|
|||
<p><code>hide_title</code>: Whether to hide the title at the top of the doc.</p>
|
||||
<p><code>sidebar_label</code>: The text shown in the document sidebar for this document. If this field is not present, the document's <code>sidebar_label</code> will default to its <code>title</code>.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
id: doc1
|
||||
title: My Document
|
||||
<span class="hljs-section">sidebar_label: Document
|
||||
|
|
@ -63,7 +63,7 @@ title: My Document
|
|||
</code></pre>
|
||||
<p>Versioned documents have their ids altered to include the version number when they get copied. The new <code>id</code> is <code>version-${version}-${id}</code> where <code>${version}</code> is the version number of that document and <code>${id}</code> is the original <code>id</code>. Additionally, versioned documents get an added <code>original_id</code> field with the original document id.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
id: version-1.0.0-doc1
|
||||
title: My Document
|
||||
sidebar_label: Document
|
||||
|
|
@ -72,7 +72,7 @@ sidebar_label: Document
|
|||
</code></pre>
|
||||
<p><code>custom_edit_url</code>: The url for editing this document. If this field is not present, the document's edit url will fallback to <code>editUrl</code> from optional fields of <code>siteConfig.js</code>. See <a href="site-config.md">siteConfig.js</a> docs for more information.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
id: doc-markdown
|
||||
title: Markdown Features
|
||||
<span class="hljs-section">custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
|
||||
|
|
@ -85,7 +85,7 @@ title: Markdown Features
|
|||
<p><code>authorURL</code>: A page to link to when a site user clicks the author's name. If this field is omitted, the author's name will not link to anything.</p>
|
||||
<p><code>authorFBID</code>: The author's Facebook id, used only to get the author's profile picture to display with the blog post. If this field is omitted, no author picture will be shown for the blog post.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
title: My First Blog Post
|
||||
author: Frank Li
|
||||
authorURL: http://twitter.com/franchementli
|
||||
|
|
@ -97,20 +97,20 @@ authorURL: http://twitter.com/franchementli
|
|||
<h3><a class="anchor" aria-hidden="true" id="linking-other-documents"></a><a href="#linking-other-documents" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Linking other Documents</h3>
|
||||
<p>You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- markdown">[<span class="hljs-string">This links to another document</span>](<span class="hljs-link">other-document.md</span>)
|
||||
<pre><code class="hljs css languages-markdown">[<span class="hljs-string">This links to another document</span>](<span class="hljs-link">other-document.md</span>)
|
||||
</code></pre>
|
||||
<p>This markdown will automatically get converted into a link to <code>/docs/other-document.html</code> (or the appropriately translated/versioned link) once it gets rendered.</p>
|
||||
<p>This can help when you want to navigate through docs on GitHub since the links there will be functional links to other documents (still on GitHub), but the documents will have the correct html links when they get rendered.</p>
|
||||
<h3><a class="anchor" aria-hidden="true" id="linking-to-images-and-other-assets"></a><a href="#linking-to-images-and-other-assets" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Linking to Images and Other Assets</h3>
|
||||
<p>Static assets can be linked to in the same way that documents are, using relative urls. Static assets used in documents and blogs should go into <code>docs/assets</code> and <code>website/blog/assets</code>, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- markdown">![<span class="hljs-string">alt-text</span>](<span class="hljs-link">/docs/assets/doc-image.png</span>)
|
||||
<pre><code class="hljs css languages-markdown">![<span class="hljs-string">alt-text</span>](<span class="hljs-link">/docs/assets/doc-image.png</span>)
|
||||
</code></pre>
|
||||
<h3><a class="anchor" aria-hidden="true" id="generating-table-of-contents"></a><a href="#generating-table-of-contents" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Generating Table of Contents</h3>
|
||||
<p>You can make an autogenerated list of links, which can be useful as a table of contents for API docs.</p>
|
||||
<p>In your markdown file, insert a line with the text <<code>AUTOGENERATED_TABLE_OF_CONTENTS</code>>. Write your documentation using <code>h3</code> headers for each function inside a code block. These will be found by Docusaurus and a list of links to these sections will inserted at the text <<code>AUTOGENERATED_TABLE_OF_CONTENTS</code>>.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- markdown"><span class="hljs-section">### `docusaurus.function(a, b)`</span>
|
||||
<pre><code class="hljs css languages-markdown"><span class="hljs-section">### `docusaurus.function(a, b)`</span>
|
||||
|
||||
Text describing my function
|
||||
|
||||
|
|
@ -120,7 +120,7 @@ Text describing my function
|
|||
Text describing my function
|
||||
</code></pre>
|
||||
<p>will lead to a table of contents of the functions:</p>
|
||||
<pre><code class="hljs css languages- markdown"><span class="hljs-bullet">- </span><span class="hljs-code">`docusaurus.function(a, b)`</span>
|
||||
<pre><code class="hljs css languages-markdown"><span class="hljs-bullet">- </span><span class="hljs-code">`docusaurus.function(a, b)`</span>
|
||||
<span class="hljs-bullet">- </span><span class="hljs-code">`docdoc(file)`</span>
|
||||
</code></pre>
|
||||
<p>and each function will link to their corresponding sections in the page.</p>
|
||||
|
|
@ -134,20 +134,20 @@ ReactDOM.render(
|
|||
```
|
||||
</code></pre>
|
||||
<p>...would be rendered with syntax highlighting like so:</p>
|
||||
<pre><code class="hljs css languages- javascript">ReactDOM.render(
|
||||
<pre><code class="hljs css languages-javascript">ReactDOM.render(
|
||||
<span class="xml"><span class="hljs-tag"><<span class="hljs-name">h1</span>></span>Hello, world!<span class="hljs-tag"></<span class="hljs-name">h1</span>></span></span>,
|
||||
<span class="hljs-built_in">document</span>.getElementById(<span class="hljs-string">'root'</span>)
|
||||
);
|
||||
</code></pre>
|
||||
<p>Highlighting is provided by <a href="https://highlightjs.org">Highlight.js</a> using the theme specified in your <code>siteConfig.js</code> file as part of the <code>highlight</code> key:</p>
|
||||
<pre><code class="hljs css languages- javascript">highlight: {
|
||||
<pre><code class="hljs css languages-javascript">highlight: {
|
||||
<span class="hljs-attr">theme</span>: <span class="hljs-string">'default'</span>
|
||||
}
|
||||
</code></pre>
|
||||
<p>You can find the full list of supported themes in the Highlight.js <a href="https://github.com/isagalaev/highlight.js/tree/master/src/styles"><code>styles</code></a> directory.</p>
|
||||
<h3><a class="anchor" aria-hidden="true" id="registering-additional-languages"></a><a href="#registering-additional-languages" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Registering additional languages</h3>
|
||||
<p>While Highlight.js provides support for <a href="https://highlightjs.org/static/demo/">many popular languages out of the box</a>, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the <code>hljs</code> constant as part of the <code>highlight</code> config key. This in turn allows you to call <a href="http://highlightjs.readthedocs.io/en/latest/api.html#registerlanguage-name-language"><code>registerLanguage</code></a>:</p>
|
||||
<pre><code class="hljs css languages- javascript">highlight: {
|
||||
<pre><code class="hljs css languages-javascript">highlight: {
|
||||
<span class="hljs-attr">theme</span>: <span class="hljs-string">'default'</span>,
|
||||
<span class="hljs-attr">hljs</span>: <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">hljs</span>) </span>{
|
||||
hljs.registerLanguage(<span class="hljs-string">'galacticbasic'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">hljs</span>) </span>{
|
||||
|
|
|
|||
|
|
@ -55,7 +55,7 @@
|
|||
<p><code>hide_title</code>: Whether to hide the title at the top of the doc.</p>
|
||||
<p><code>sidebar_label</code>: The text shown in the document sidebar for this document. If this field is not present, the document's <code>sidebar_label</code> will default to its <code>title</code>.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
id: doc1
|
||||
title: My Document
|
||||
<span class="hljs-section">sidebar_label: Document
|
||||
|
|
@ -63,7 +63,7 @@ title: My Document
|
|||
</code></pre>
|
||||
<p>Versioned documents have their ids altered to include the version number when they get copied. The new <code>id</code> is <code>version-${version}-${id}</code> where <code>${version}</code> is the version number of that document and <code>${id}</code> is the original <code>id</code>. Additionally, versioned documents get an added <code>original_id</code> field with the original document id.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
id: version-1.0.0-doc1
|
||||
title: My Document
|
||||
sidebar_label: Document
|
||||
|
|
@ -72,7 +72,7 @@ sidebar_label: Document
|
|||
</code></pre>
|
||||
<p><code>custom_edit_url</code>: The url for editing this document. If this field is not present, the document's edit url will fallback to <code>editUrl</code> from optional fields of <code>siteConfig.js</code>. See <a href="site-config.md">siteConfig.js</a> docs for more information.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
id: doc-markdown
|
||||
title: Markdown Features
|
||||
<span class="hljs-section">custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
|
||||
|
|
@ -85,7 +85,7 @@ title: Markdown Features
|
|||
<p><code>authorURL</code>: A page to link to when a site user clicks the author's name. If this field is omitted, the author's name will not link to anything.</p>
|
||||
<p><code>authorFBID</code>: The author's Facebook id, used only to get the author's profile picture to display with the blog post. If this field is omitted, no author picture will be shown for the blog post.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
title: My First Blog Post
|
||||
author: Frank Li
|
||||
authorURL: http://twitter.com/franchementli
|
||||
|
|
@ -97,20 +97,20 @@ authorURL: http://twitter.com/franchementli
|
|||
<h3><a class="anchor" aria-hidden="true" id="linking-other-documents"></a><a href="#linking-other-documents" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Linking other Documents</h3>
|
||||
<p>You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- markdown">[<span class="hljs-string">This links to another document</span>](<span class="hljs-link">other-document.md</span>)
|
||||
<pre><code class="hljs css languages-markdown">[<span class="hljs-string">This links to another document</span>](<span class="hljs-link">other-document.md</span>)
|
||||
</code></pre>
|
||||
<p>This markdown will automatically get converted into a link to <code>/docs/other-document.html</code> (or the appropriately translated/versioned link) once it gets rendered.</p>
|
||||
<p>This can help when you want to navigate through docs on GitHub since the links there will be functional links to other documents (still on GitHub), but the documents will have the correct html links when they get rendered.</p>
|
||||
<h3><a class="anchor" aria-hidden="true" id="linking-to-images-and-other-assets"></a><a href="#linking-to-images-and-other-assets" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Linking to Images and Other Assets</h3>
|
||||
<p>Static assets can be linked to in the same way that documents are, using relative urls. Static assets used in documents and blogs should go into <code>docs/assets</code> and <code>website/blog/assets</code>, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- markdown">![<span class="hljs-string">alt-text</span>](<span class="hljs-link">/docs/assets/doc-image.png</span>)
|
||||
<pre><code class="hljs css languages-markdown">![<span class="hljs-string">alt-text</span>](<span class="hljs-link">/docs/assets/doc-image.png</span>)
|
||||
</code></pre>
|
||||
<h3><a class="anchor" aria-hidden="true" id="generating-table-of-contents"></a><a href="#generating-table-of-contents" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Generating Table of Contents</h3>
|
||||
<p>You can make an autogenerated list of links, which can be useful as a table of contents for API docs.</p>
|
||||
<p>In your markdown file, insert a line with the text <<code>AUTOGENERATED_TABLE_OF_CONTENTS</code>>. Write your documentation using <code>h3</code> headers for each function inside a code block. These will be found by Docusaurus and a list of links to these sections will inserted at the text <<code>AUTOGENERATED_TABLE_OF_CONTENTS</code>>.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- markdown"><span class="hljs-section">### `docusaurus.function(a, b)`</span>
|
||||
<pre><code class="hljs css languages-markdown"><span class="hljs-section">### `docusaurus.function(a, b)`</span>
|
||||
|
||||
Text describing my function
|
||||
|
||||
|
|
@ -120,7 +120,7 @@ Text describing my function
|
|||
Text describing my function
|
||||
</code></pre>
|
||||
<p>will lead to a table of contents of the functions:</p>
|
||||
<pre><code class="hljs css languages- markdown"><span class="hljs-bullet">- </span><span class="hljs-code">`docusaurus.function(a, b)`</span>
|
||||
<pre><code class="hljs css languages-markdown"><span class="hljs-bullet">- </span><span class="hljs-code">`docusaurus.function(a, b)`</span>
|
||||
<span class="hljs-bullet">- </span><span class="hljs-code">`docdoc(file)`</span>
|
||||
</code></pre>
|
||||
<p>and each function will link to their corresponding sections in the page.</p>
|
||||
|
|
@ -134,20 +134,20 @@ ReactDOM.render(
|
|||
```
|
||||
</code></pre>
|
||||
<p>...would be rendered with syntax highlighting like so:</p>
|
||||
<pre><code class="hljs css languages- javascript">ReactDOM.render(
|
||||
<pre><code class="hljs css languages-javascript">ReactDOM.render(
|
||||
<span class="xml"><span class="hljs-tag"><<span class="hljs-name">h1</span>></span>Hello, world!<span class="hljs-tag"></<span class="hljs-name">h1</span>></span></span>,
|
||||
<span class="hljs-built_in">document</span>.getElementById(<span class="hljs-string">'root'</span>)
|
||||
);
|
||||
</code></pre>
|
||||
<p>Highlighting is provided by <a href="https://highlightjs.org">Highlight.js</a> using the theme specified in your <code>siteConfig.js</code> file as part of the <code>highlight</code> key:</p>
|
||||
<pre><code class="hljs css languages- javascript">highlight: {
|
||||
<pre><code class="hljs css languages-javascript">highlight: {
|
||||
<span class="hljs-attr">theme</span>: <span class="hljs-string">'default'</span>
|
||||
}
|
||||
</code></pre>
|
||||
<p>You can find the full list of supported themes in the Highlight.js <a href="https://github.com/isagalaev/highlight.js/tree/master/src/styles"><code>styles</code></a> directory.</p>
|
||||
<h3><a class="anchor" aria-hidden="true" id="registering-additional-languages"></a><a href="#registering-additional-languages" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Registering additional languages</h3>
|
||||
<p>While Highlight.js provides support for <a href="https://highlightjs.org/static/demo/">many popular languages out of the box</a>, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the <code>hljs</code> constant as part of the <code>highlight</code> config key. This in turn allows you to call <a href="http://highlightjs.readthedocs.io/en/latest/api.html#registerlanguage-name-language"><code>registerLanguage</code></a>:</p>
|
||||
<pre><code class="hljs css languages- javascript">highlight: {
|
||||
<pre><code class="hljs css languages-javascript">highlight: {
|
||||
<span class="hljs-attr">theme</span>: <span class="hljs-string">'default'</span>,
|
||||
<span class="hljs-attr">hljs</span>: <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">hljs</span>) </span>{
|
||||
hljs.registerLanguage(<span class="hljs-string">'galacticbasic'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">hljs</span>) </span>{
|
||||
|
|
|
|||
|
|
@ -61,7 +61,7 @@
|
|||
<p>After docusaurus is installed, moving forward, you can check your current version of Docusaurus by going into the <code>website</code> directory and typing <code>npm list docusaurus</code>. You can update to the <a href="https://www.npmjs.com/package/docusaurus">latest version</a> of Docusaurus by typing <code>npm update</code>.</p>
|
||||
</blockquote>
|
||||
<p>Along with previously existing files and directories, your root directory will now contain a structure similar to:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs-examples-from-docusaurus
|
||||
│ └── doc1.md
|
||||
│ └── doc2.md
|
||||
|
|
|
|||
|
|
@ -61,7 +61,7 @@
|
|||
<p>After docusaurus is installed, moving forward, you can check your current version of Docusaurus by going into the <code>website</code> directory and typing <code>npm list docusaurus</code>. You can update to the <a href="https://www.npmjs.com/package/docusaurus">latest version</a> of Docusaurus by typing <code>npm update</code>.</p>
|
||||
</blockquote>
|
||||
<p>Along with previously existing files and directories, your root directory will now contain a structure similar to:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs-examples-from-docusaurus
|
||||
│ └── doc1.md
|
||||
│ └── doc2.md
|
||||
|
|
|
|||
|
|
@ -102,7 +102,7 @@
|
|||
</table>
|
||||
<p>Once you have the parameter value information, you can go ahead and run the publish script, ensuring you have inserted your own values inside the various parameter placeholders:</p>
|
||||
<p>To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate.</p>
|
||||
<pre><code class="hljs css languages- bash">GIT_USER=<GIT_USER> \
|
||||
<pre><code class="hljs css languages-bash">GIT_USER=<GIT_USER> \
|
||||
CURRENT_BRANCH=master \
|
||||
USE_SSH=<span class="hljs-literal">true</span> \
|
||||
yarn run publish-gh-pages <span class="hljs-comment"># or `npm run publish-gh-pages`</span>
|
||||
|
|
@ -126,7 +126,7 @@
|
|||
<li>Create a <code>.circleci</code> folder and create a <code>config.yml</code> under that folder.</li>
|
||||
<li>Copy the text below into <code>.circleci/config.yml</code>.</li>
|
||||
</ol>
|
||||
<pre><code class="hljs css languages- yml"><span class="hljs-comment"># If you only one circle to run on direct commits to master, you can uncomment this out</span>
|
||||
<pre><code class="hljs css languages-yml"><span class="hljs-comment"># If you only one circle to run on direct commits to master, you can uncomment this out</span>
|
||||
<span class="hljs-comment"># and uncomment the filters: *filter-only-master down below too</span>
|
||||
<span class="hljs-comment">#</span>
|
||||
<span class="hljs-comment"># aliases:</span>
|
||||
|
|
@ -173,7 +173,7 @@
|
|||
</blockquote>
|
||||
<h3><a class="anchor" aria-hidden="true" id="tips-tricks"></a><a href="#tips-tricks" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Tips & Tricks</h3>
|
||||
<p>When initially deploying to a <code>gh-pages</code> branch using Circle CI, you may notice that some jobs triggered by commits to the <code>gh-pages</code> branch fail to run successfully due to a lack of tests. You can easily work around this by creating a basic Circle CI config with the following contents:</p>
|
||||
<pre><code class="hljs css languages- yml"><span class="hljs-comment"># Circle CI 2.0 Config File</span>
|
||||
<pre><code class="hljs css languages-yml"><span class="hljs-comment"># Circle CI 2.0 Config File</span>
|
||||
<span class="hljs-comment"># This config file will prevent tests from being run on the gh-pages branch.</span>
|
||||
<span class="hljs-attr">version:</span> <span class="hljs-number">2</span>
|
||||
<span class="hljs-attr">jobs:</span>
|
||||
|
|
|
|||
|
|
@ -102,7 +102,7 @@
|
|||
</table>
|
||||
<p>Once you have the parameter value information, you can go ahead and run the publish script, ensuring you have inserted your own values inside the various parameter placeholders:</p>
|
||||
<p>To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate.</p>
|
||||
<pre><code class="hljs css languages- bash">GIT_USER=<GIT_USER> \
|
||||
<pre><code class="hljs css languages-bash">GIT_USER=<GIT_USER> \
|
||||
CURRENT_BRANCH=master \
|
||||
USE_SSH=<span class="hljs-literal">true</span> \
|
||||
yarn run publish-gh-pages <span class="hljs-comment"># or `npm run publish-gh-pages`</span>
|
||||
|
|
@ -126,7 +126,7 @@
|
|||
<li>Create a <code>.circleci</code> folder and create a <code>config.yml</code> under that folder.</li>
|
||||
<li>Copy the text below into <code>.circleci/config.yml</code>.</li>
|
||||
</ol>
|
||||
<pre><code class="hljs css languages- yml"><span class="hljs-comment"># If you only one circle to run on direct commits to master, you can uncomment this out</span>
|
||||
<pre><code class="hljs css languages-yml"><span class="hljs-comment"># If you only one circle to run on direct commits to master, you can uncomment this out</span>
|
||||
<span class="hljs-comment"># and uncomment the filters: *filter-only-master down below too</span>
|
||||
<span class="hljs-comment">#</span>
|
||||
<span class="hljs-comment"># aliases:</span>
|
||||
|
|
@ -173,7 +173,7 @@
|
|||
</blockquote>
|
||||
<h3><a class="anchor" aria-hidden="true" id="tips-tricks"></a><a href="#tips-tricks" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Tips & Tricks</h3>
|
||||
<p>When initially deploying to a <code>gh-pages</code> branch using Circle CI, you may notice that some jobs triggered by commits to the <code>gh-pages</code> branch fail to run successfully due to a lack of tests. You can easily work around this by creating a basic Circle CI config with the following contents:</p>
|
||||
<pre><code class="hljs css languages- yml"><span class="hljs-comment"># Circle CI 2.0 Config File</span>
|
||||
<pre><code class="hljs css languages-yml"><span class="hljs-comment"># Circle CI 2.0 Config File</span>
|
||||
<span class="hljs-comment"># This config file will prevent tests from being run on the gh-pages branch.</span>
|
||||
<span class="hljs-attr">version:</span> <span class="hljs-number">2</span>
|
||||
<span class="hljs-attr">jobs:</span>
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@
|
|||
</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/facebook/docusaurus/edit/master/docs/guides-search.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 class="postHeaderTitle">Enabling Search</h1></header><article><div><span><p>Docusaurus supports search using <a href="https://community.algolia.com/docsearch/">Algolia DocSearch</a>. Once you have set up your site, <a href="https://community.algolia.com/docsearch/">enter your site information</a> to have Algolia crawl your website's documentation pages. Algolia will then send you an API key and index name for your site.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="enabling-the-search-bar"></a><a href="#enabling-the-search-bar" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Enabling the Search Bar</h2>
|
||||
<p>Enter your search-only API key and index name into <code>siteConfig.js</code> in the <code>algolia</code> section to enable search for your site.</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
...
|
||||
algolia: {
|
||||
<span class="hljs-attr">apiKey</span>: <span class="hljs-string">"my-search-only-api-key-1234"</span>,
|
||||
|
|
@ -61,7 +61,7 @@
|
|||
</code></pre>
|
||||
<h2><a class="anchor" aria-hidden="true" id="extra-search-options"></a><a href="#extra-search-options" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Extra Search Options</h2>
|
||||
<p>You can also specify extra <a href="https://community.algolia.com/docsearch/documentation/">search options used by Algolia</a> by using an <code>algoliaOptions</code> field in <code>algolia</code>. This may be useful if you want to provide different search results for the different versions or languages of your docs. Any occurrences of "VERSION" or "LANGUAGE" will be replaced by the version or language of the current page, respectively. More details about search options can be <a href="https://www.algolia.com/doc/api-reference/api-parameters/#overview">found here</a>.</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
...
|
||||
algolia: {
|
||||
...
|
||||
|
|
@ -75,7 +75,7 @@
|
|||
<h2><a class="anchor" aria-hidden="true" id="controlling-the-location-of-the-search-bar"></a><a href="#controlling-the-location-of-the-search-bar" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Controlling the Location of the Search Bar</h2>
|
||||
<p>By default, the search bar will be the rightmost element in the top navigation bar.</p>
|
||||
<p>If you want to change the default location, add the <code>searchBar</code> flag in the <code>headerLinks</code> field of <code>siteConfig.js</code> in your desired location. For example, you may want the search bar in between your internal and external links.</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
...
|
||||
headerLinks: [
|
||||
{...}
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@
|
|||
</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/facebook/docusaurus/edit/master/docs/guides-search.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 class="postHeaderTitle">Enabling Search</h1></header><article><div><span><p>Docusaurus supports search using <a href="https://community.algolia.com/docsearch/">Algolia DocSearch</a>. Once you have set up your site, <a href="https://community.algolia.com/docsearch/">enter your site information</a> to have Algolia crawl your website's documentation pages. Algolia will then send you an API key and index name for your site.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="enabling-the-search-bar"></a><a href="#enabling-the-search-bar" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Enabling the Search Bar</h2>
|
||||
<p>Enter your search-only API key and index name into <code>siteConfig.js</code> in the <code>algolia</code> section to enable search for your site.</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
...
|
||||
algolia: {
|
||||
<span class="hljs-attr">apiKey</span>: <span class="hljs-string">"my-search-only-api-key-1234"</span>,
|
||||
|
|
@ -61,7 +61,7 @@
|
|||
</code></pre>
|
||||
<h2><a class="anchor" aria-hidden="true" id="extra-search-options"></a><a href="#extra-search-options" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Extra Search Options</h2>
|
||||
<p>You can also specify extra <a href="https://community.algolia.com/docsearch/documentation/">search options used by Algolia</a> by using an <code>algoliaOptions</code> field in <code>algolia</code>. This may be useful if you want to provide different search results for the different versions or languages of your docs. Any occurrences of "VERSION" or "LANGUAGE" will be replaced by the version or language of the current page, respectively. More details about search options can be <a href="https://www.algolia.com/doc/api-reference/api-parameters/#overview">found here</a>.</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
...
|
||||
algolia: {
|
||||
...
|
||||
|
|
@ -75,7 +75,7 @@
|
|||
<h2><a class="anchor" aria-hidden="true" id="controlling-the-location-of-the-search-bar"></a><a href="#controlling-the-location-of-the-search-bar" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Controlling the Location of the Search Bar</h2>
|
||||
<p>By default, the search bar will be the rightmost element in the top navigation bar.</p>
|
||||
<p>If you want to change the default location, add the <code>searchBar</code> flag in the <code>headerLinks</code> field of <code>siteConfig.js</code> in your desired location. For example, you may want the search bar in between your internal and external links.</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
...
|
||||
headerLinks: [
|
||||
{...}
|
||||
|
|
|
|||
|
|
@ -66,7 +66,7 @@
|
|||
<p><code>headerIcon</code> - url for icon used in header navigation bar.</p>
|
||||
<p><code>headerLinks</code> - Links that will be used in the header navigation bar. The <code>label</code> field of each object will be the link text and will also be translated for each language.</p>
|
||||
<p>Example Usage:</p>
|
||||
<pre><code class="hljs css languages- js">headerLinks: [
|
||||
<pre><code class="hljs css languages-js">headerLinks: [
|
||||
<span class="hljs-comment">// Links to document with id doc1 for current language/version</span>
|
||||
{ <span class="hljs-attr">doc</span>: <span class="hljs-string">"doc1"</span>, <span class="hljs-attr">label</span>: <span class="hljs-string">"Getting Started"</span> },
|
||||
<span class="hljs-comment">// Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language</span>
|
||||
|
|
@ -97,9 +97,9 @@
|
|||
<p><code>blogSidebarCount</code> - Control the number of blog posts that show up in the sidebar. See the <a href="/docs/en/1.0.12/adding-blog#changing-how-many-blog-posts-show-on-sidebar">adding a blog docs</a> for more information.</p>
|
||||
<p><code>cname</code> - The CNAME for your website. It will go into a <code>CNAME</code> file when your site it built.</p>
|
||||
<p><code>customDocsPath</code> - By default, Docusaurus expects your documentation to be in a directory called <code>docs</code>. This directory is at the same level as the <code>website</code> directory (i.e., not inside the <code>website</code> directory). You can specify a custom path to your documentation with this field. <strong>Note that all of your documentation <code>*.md</code> files must still reside in a flat hierarchy. You cannot have your documents in nested directories</strong>.</p>
|
||||
<pre><code class="hljs css languages- js">customDocsPath: <span class="hljs-string">"docs/site"</span>
|
||||
<pre><code class="hljs css languages-js">customDocsPath: <span class="hljs-string">"docs/site"</span>
|
||||
</code></pre>
|
||||
<pre><code class="hljs css languages- js">customDocsPath: <span class="hljs-string">"website-docs"</span>
|
||||
<pre><code class="hljs css languages-js">customDocsPath: <span class="hljs-string">"website-docs"</span>
|
||||
</code></pre>
|
||||
<p><code>disableHeaderTitle</code> - An option to disable showing the title in the header next to the header icon. Exclude this field to keep the header as normal, otherwise set to <code>true</code>.</p>
|
||||
<p><code>disableTitleTagline</code> - An option to disable showing the tagline in the title of main pages. Exclude this field to keep page titles as <code>Title • Tagline</code>. Set to <code>true</code> to make page titles just <code>Title</code>.</p>
|
||||
|
|
|
|||
|
|
@ -66,7 +66,7 @@
|
|||
<p><code>headerIcon</code> - url for icon used in header navigation bar.</p>
|
||||
<p><code>headerLinks</code> - Links that will be used in the header navigation bar. The <code>label</code> field of each object will be the link text and will also be translated for each language.</p>
|
||||
<p>Example Usage:</p>
|
||||
<pre><code class="hljs css languages- js">headerLinks: [
|
||||
<pre><code class="hljs css languages-js">headerLinks: [
|
||||
<span class="hljs-comment">// Links to document with id doc1 for current language/version</span>
|
||||
{ <span class="hljs-attr">doc</span>: <span class="hljs-string">"doc1"</span>, <span class="hljs-attr">label</span>: <span class="hljs-string">"Getting Started"</span> },
|
||||
<span class="hljs-comment">// Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language</span>
|
||||
|
|
@ -97,9 +97,9 @@
|
|||
<p><code>blogSidebarCount</code> - Control the number of blog posts that show up in the sidebar. See the <a href="/docs/en/1.0.12/adding-blog#changing-how-many-blog-posts-show-on-sidebar">adding a blog docs</a> for more information.</p>
|
||||
<p><code>cname</code> - The CNAME for your website. It will go into a <code>CNAME</code> file when your site it built.</p>
|
||||
<p><code>customDocsPath</code> - By default, Docusaurus expects your documentation to be in a directory called <code>docs</code>. This directory is at the same level as the <code>website</code> directory (i.e., not inside the <code>website</code> directory). You can specify a custom path to your documentation with this field. <strong>Note that all of your documentation <code>*.md</code> files must still reside in a flat hierarchy. You cannot have your documents in nested directories</strong>.</p>
|
||||
<pre><code class="hljs css languages- js">customDocsPath: <span class="hljs-string">"docs/site"</span>
|
||||
<pre><code class="hljs css languages-js">customDocsPath: <span class="hljs-string">"docs/site"</span>
|
||||
</code></pre>
|
||||
<pre><code class="hljs css languages- js">customDocsPath: <span class="hljs-string">"website-docs"</span>
|
||||
<pre><code class="hljs css languages-js">customDocsPath: <span class="hljs-string">"website-docs"</span>
|
||||
</code></pre>
|
||||
<p><code>disableHeaderTitle</code> - An option to disable showing the title in the header next to the header icon. Exclude this field to keep the header as normal, otherwise set to <code>true</code>.</p>
|
||||
<p><code>disableTitleTagline</code> - An option to disable showing the tagline in the title of main pages. Exclude this field to keep page titles as <code>Title • Tagline</code>. Set to <code>true</code> to make page titles just <code>Title</code>.</p>
|
||||
|
|
|
|||
|
|
@ -51,7 +51,7 @@
|
|||
<p>After <a href="/docs/en/1.0.12/installation">installation</a> and <a href="/docs/en/1.0.12/site-preparation">preparation</a>, much of the work to create a basic site for your docs is already complete.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="site-structure"></a><a href="#site-structure" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Site Structure</h2>
|
||||
<p>Your site structure looks like the following:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs
|
||||
└── website
|
||||
│ └── blog
|
||||
|
|
|
|||
|
|
@ -51,7 +51,7 @@
|
|||
<p>After <a href="/docs/en/1.0.12/installation">installation</a> and <a href="/docs/en/1.0.12/site-preparation">preparation</a>, much of the work to create a basic site for your docs is already complete.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="site-structure"></a><a href="#site-structure" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Site Structure</h2>
|
||||
<p>Your site structure looks like the following:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs
|
||||
└── website
|
||||
│ └── blog
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@
|
|||
</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/facebook/docusaurus/edit/master/docs/getting-started-preparation.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 class="postHeaderTitle">Site Preparation</h1></header><article><div><span><p>After <a href="/docs/en/1.0.12/installation">installing Docusaurus</a>, you now have a skeleton to work from for your specific website. The following discusses the rest of the Docusaurus structure in order for you to prepare your site.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="directory-structure"></a><a href="#directory-structure" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Directory Structure</h2>
|
||||
<p>As shown after you <a href="/docs/en/1.0.12/installation">installed Docusaurus</a>, the initialization script created a directory structure similar to:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs-examples-from-docusaurus
|
||||
│ └── doc1.md
|
||||
│ └── doc2.md
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@
|
|||
</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/facebook/docusaurus/edit/master/docs/getting-started-preparation.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 class="postHeaderTitle">Site Preparation</h1></header><article><div><span><p>After <a href="/docs/en/1.0.12/installation">installing Docusaurus</a>, you now have a skeleton to work from for your specific website. The following discusses the rest of the Docusaurus structure in order for you to prepare your site.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="directory-structure"></a><a href="#directory-structure" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Directory Structure</h2>
|
||||
<p>As shown after you <a href="/docs/en/1.0.12/installation">installed Docusaurus</a>, the initialization script created a directory structure similar to:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs-examples-from-docusaurus
|
||||
│ └── doc1.md
|
||||
│ └── doc2.md
|
||||
|
|
|
|||
|
|
@ -76,7 +76,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<p>Pages allow you to customize layout and specific content of pages like a custom index page or help page.</p>
|
||||
<p>Pages with text that you want translated should be placed in <code>website/pages/en</code> folder.</p>
|
||||
<p>Wrap strings you want translated in a <code><translate></code> tag, and add the following <code>require</code> statement to the top of the file:</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token operator">...</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token operator">...</span>
|
||||
<span class="token keyword">const</span> translate <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">"../../server/translate.js"</span><span class="token punctuation">)</span><span class="token punctuation">.</span>translate<span class="token punctuation">;</span>
|
||||
<span class="token operator">...</span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>h2</span><span class="token punctuation">></span></span>
|
||||
|
|
@ -85,7 +85,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<span class="token operator">...</span>
|
||||
</code></pre>
|
||||
<p>You can also include an optional description attribute to give more context to a translator about how to translate the string:</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span> <span class="token attr-name">desc</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>flower, not verb<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Rose<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
</code></pre>
|
||||
|
|
@ -95,7 +95,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<h2><a class="anchor" aria-hidden="true" id="gathering-strings-to-translate"></a><a href="#gathering-strings-to-translate" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Gathering Strings to Translate</h2>
|
||||
<p>The strings within localized Pages must be extracted and provided to Crowdin.</p>
|
||||
<p>Add the following script to your <code>website/package.json</code> file, if it does not exist already:</p>
|
||||
<pre><code class="hljs css languages- json">...
|
||||
<pre><code class="hljs css languages-json">...
|
||||
"scripts": {
|
||||
"write-translations": "docusaurus-write-translations"
|
||||
},
|
||||
|
|
@ -133,7 +133,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
</blockquote>
|
||||
<p>The example below can be automatically generated by the Docusaurus cli with the <code>examples</code> script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.</p>
|
||||
<p>Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.</p>
|
||||
<pre><code class="hljs css languages- yaml"><span class="hljs-attr">project_identifier_env:</span> <span class="hljs-string">CROWDIN_DOCUSAURUS_PROJECT_ID</span>
|
||||
<pre><code class="hljs css languages-yaml"><span class="hljs-attr">project_identifier_env:</span> <span class="hljs-string">CROWDIN_DOCUSAURUS_PROJECT_ID</span>
|
||||
<span class="hljs-attr">api_key_env:</span> <span class="hljs-string">CROWDIN_DOCUSAURUS_API_KEY</span>
|
||||
<span class="hljs-attr">base_path:</span> <span class="hljs-string">"./"</span>
|
||||
<span class="hljs-attr">preserve_hierarchy:</span> <span class="hljs-literal">true</span>
|
||||
|
|
@ -158,7 +158,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<h3><a class="anchor" aria-hidden="true" id="setup-the-crowdin-scripts"></a><a href="#setup-the-crowdin-scripts" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Setup the Crowdin Scripts</h3>
|
||||
<p>You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in <code>/docs</code> as well as translatable strings in <code>website/i18n/en.json</code>. (These strings can be generated by running <code>yarn write-translations</code>.)</p>
|
||||
<p>You can add the following to your <code>package.json</code> to manually trigger Crowdin.</p>
|
||||
<pre><code class="hljs css languages- json">"scripts": {
|
||||
<pre><code class="hljs css languages-json">"scripts": {
|
||||
"crowdin-upload": "crowdin --config ../crowdin.yaml upload sources --auto-update -b master",
|
||||
"crowdin-download": "crowdin --config ../crowdin.yaml download -b master"
|
||||
},
|
||||
|
|
@ -183,7 +183,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<h3><a class="anchor" aria-hidden="true" id="automated-file-sync-using-circleci"></a><a href="#automated-file-sync-using-circleci" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Automated File Sync Using CircleCI</h3>
|
||||
<p>You can automate pulling down and uploading translations for your files using the <a href="https://circleci.com">CircleCI</a> web continuous integration service.</p>
|
||||
<p>First, update the <code>circle.yml</code> file in your project directory to include steps to upload English files to be translated and download translated files using the Crowdin CLI. Here is an example <code>circle.yml</code> file:</p>
|
||||
<pre><code class="hljs css languages- yaml"><span class="hljs-attr">machine:</span>
|
||||
<pre><code class="hljs css languages-yaml"><span class="hljs-attr">machine:</span>
|
||||
<span class="hljs-attr"> node:</span>
|
||||
<span class="hljs-attr"> version:</span> <span class="hljs-number">6.10</span><span class="hljs-number">.3</span>
|
||||
<span class="hljs-attr"> npm:</span>
|
||||
|
|
@ -219,7 +219,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<p>If you wish to use Crowdin on your machine locally, you can install the <a href="https://support.crowdin.com/cli-tool/">Crowdin CLI tool</a> and run the same commands found in the <code>circle.yaml</code> file. The only difference is that you must set <code>project_identifier</code> and <code>api_key</code> values in the <code>crowdin.yaml</code> file since you will not have Circle environment variables set up.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="versioned-translations"></a><a href="#versioned-translations" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Versioned Translations</h2>
|
||||
<p>If you wish to have translation and versioning for your documentation, add the following section to the end of your <code>crowdin.yaml</code> file:</p>
|
||||
<pre><code class="hljs css languages- yaml"><span class="hljs-bullet"> -</span>
|
||||
<pre><code class="hljs css languages-yaml"><span class="hljs-bullet"> -</span>
|
||||
<span class="hljs-attr"> source:</span> <span class="hljs-string">'/website/versioned_docs/**/*.md'</span>
|
||||
<span class="hljs-attr"> translation:</span> <span class="hljs-string">'/website/translated_docs/%locale%/**/%original_file_name%'</span>
|
||||
<span class="hljs-attr"> languages_mapping:</span> <span class="hljs-meta">*anchor</span>
|
||||
|
|
|
|||
|
|
@ -76,7 +76,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<p>Pages allow you to customize layout and specific content of pages like a custom index page or help page.</p>
|
||||
<p>Pages with text that you want translated should be placed in <code>website/pages/en</code> folder.</p>
|
||||
<p>Wrap strings you want translated in a <code><translate></code> tag, and add the following <code>require</code> statement to the top of the file:</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token operator">...</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token operator">...</span>
|
||||
<span class="token keyword">const</span> translate <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">"../../server/translate.js"</span><span class="token punctuation">)</span><span class="token punctuation">.</span>translate<span class="token punctuation">;</span>
|
||||
<span class="token operator">...</span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>h2</span><span class="token punctuation">></span></span>
|
||||
|
|
@ -85,7 +85,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<span class="token operator">...</span>
|
||||
</code></pre>
|
||||
<p>You can also include an optional description attribute to give more context to a translator about how to translate the string:</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span> <span class="token attr-name">desc</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>flower, not verb<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Rose<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
</code></pre>
|
||||
|
|
@ -95,7 +95,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<h2><a class="anchor" aria-hidden="true" id="gathering-strings-to-translate"></a><a href="#gathering-strings-to-translate" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Gathering Strings to Translate</h2>
|
||||
<p>The strings within localized Pages must be extracted and provided to Crowdin.</p>
|
||||
<p>Add the following script to your <code>website/package.json</code> file, if it does not exist already:</p>
|
||||
<pre><code class="hljs css languages- json">...
|
||||
<pre><code class="hljs css languages-json">...
|
||||
"scripts": {
|
||||
"write-translations": "docusaurus-write-translations"
|
||||
},
|
||||
|
|
@ -133,7 +133,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
</blockquote>
|
||||
<p>The example below can be automatically generated by the Docusaurus cli with the <code>examples</code> script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.</p>
|
||||
<p>Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.</p>
|
||||
<pre><code class="hljs css languages- yaml"><span class="hljs-attr">project_identifier_env:</span> <span class="hljs-string">CROWDIN_DOCUSAURUS_PROJECT_ID</span>
|
||||
<pre><code class="hljs css languages-yaml"><span class="hljs-attr">project_identifier_env:</span> <span class="hljs-string">CROWDIN_DOCUSAURUS_PROJECT_ID</span>
|
||||
<span class="hljs-attr">api_key_env:</span> <span class="hljs-string">CROWDIN_DOCUSAURUS_API_KEY</span>
|
||||
<span class="hljs-attr">base_path:</span> <span class="hljs-string">"./"</span>
|
||||
<span class="hljs-attr">preserve_hierarchy:</span> <span class="hljs-literal">true</span>
|
||||
|
|
@ -158,7 +158,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<h3><a class="anchor" aria-hidden="true" id="setup-the-crowdin-scripts"></a><a href="#setup-the-crowdin-scripts" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Setup the Crowdin Scripts</h3>
|
||||
<p>You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in <code>/docs</code> as well as translatable strings in <code>website/i18n/en.json</code>. (These strings can be generated by running <code>yarn write-translations</code>.)</p>
|
||||
<p>You can add the following to your <code>package.json</code> to manually trigger Crowdin.</p>
|
||||
<pre><code class="hljs css languages- json">"scripts": {
|
||||
<pre><code class="hljs css languages-json">"scripts": {
|
||||
"crowdin-upload": "crowdin --config ../crowdin.yaml upload sources --auto-update -b master",
|
||||
"crowdin-download": "crowdin --config ../crowdin.yaml download -b master"
|
||||
},
|
||||
|
|
@ -183,7 +183,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<h3><a class="anchor" aria-hidden="true" id="automated-file-sync-using-circleci"></a><a href="#automated-file-sync-using-circleci" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Automated File Sync Using CircleCI</h3>
|
||||
<p>You can automate pulling down and uploading translations for your files using the <a href="https://circleci.com">CircleCI</a> web continuous integration service.</p>
|
||||
<p>First, update the <code>circle.yml</code> file in your project directory to include steps to upload English files to be translated and download translated files using the Crowdin CLI. Here is an example <code>circle.yml</code> file:</p>
|
||||
<pre><code class="hljs css languages- yaml"><span class="hljs-attr">machine:</span>
|
||||
<pre><code class="hljs css languages-yaml"><span class="hljs-attr">machine:</span>
|
||||
<span class="hljs-attr"> node:</span>
|
||||
<span class="hljs-attr"> version:</span> <span class="hljs-number">6.10</span><span class="hljs-number">.3</span>
|
||||
<span class="hljs-attr"> npm:</span>
|
||||
|
|
@ -219,7 +219,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<p>If you wish to use Crowdin on your machine locally, you can install the <a href="https://support.crowdin.com/cli-tool/">Crowdin CLI tool</a> and run the same commands found in the <code>circle.yaml</code> file. The only difference is that you must set <code>project_identifier</code> and <code>api_key</code> values in the <code>crowdin.yaml</code> file since you will not have Circle environment variables set up.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="versioned-translations"></a><a href="#versioned-translations" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Versioned Translations</h2>
|
||||
<p>If you wish to have translation and versioning for your documentation, add the following section to the end of your <code>crowdin.yaml</code> file:</p>
|
||||
<pre><code class="hljs css languages- yaml"><span class="hljs-bullet"> -</span>
|
||||
<pre><code class="hljs css languages-yaml"><span class="hljs-bullet"> -</span>
|
||||
<span class="hljs-attr"> source:</span> <span class="hljs-string">'/website/versioned_docs/**/*.md'</span>
|
||||
<span class="hljs-attr"> translation:</span> <span class="hljs-string">'/website/translated_docs/%locale%/**/%original_file_name%'</span>
|
||||
<span class="hljs-attr"> languages_mapping:</span> <span class="hljs-meta">*anchor</span>
|
||||
|
|
|
|||
|
|
@ -50,19 +50,19 @@
|
|||
</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/facebook/docusaurus/edit/master/docs/guides-versioning.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 class="postHeaderTitle">Versioning</h1></header><article><div><span><p>You 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" aria-hidden="true" id="how-to-create-new-versions"></a><a href="#how-to-create-new-versions" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>How to Create New Versions</h2>
|
||||
<p>Run the following script to generate a starter versions page listing all the site versions:</p>
|
||||
<pre><code class="hljs css languages- bash">yarn examples versions
|
||||
<pre><code class="hljs css languages-bash">yarn examples versions
|
||||
</code></pre>
|
||||
<p>This creates the <code>pages/en/versions.js</code> file.</p>
|
||||
<p>You can edit this file later on to customize how you display the versions.</p>
|
||||
<p>Add the following script to your <code>package.json</code> file if it doesn't already exist:</p>
|
||||
<pre><code class="hljs css languages- json">...
|
||||
<pre><code class="hljs css languages-json">...
|
||||
"scripts": {
|
||||
"version": "docusaurus-version"
|
||||
},
|
||||
...
|
||||
</code></pre>
|
||||
<p>Run the script with a command line argument of the version you wish to create. e.g.,</p>
|
||||
<pre><code class="hljs css languages- bash">yarn run version 1.0.0
|
||||
<pre><code class="hljs css languages-bash">yarn run version 1.0.0
|
||||
</code></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 <code>1.0.0</code> as the version number, version <code>1.0.0</code> is considered the latest release version for your project. The site will display the version number next to the title in the header. This version number links to a versions page that you created earlier.</p>
|
||||
|
|
@ -93,14 +93,14 @@
|
|||
<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" aria-hidden="true" id="renaming-existing-versions"></a><a href="#renaming-existing-versions" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Renaming Existing Versions</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><code class="hljs css languages- json">...
|
||||
<pre><code class="hljs css languages-json">...
|
||||
"scripts": {
|
||||
"rename-version": "docusaurus-rename-version"
|
||||
},
|
||||
...
|
||||
</code></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><code class="hljs css languages- bash">yarn run rename-version 1.0.0 1.0.1
|
||||
<pre><code class="hljs css languages-bash">yarn run rename-version 1.0.0 1.0.1
|
||||
</code></pre>
|
||||
<h2><a class="anchor" aria-hidden="true" id="versioning-and-translations"></a><a href="#versioning-and-translations" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Versioning and Translations</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="/docs/en/1.0.12/translation">translations guide</a>.</p>
|
||||
|
|
|
|||
|
|
@ -50,19 +50,19 @@
|
|||
</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/facebook/docusaurus/edit/master/docs/guides-versioning.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 class="postHeaderTitle">Versioning</h1></header><article><div><span><p>You 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" aria-hidden="true" id="how-to-create-new-versions"></a><a href="#how-to-create-new-versions" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>How to Create New Versions</h2>
|
||||
<p>Run the following script to generate a starter versions page listing all the site versions:</p>
|
||||
<pre><code class="hljs css languages- bash">yarn examples versions
|
||||
<pre><code class="hljs css languages-bash">yarn examples versions
|
||||
</code></pre>
|
||||
<p>This creates the <code>pages/en/versions.js</code> file.</p>
|
||||
<p>You can edit this file later on to customize how you display the versions.</p>
|
||||
<p>Add the following script to your <code>package.json</code> file if it doesn't already exist:</p>
|
||||
<pre><code class="hljs css languages- json">...
|
||||
<pre><code class="hljs css languages-json">...
|
||||
"scripts": {
|
||||
"version": "docusaurus-version"
|
||||
},
|
||||
...
|
||||
</code></pre>
|
||||
<p>Run the script with a command line argument of the version you wish to create. e.g.,</p>
|
||||
<pre><code class="hljs css languages- bash">yarn run version 1.0.0
|
||||
<pre><code class="hljs css languages-bash">yarn run version 1.0.0
|
||||
</code></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 <code>1.0.0</code> as the version number, version <code>1.0.0</code> is considered the latest release version for your project. The site will display the version number next to the title in the header. This version number links to a versions page that you created earlier.</p>
|
||||
|
|
@ -93,14 +93,14 @@
|
|||
<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" aria-hidden="true" id="renaming-existing-versions"></a><a href="#renaming-existing-versions" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Renaming Existing Versions</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><code class="hljs css languages- json">...
|
||||
<pre><code class="hljs css languages-json">...
|
||||
"scripts": {
|
||||
"rename-version": "docusaurus-rename-version"
|
||||
},
|
||||
...
|
||||
</code></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><code class="hljs css languages- bash">yarn run rename-version 1.0.0 1.0.1
|
||||
<pre><code class="hljs css languages-bash">yarn run rename-version 1.0.0 1.0.1
|
||||
</code></pre>
|
||||
<h2><a class="anchor" aria-hidden="true" id="versioning-and-translations"></a><a href="#versioning-and-translations" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Versioning and Translations</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="/docs/en/1.0.12/translation">translations guide</a>.</p>
|
||||
|
|
|
|||
|
|
@ -59,7 +59,7 @@
|
|||
<h3><a class="anchor" aria-hidden="true" id="complibrarymarkdownblock"></a><a href="#complibrarymarkdownblock" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><code>CompLibrary.MarkdownBlock</code></h3>
|
||||
<p>A React component that parses markdown and renders to HTML.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token keyword">const</span> MarkdownBlock <span class="token operator">=</span> CompLibrary<span class="token punctuation">.</span>MarkdownBlock<span class="token punctuation">;</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token keyword">const</span> MarkdownBlock <span class="token operator">=</span> CompLibrary<span class="token punctuation">.</span>MarkdownBlock<span class="token punctuation">;</span>
|
||||
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>MarkdownBlock</span><span class="token punctuation">></span></span>
|
||||
<span class="token punctuation">[</span>Markdown syntax <span class="token keyword">for</span> a link<span class="token punctuation">]</span><span class="token punctuation">(</span>http<span class="token punctuation">:</span><span class="token operator">/</span><span class="token operator">/</span>www<span class="token punctuation">.</span>example<span class="token punctuation">.</span>com<span class="token punctuation">)</span>
|
||||
|
|
@ -79,7 +79,7 @@
|
|||
</tbody>
|
||||
</table>
|
||||
<p><strong>Example</strong></p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>Container</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>Container</span>
|
||||
<span class="token attr-name">padding</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">[</span><span class="token string">'bottom'</span><span class="token punctuation">,</span> <span class="token string">'top'</span><span class="token punctuation">]</span><span class="token punctuation">}</span></span>
|
||||
<span class="token attr-name">background</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>light<span class="token punctuation">"</span></span>
|
||||
<span class="token attr-name">className</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>myCustomClass<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
|
|
@ -144,19 +144,19 @@
|
|||
<h2><a class="anchor" aria-hidden="true" id="translating-strings"></a><a href="#translating-strings" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Translating Strings</h2>
|
||||
<p>When translations are enabled, any pages inside <code>website/pages/en</code> will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the <code>languages.js</code> file. E.g. The url for a French page of <code>website/pages/en/help.js</code> would be found at <code>${baseUrl}fr/help.html</code>.</p>
|
||||
<p>When writing pages that you wish to translate, wrap any strings to be translated inside a <code><translate></code> tag. e.g.,</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span><span class="token punctuation">></span></span><span class="token constant">I</span> like translations<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>p</span><span class="token punctuation">></span></span>
|
||||
</code></pre>
|
||||
<p>You can also provide an optional description attribute to provide context for translators. e.g,</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>a</span> <span class="token attr-name">href</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>/community<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>a</span> <span class="token attr-name">href</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>/community<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span> <span class="token attr-name">desc</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>Footer link to page referring to community GitHub and Slack<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
Community
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>a</span><span class="token punctuation">></span></span>
|
||||
</code></pre>
|
||||
<p>Add the following require statement as well:</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> translate = <span class="hljs-built_in">require</span>(<span class="hljs-string">'../../server/translate.js'</span>).translate;
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> translate = <span class="hljs-built_in">require</span>(<span class="hljs-string">'../../server/translate.js'</span>).translate;
|
||||
</code></pre>
|
||||
<p>Note that this path is valid for files inside <code>pages/en</code> and should be adjusted accordingly if files are in different locations, as discussed <a href="#page-require-paths">above</a>.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="using-static-assets"></a><a href="#using-static-assets" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Using Static Assets</h2>
|
||||
|
|
|
|||
|
|
@ -59,7 +59,7 @@
|
|||
<h3><a class="anchor" aria-hidden="true" id="complibrarymarkdownblock"></a><a href="#complibrarymarkdownblock" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><code>CompLibrary.MarkdownBlock</code></h3>
|
||||
<p>A React component that parses markdown and renders to HTML.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token keyword">const</span> MarkdownBlock <span class="token operator">=</span> CompLibrary<span class="token punctuation">.</span>MarkdownBlock<span class="token punctuation">;</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token keyword">const</span> MarkdownBlock <span class="token operator">=</span> CompLibrary<span class="token punctuation">.</span>MarkdownBlock<span class="token punctuation">;</span>
|
||||
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>MarkdownBlock</span><span class="token punctuation">></span></span>
|
||||
<span class="token punctuation">[</span>Markdown syntax <span class="token keyword">for</span> a link<span class="token punctuation">]</span><span class="token punctuation">(</span>http<span class="token punctuation">:</span><span class="token operator">/</span><span class="token operator">/</span>www<span class="token punctuation">.</span>example<span class="token punctuation">.</span>com<span class="token punctuation">)</span>
|
||||
|
|
@ -79,7 +79,7 @@
|
|||
</tbody>
|
||||
</table>
|
||||
<p><strong>Example</strong></p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>Container</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>Container</span>
|
||||
<span class="token attr-name">padding</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">[</span><span class="token string">'bottom'</span><span class="token punctuation">,</span> <span class="token string">'top'</span><span class="token punctuation">]</span><span class="token punctuation">}</span></span>
|
||||
<span class="token attr-name">background</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>light<span class="token punctuation">"</span></span>
|
||||
<span class="token attr-name">className</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>myCustomClass<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
|
|
@ -144,19 +144,19 @@
|
|||
<h2><a class="anchor" aria-hidden="true" id="translating-strings"></a><a href="#translating-strings" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Translating Strings</h2>
|
||||
<p>When translations are enabled, any pages inside <code>website/pages/en</code> will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the <code>languages.js</code> file. E.g. The url for a French page of <code>website/pages/en/help.js</code> would be found at <code>${baseUrl}fr/help.html</code>.</p>
|
||||
<p>When writing pages that you wish to translate, wrap any strings to be translated inside a <code><translate></code> tag. e.g.,</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span><span class="token punctuation">></span></span><span class="token constant">I</span> like translations<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>p</span><span class="token punctuation">></span></span>
|
||||
</code></pre>
|
||||
<p>You can also provide an optional description attribute to provide context for translators. e.g,</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>a</span> <span class="token attr-name">href</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>/community<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>a</span> <span class="token attr-name">href</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>/community<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span> <span class="token attr-name">desc</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>Footer link to page referring to community GitHub and Slack<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
Community
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>a</span><span class="token punctuation">></span></span>
|
||||
</code></pre>
|
||||
<p>Add the following require statement as well:</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> translate = <span class="hljs-built_in">require</span>(<span class="hljs-string">'../../server/translate.js'</span>).translate;
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> translate = <span class="hljs-built_in">require</span>(<span class="hljs-string">'../../server/translate.js'</span>).translate;
|
||||
</code></pre>
|
||||
<p>Note that this path is valid for files inside <code>pages/en</code> and should be adjusted accordingly if files are in different locations, as discussed <a href="#page-require-paths">above</a>.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="using-static-assets"></a><a href="#using-static-assets" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Using Static Assets</h2>
|
||||
|
|
|
|||
|
|
@ -100,7 +100,7 @@
|
|||
<li><code>USE_SSH</code>: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.</li>
|
||||
</ul>
|
||||
<p>e.g.,</p>
|
||||
<pre><code class="hljs css languages- bash">GIT_USER=docusaurus-bot USE_SSH=<span class="hljs-literal">true</span> yarn run publish-gh-pages
|
||||
<pre><code class="hljs css languages-bash">GIT_USER=docusaurus-bot USE_SSH=<span class="hljs-literal">true</span> yarn run publish-gh-pages
|
||||
</code></pre>
|
||||
<p>The following environment variables are <a href="https://circleci.com/docs/1.0/environment-variables/">set by CircleCI</a> during the build process.</p>
|
||||
<ul>
|
||||
|
|
|
|||
|
|
@ -100,7 +100,7 @@
|
|||
<li><code>USE_SSH</code>: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.</li>
|
||||
</ul>
|
||||
<p>e.g.,</p>
|
||||
<pre><code class="hljs css languages- bash">GIT_USER=docusaurus-bot USE_SSH=<span class="hljs-literal">true</span> yarn run publish-gh-pages
|
||||
<pre><code class="hljs css languages-bash">GIT_USER=docusaurus-bot USE_SSH=<span class="hljs-literal">true</span> yarn run publish-gh-pages
|
||||
</code></pre>
|
||||
<p>The following environment variables are <a href="https://circleci.com/docs/1.0/environment-variables/">set by CircleCI</a> during the build process.</p>
|
||||
<ul>
|
||||
|
|
|
|||
|
|
@ -53,7 +53,7 @@
|
|||
<p>You can <a href="/docs/en/1.0.13/site-preparation#verifying-installation">start</a> your local server and go to <code>http://localhost:3000</code> to see what the example home page looks like. From there, edit the <code>website/pages/en/index.js</code> file and its various components to use the images and text you want for your project.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="adding-other-custom-pages"></a><a href="#adding-other-custom-pages" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Adding Other Custom Pages</h2>
|
||||
<p>Docusaurus provides some simple example pages in the <code>website/pages/en</code> directory, including <code>index.js</code>, <code>users.js</code>, and <code>help.js</code>. These are good examples to showcase how to create a custom page for Docusaurus.</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs
|
||||
└── website
|
||||
│ └── blog
|
||||
|
|
@ -85,7 +85,7 @@
|
|||
<p>Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.</p>
|
||||
<p>Your footer will automatically get applied to all pages on your site, including docs and blog posts. The sole exception to this is any static html pages you include.</p>
|
||||
<p>If you do not want a footer for your site, change the <code>render</code> function of <code>core/Footer.js</code> to return <code>null</code>. e.g.,</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token keyword">const</span> React <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">"react"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token keyword">const</span> React <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">"react"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token keyword">class</span> <span class="token class-name">Footer</span> <span class="token keyword">extends</span> <span class="token class-name">React<span class="token punctuation">.</span>Component</span> <span class="token punctuation">{</span>
|
||||
<span class="token function">render</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
|
|
|
|||
|
|
@ -53,7 +53,7 @@
|
|||
<p>You can <a href="/docs/en/1.0.13/site-preparation#verifying-installation">start</a> your local server and go to <code>http://localhost:3000</code> to see what the example home page looks like. From there, edit the <code>website/pages/en/index.js</code> file and its various components to use the images and text you want for your project.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="adding-other-custom-pages"></a><a href="#adding-other-custom-pages" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Adding Other Custom Pages</h2>
|
||||
<p>Docusaurus provides some simple example pages in the <code>website/pages/en</code> directory, including <code>index.js</code>, <code>users.js</code>, and <code>help.js</code>. These are good examples to showcase how to create a custom page for Docusaurus.</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs
|
||||
└── website
|
||||
│ └── blog
|
||||
|
|
@ -85,7 +85,7 @@
|
|||
<p>Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.</p>
|
||||
<p>Your footer will automatically get applied to all pages on your site, including docs and blog posts. The sole exception to this is any static html pages you include.</p>
|
||||
<p>If you do not want a footer for your site, change the <code>render</code> function of <code>core/Footer.js</code> to return <code>null</code>. e.g.,</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token keyword">const</span> React <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">"react"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token keyword">const</span> React <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">"react"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token keyword">class</span> <span class="token class-name">Footer</span> <span class="token keyword">extends</span> <span class="token class-name">React<span class="token punctuation">.</span>Component</span> <span class="token punctuation">{</span>
|
||||
<span class="token function">render</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
|
|
|
|||
|
|
@ -55,7 +55,7 @@
|
|||
<p><code>hide_title</code>: Whether to hide the title at the top of the doc.</p>
|
||||
<p><code>sidebar_label</code>: The text shown in the document sidebar for this document. If this field is not present, the document's <code>sidebar_label</code> will default to its <code>title</code>.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
id: doc1
|
||||
title: My Document
|
||||
<span class="hljs-section">sidebar_label: Document
|
||||
|
|
@ -63,7 +63,7 @@ title: My Document
|
|||
</code></pre>
|
||||
<p>Versioned documents have their ids altered to include the version number when they get copied. The new <code>id</code> is <code>version-${version}-${id}</code> where <code>${version}</code> is the version number of that document and <code>${id}</code> is the original <code>id</code>. Additionally, versioned documents get an added <code>original_id</code> field with the original document id.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
id: version-1.0.0-doc1
|
||||
title: My Document
|
||||
sidebar_label: Document
|
||||
|
|
@ -72,7 +72,7 @@ sidebar_label: Document
|
|||
</code></pre>
|
||||
<p><code>custom_edit_url</code>: The url for editing this document. If this field is not present, the document's edit url will fallback to <code>editUrl</code> from optional fields of <code>siteConfig.js</code>. See <a href="site-config.md">siteConfig.js</a> docs for more information.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
id: doc-markdown
|
||||
title: Markdown Features
|
||||
<span class="hljs-section">custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
|
||||
|
|
@ -85,7 +85,7 @@ title: Markdown Features
|
|||
<p><code>authorURL</code>: A page to link to when a site user clicks the author's name. If this field is omitted, the author's name will not link to anything.</p>
|
||||
<p><code>authorFBID</code>: The author's Facebook id, used only to get the author's profile picture to display with the blog post. If this field is omitted, no author picture will be shown for the blog post.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
title: My First Blog Post
|
||||
author: Frank Li
|
||||
authorURL: http://twitter.com/franchementli
|
||||
|
|
@ -97,20 +97,20 @@ authorURL: http://twitter.com/franchementli
|
|||
<h3><a class="anchor" aria-hidden="true" id="linking-other-documents"></a><a href="#linking-other-documents" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Linking other Documents</h3>
|
||||
<p>You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- markdown">[<span class="hljs-string">This links to another document</span>](<span class="hljs-link">other-document.md</span>)
|
||||
<pre><code class="hljs css languages-markdown">[<span class="hljs-string">This links to another document</span>](<span class="hljs-link">other-document.md</span>)
|
||||
</code></pre>
|
||||
<p>This markdown will automatically get converted into a link to <code>/docs/other-document.html</code> (or the appropriately translated/versioned link) once it gets rendered.</p>
|
||||
<p>This can help when you want to navigate through docs on GitHub since the links there will be functional links to other documents (still on GitHub), but the documents will have the correct html links when they get rendered.</p>
|
||||
<h3><a class="anchor" aria-hidden="true" id="linking-to-images-and-other-assets"></a><a href="#linking-to-images-and-other-assets" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Linking to Images and Other Assets</h3>
|
||||
<p>Static assets can be linked to in the same way that documents are, using relative urls. Static assets used in documents and blogs should go into <code>docs/assets</code> and <code>website/blog/assets</code>, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- markdown">![<span class="hljs-string">alt-text</span>](<span class="hljs-link">/docs/assets/doc-image.png</span>)
|
||||
<pre><code class="hljs css languages-markdown">![<span class="hljs-string">alt-text</span>](<span class="hljs-link">/docs/assets/doc-image.png</span>)
|
||||
</code></pre>
|
||||
<h3><a class="anchor" aria-hidden="true" id="generating-table-of-contents"></a><a href="#generating-table-of-contents" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Generating Table of Contents</h3>
|
||||
<p>You can make an autogenerated list of links, which can be useful as a table of contents for API docs.</p>
|
||||
<p>In your markdown file, insert a line with the text <<code>AUTOGENERATED_TABLE_OF_CONTENTS</code>>. Write your documentation using <code>h3</code> headers for each function inside a code block. These will be found by Docusaurus and a list of links to these sections will inserted at the text <<code>AUTOGENERATED_TABLE_OF_CONTENTS</code>>.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- markdown"><span class="hljs-section">### `docusaurus.function(a, b)`</span>
|
||||
<pre><code class="hljs css languages-markdown"><span class="hljs-section">### `docusaurus.function(a, b)`</span>
|
||||
|
||||
Text describing my function
|
||||
|
||||
|
|
@ -120,7 +120,7 @@ Text describing my function
|
|||
Text describing my function
|
||||
</code></pre>
|
||||
<p>will lead to a table of contents of the functions:</p>
|
||||
<pre><code class="hljs css languages- markdown"><span class="hljs-bullet">- </span><span class="hljs-code">`docusaurus.function(a, b)`</span>
|
||||
<pre><code class="hljs css languages-markdown"><span class="hljs-bullet">- </span><span class="hljs-code">`docusaurus.function(a, b)`</span>
|
||||
<span class="hljs-bullet">- </span><span class="hljs-code">`docdoc(file)`</span>
|
||||
</code></pre>
|
||||
<p>and each function will link to their corresponding sections in the page.</p>
|
||||
|
|
@ -134,20 +134,20 @@ ReactDOM.render(
|
|||
```
|
||||
</code></pre>
|
||||
<p>...would be rendered with syntax highlighting like so:</p>
|
||||
<pre><code class="hljs css languages- javascript">ReactDOM.render(
|
||||
<pre><code class="hljs css languages-javascript">ReactDOM.render(
|
||||
<span class="xml"><span class="hljs-tag"><<span class="hljs-name">h1</span>></span>Hello, world!<span class="hljs-tag"></<span class="hljs-name">h1</span>></span></span>,
|
||||
<span class="hljs-built_in">document</span>.getElementById(<span class="hljs-string">'root'</span>)
|
||||
);
|
||||
</code></pre>
|
||||
<p>Highlighting is provided by <a href="https://highlightjs.org">Highlight.js</a> using the theme specified in your <code>siteConfig.js</code> file as part of the <code>highlight</code> key:</p>
|
||||
<pre><code class="hljs css languages- javascript">highlight: {
|
||||
<pre><code class="hljs css languages-javascript">highlight: {
|
||||
<span class="hljs-attr">theme</span>: <span class="hljs-string">'default'</span>
|
||||
}
|
||||
</code></pre>
|
||||
<p>You can find the full list of supported themes in the Highlight.js <a href="https://github.com/isagalaev/highlight.js/tree/master/src/styles"><code>styles</code></a> directory.</p>
|
||||
<h3><a class="anchor" aria-hidden="true" id="registering-additional-languages"></a><a href="#registering-additional-languages" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Registering additional languages</h3>
|
||||
<p>While Highlight.js provides support for <a href="https://highlightjs.org/static/demo/">many popular languages out of the box</a>, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the <code>hljs</code> constant as part of the <code>highlight</code> config key. This in turn allows you to call <a href="http://highlightjs.readthedocs.io/en/latest/api.html#registerlanguage-name-language"><code>registerLanguage</code></a>:</p>
|
||||
<pre><code class="hljs css languages- javascript">highlight: {
|
||||
<pre><code class="hljs css languages-javascript">highlight: {
|
||||
<span class="hljs-attr">theme</span>: <span class="hljs-string">'default'</span>,
|
||||
<span class="hljs-attr">hljs</span>: <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">hljs</span>) </span>{
|
||||
hljs.registerLanguage(<span class="hljs-string">'galacticbasic'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">hljs</span>) </span>{
|
||||
|
|
|
|||
|
|
@ -55,7 +55,7 @@
|
|||
<p><code>hide_title</code>: Whether to hide the title at the top of the doc.</p>
|
||||
<p><code>sidebar_label</code>: The text shown in the document sidebar for this document. If this field is not present, the document's <code>sidebar_label</code> will default to its <code>title</code>.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
id: doc1
|
||||
title: My Document
|
||||
<span class="hljs-section">sidebar_label: Document
|
||||
|
|
@ -63,7 +63,7 @@ title: My Document
|
|||
</code></pre>
|
||||
<p>Versioned documents have their ids altered to include the version number when they get copied. The new <code>id</code> is <code>version-${version}-${id}</code> where <code>${version}</code> is the version number of that document and <code>${id}</code> is the original <code>id</code>. Additionally, versioned documents get an added <code>original_id</code> field with the original document id.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
id: version-1.0.0-doc1
|
||||
title: My Document
|
||||
sidebar_label: Document
|
||||
|
|
@ -72,7 +72,7 @@ sidebar_label: Document
|
|||
</code></pre>
|
||||
<p><code>custom_edit_url</code>: The url for editing this document. If this field is not present, the document's edit url will fallback to <code>editUrl</code> from optional fields of <code>siteConfig.js</code>. See <a href="site-config.md">siteConfig.js</a> docs for more information.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
id: doc-markdown
|
||||
title: Markdown Features
|
||||
<span class="hljs-section">custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
|
||||
|
|
@ -85,7 +85,7 @@ title: Markdown Features
|
|||
<p><code>authorURL</code>: A page to link to when a site user clicks the author's name. If this field is omitted, the author's name will not link to anything.</p>
|
||||
<p><code>authorFBID</code>: The author's Facebook id, used only to get the author's profile picture to display with the blog post. If this field is omitted, no author picture will be shown for the blog post.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
title: My First Blog Post
|
||||
author: Frank Li
|
||||
authorURL: http://twitter.com/franchementli
|
||||
|
|
@ -97,20 +97,20 @@ authorURL: http://twitter.com/franchementli
|
|||
<h3><a class="anchor" aria-hidden="true" id="linking-other-documents"></a><a href="#linking-other-documents" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Linking other Documents</h3>
|
||||
<p>You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- markdown">[<span class="hljs-string">This links to another document</span>](<span class="hljs-link">other-document.md</span>)
|
||||
<pre><code class="hljs css languages-markdown">[<span class="hljs-string">This links to another document</span>](<span class="hljs-link">other-document.md</span>)
|
||||
</code></pre>
|
||||
<p>This markdown will automatically get converted into a link to <code>/docs/other-document.html</code> (or the appropriately translated/versioned link) once it gets rendered.</p>
|
||||
<p>This can help when you want to navigate through docs on GitHub since the links there will be functional links to other documents (still on GitHub), but the documents will have the correct html links when they get rendered.</p>
|
||||
<h3><a class="anchor" aria-hidden="true" id="linking-to-images-and-other-assets"></a><a href="#linking-to-images-and-other-assets" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Linking to Images and Other Assets</h3>
|
||||
<p>Static assets can be linked to in the same way that documents are, using relative urls. Static assets used in documents and blogs should go into <code>docs/assets</code> and <code>website/blog/assets</code>, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- markdown">![<span class="hljs-string">alt-text</span>](<span class="hljs-link">/docs/assets/doc-image.png</span>)
|
||||
<pre><code class="hljs css languages-markdown">![<span class="hljs-string">alt-text</span>](<span class="hljs-link">/docs/assets/doc-image.png</span>)
|
||||
</code></pre>
|
||||
<h3><a class="anchor" aria-hidden="true" id="generating-table-of-contents"></a><a href="#generating-table-of-contents" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Generating Table of Contents</h3>
|
||||
<p>You can make an autogenerated list of links, which can be useful as a table of contents for API docs.</p>
|
||||
<p>In your markdown file, insert a line with the text <<code>AUTOGENERATED_TABLE_OF_CONTENTS</code>>. Write your documentation using <code>h3</code> headers for each function inside a code block. These will be found by Docusaurus and a list of links to these sections will inserted at the text <<code>AUTOGENERATED_TABLE_OF_CONTENTS</code>>.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- markdown"><span class="hljs-section">### `docusaurus.function(a, b)`</span>
|
||||
<pre><code class="hljs css languages-markdown"><span class="hljs-section">### `docusaurus.function(a, b)`</span>
|
||||
|
||||
Text describing my function
|
||||
|
||||
|
|
@ -120,7 +120,7 @@ Text describing my function
|
|||
Text describing my function
|
||||
</code></pre>
|
||||
<p>will lead to a table of contents of the functions:</p>
|
||||
<pre><code class="hljs css languages- markdown"><span class="hljs-bullet">- </span><span class="hljs-code">`docusaurus.function(a, b)`</span>
|
||||
<pre><code class="hljs css languages-markdown"><span class="hljs-bullet">- </span><span class="hljs-code">`docusaurus.function(a, b)`</span>
|
||||
<span class="hljs-bullet">- </span><span class="hljs-code">`docdoc(file)`</span>
|
||||
</code></pre>
|
||||
<p>and each function will link to their corresponding sections in the page.</p>
|
||||
|
|
@ -134,20 +134,20 @@ ReactDOM.render(
|
|||
```
|
||||
</code></pre>
|
||||
<p>...would be rendered with syntax highlighting like so:</p>
|
||||
<pre><code class="hljs css languages- javascript">ReactDOM.render(
|
||||
<pre><code class="hljs css languages-javascript">ReactDOM.render(
|
||||
<span class="xml"><span class="hljs-tag"><<span class="hljs-name">h1</span>></span>Hello, world!<span class="hljs-tag"></<span class="hljs-name">h1</span>></span></span>,
|
||||
<span class="hljs-built_in">document</span>.getElementById(<span class="hljs-string">'root'</span>)
|
||||
);
|
||||
</code></pre>
|
||||
<p>Highlighting is provided by <a href="https://highlightjs.org">Highlight.js</a> using the theme specified in your <code>siteConfig.js</code> file as part of the <code>highlight</code> key:</p>
|
||||
<pre><code class="hljs css languages- javascript">highlight: {
|
||||
<pre><code class="hljs css languages-javascript">highlight: {
|
||||
<span class="hljs-attr">theme</span>: <span class="hljs-string">'default'</span>
|
||||
}
|
||||
</code></pre>
|
||||
<p>You can find the full list of supported themes in the Highlight.js <a href="https://github.com/isagalaev/highlight.js/tree/master/src/styles"><code>styles</code></a> directory.</p>
|
||||
<h3><a class="anchor" aria-hidden="true" id="registering-additional-languages"></a><a href="#registering-additional-languages" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Registering additional languages</h3>
|
||||
<p>While Highlight.js provides support for <a href="https://highlightjs.org/static/demo/">many popular languages out of the box</a>, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the <code>hljs</code> constant as part of the <code>highlight</code> config key. This in turn allows you to call <a href="http://highlightjs.readthedocs.io/en/latest/api.html#registerlanguage-name-language"><code>registerLanguage</code></a>:</p>
|
||||
<pre><code class="hljs css languages- javascript">highlight: {
|
||||
<pre><code class="hljs css languages-javascript">highlight: {
|
||||
<span class="hljs-attr">theme</span>: <span class="hljs-string">'default'</span>,
|
||||
<span class="hljs-attr">hljs</span>: <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">hljs</span>) </span>{
|
||||
hljs.registerLanguage(<span class="hljs-string">'galacticbasic'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">hljs</span>) </span>{
|
||||
|
|
|
|||
|
|
@ -61,7 +61,7 @@
|
|||
<p>After docusaurus is installed, moving forward, you can check your current version of Docusaurus by going into the <code>website</code> directory and typing <code>npm list docusaurus</code>. You can update to the <a href="https://www.npmjs.com/package/docusaurus">latest version</a> of Docusaurus by typing <code>npm update</code>.</p>
|
||||
</blockquote>
|
||||
<p>Along with previously existing files and directories, your root directory will now contain a structure similar to:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs-examples-from-docusaurus
|
||||
│ └── doc1.md
|
||||
│ └── doc2.md
|
||||
|
|
|
|||
|
|
@ -61,7 +61,7 @@
|
|||
<p>After docusaurus is installed, moving forward, you can check your current version of Docusaurus by going into the <code>website</code> directory and typing <code>npm list docusaurus</code>. You can update to the <a href="https://www.npmjs.com/package/docusaurus">latest version</a> of Docusaurus by typing <code>npm update</code>.</p>
|
||||
</blockquote>
|
||||
<p>Along with previously existing files and directories, your root directory will now contain a structure similar to:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs-examples-from-docusaurus
|
||||
│ └── doc1.md
|
||||
│ └── doc2.md
|
||||
|
|
|
|||
|
|
@ -102,7 +102,7 @@
|
|||
</table>
|
||||
<p>Once you have the parameter value information, you can go ahead and run the publish script, ensuring you have inserted your own values inside the various parameter placeholders:</p>
|
||||
<p>To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate.</p>
|
||||
<pre><code class="hljs css languages- bash">GIT_USER=<GIT_USER> \
|
||||
<pre><code class="hljs css languages-bash">GIT_USER=<GIT_USER> \
|
||||
CURRENT_BRANCH=master \
|
||||
USE_SSH=<span class="hljs-literal">true</span> \
|
||||
yarn run publish-gh-pages <span class="hljs-comment"># or `npm run publish-gh-pages`</span>
|
||||
|
|
@ -126,7 +126,7 @@
|
|||
<li>Create a <code>.circleci</code> folder and create a <code>config.yml</code> under that folder.</li>
|
||||
<li>Copy the text below into <code>.circleci/config.yml</code>.</li>
|
||||
</ol>
|
||||
<pre><code class="hljs css languages- yml"><span class="hljs-comment"># If you only one circle to run on direct commits to master, you can uncomment this out</span>
|
||||
<pre><code class="hljs css languages-yml"><span class="hljs-comment"># If you only one circle to run on direct commits to master, you can uncomment this out</span>
|
||||
<span class="hljs-comment"># and uncomment the filters: *filter-only-master down below too</span>
|
||||
<span class="hljs-comment">#</span>
|
||||
<span class="hljs-comment"># aliases:</span>
|
||||
|
|
@ -173,7 +173,7 @@
|
|||
</blockquote>
|
||||
<h3><a class="anchor" aria-hidden="true" id="tips-tricks"></a><a href="#tips-tricks" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Tips & Tricks</h3>
|
||||
<p>When initially deploying to a <code>gh-pages</code> branch using Circle CI, you may notice that some jobs triggered by commits to the <code>gh-pages</code> branch fail to run successfully due to a lack of tests. You can easily work around this by creating a basic Circle CI config with the following contents:</p>
|
||||
<pre><code class="hljs css languages- yml"><span class="hljs-comment"># Circle CI 2.0 Config File</span>
|
||||
<pre><code class="hljs css languages-yml"><span class="hljs-comment"># Circle CI 2.0 Config File</span>
|
||||
<span class="hljs-comment"># This config file will prevent tests from being run on the gh-pages branch.</span>
|
||||
<span class="hljs-attr">version:</span> <span class="hljs-number">2</span>
|
||||
<span class="hljs-attr">jobs:</span>
|
||||
|
|
|
|||
|
|
@ -102,7 +102,7 @@
|
|||
</table>
|
||||
<p>Once you have the parameter value information, you can go ahead and run the publish script, ensuring you have inserted your own values inside the various parameter placeholders:</p>
|
||||
<p>To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate.</p>
|
||||
<pre><code class="hljs css languages- bash">GIT_USER=<GIT_USER> \
|
||||
<pre><code class="hljs css languages-bash">GIT_USER=<GIT_USER> \
|
||||
CURRENT_BRANCH=master \
|
||||
USE_SSH=<span class="hljs-literal">true</span> \
|
||||
yarn run publish-gh-pages <span class="hljs-comment"># or `npm run publish-gh-pages`</span>
|
||||
|
|
@ -126,7 +126,7 @@
|
|||
<li>Create a <code>.circleci</code> folder and create a <code>config.yml</code> under that folder.</li>
|
||||
<li>Copy the text below into <code>.circleci/config.yml</code>.</li>
|
||||
</ol>
|
||||
<pre><code class="hljs css languages- yml"><span class="hljs-comment"># If you only one circle to run on direct commits to master, you can uncomment this out</span>
|
||||
<pre><code class="hljs css languages-yml"><span class="hljs-comment"># If you only one circle to run on direct commits to master, you can uncomment this out</span>
|
||||
<span class="hljs-comment"># and uncomment the filters: *filter-only-master down below too</span>
|
||||
<span class="hljs-comment">#</span>
|
||||
<span class="hljs-comment"># aliases:</span>
|
||||
|
|
@ -173,7 +173,7 @@
|
|||
</blockquote>
|
||||
<h3><a class="anchor" aria-hidden="true" id="tips-tricks"></a><a href="#tips-tricks" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Tips & Tricks</h3>
|
||||
<p>When initially deploying to a <code>gh-pages</code> branch using Circle CI, you may notice that some jobs triggered by commits to the <code>gh-pages</code> branch fail to run successfully due to a lack of tests. You can easily work around this by creating a basic Circle CI config with the following contents:</p>
|
||||
<pre><code class="hljs css languages- yml"><span class="hljs-comment"># Circle CI 2.0 Config File</span>
|
||||
<pre><code class="hljs css languages-yml"><span class="hljs-comment"># Circle CI 2.0 Config File</span>
|
||||
<span class="hljs-comment"># This config file will prevent tests from being run on the gh-pages branch.</span>
|
||||
<span class="hljs-attr">version:</span> <span class="hljs-number">2</span>
|
||||
<span class="hljs-attr">jobs:</span>
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@
|
|||
</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/facebook/docusaurus/edit/master/docs/guides-search.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 class="postHeaderTitle">Enabling Search</h1></header><article><div><span><p>Docusaurus supports search using <a href="https://community.algolia.com/docsearch/">Algolia DocSearch</a>. Once you have set up your site, <a href="https://community.algolia.com/docsearch/">enter your site information</a> to have Algolia crawl your website's documentation pages. Algolia will then send you an API key and index name for your site.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="enabling-the-search-bar"></a><a href="#enabling-the-search-bar" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Enabling the Search Bar</h2>
|
||||
<p>Enter your search-only API key and index name into <code>siteConfig.js</code> in the <code>algolia</code> section to enable search for your site.</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
...
|
||||
algolia: {
|
||||
<span class="hljs-attr">apiKey</span>: <span class="hljs-string">"my-search-only-api-key-1234"</span>,
|
||||
|
|
@ -61,7 +61,7 @@
|
|||
</code></pre>
|
||||
<h2><a class="anchor" aria-hidden="true" id="extra-search-options"></a><a href="#extra-search-options" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Extra Search Options</h2>
|
||||
<p>You can also specify extra <a href="https://community.algolia.com/docsearch/documentation/">search options used by Algolia</a> by using an <code>algoliaOptions</code> field in <code>algolia</code>. This may be useful if you want to provide different search results for the different versions or languages of your docs. Any occurrences of "VERSION" or "LANGUAGE" will be replaced by the version or language of the current page, respectively. More details about search options can be <a href="https://www.algolia.com/doc/api-reference/api-parameters/#overview">found here</a>.</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
...
|
||||
algolia: {
|
||||
...
|
||||
|
|
@ -75,7 +75,7 @@
|
|||
<h2><a class="anchor" aria-hidden="true" id="controlling-the-location-of-the-search-bar"></a><a href="#controlling-the-location-of-the-search-bar" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Controlling the Location of the Search Bar</h2>
|
||||
<p>By default, the search bar will be the rightmost element in the top navigation bar.</p>
|
||||
<p>If you want to change the default location, add the <code>searchBar</code> flag in the <code>headerLinks</code> field of <code>siteConfig.js</code> in your desired location. For example, you may want the search bar in between your internal and external links.</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
...
|
||||
headerLinks: [
|
||||
{...}
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@
|
|||
</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/facebook/docusaurus/edit/master/docs/guides-search.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 class="postHeaderTitle">Enabling Search</h1></header><article><div><span><p>Docusaurus supports search using <a href="https://community.algolia.com/docsearch/">Algolia DocSearch</a>. Once you have set up your site, <a href="https://community.algolia.com/docsearch/">enter your site information</a> to have Algolia crawl your website's documentation pages. Algolia will then send you an API key and index name for your site.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="enabling-the-search-bar"></a><a href="#enabling-the-search-bar" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Enabling the Search Bar</h2>
|
||||
<p>Enter your search-only API key and index name into <code>siteConfig.js</code> in the <code>algolia</code> section to enable search for your site.</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
...
|
||||
algolia: {
|
||||
<span class="hljs-attr">apiKey</span>: <span class="hljs-string">"my-search-only-api-key-1234"</span>,
|
||||
|
|
@ -61,7 +61,7 @@
|
|||
</code></pre>
|
||||
<h2><a class="anchor" aria-hidden="true" id="extra-search-options"></a><a href="#extra-search-options" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Extra Search Options</h2>
|
||||
<p>You can also specify extra <a href="https://community.algolia.com/docsearch/documentation/">search options used by Algolia</a> by using an <code>algoliaOptions</code> field in <code>algolia</code>. This may be useful if you want to provide different search results for the different versions or languages of your docs. Any occurrences of "VERSION" or "LANGUAGE" will be replaced by the version or language of the current page, respectively. More details about search options can be <a href="https://www.algolia.com/doc/api-reference/api-parameters/#overview">found here</a>.</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
...
|
||||
algolia: {
|
||||
...
|
||||
|
|
@ -75,7 +75,7 @@
|
|||
<h2><a class="anchor" aria-hidden="true" id="controlling-the-location-of-the-search-bar"></a><a href="#controlling-the-location-of-the-search-bar" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Controlling the Location of the Search Bar</h2>
|
||||
<p>By default, the search bar will be the rightmost element in the top navigation bar.</p>
|
||||
<p>If you want to change the default location, add the <code>searchBar</code> flag in the <code>headerLinks</code> field of <code>siteConfig.js</code> in your desired location. For example, you may want the search bar in between your internal and external links.</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
...
|
||||
headerLinks: [
|
||||
{...}
|
||||
|
|
|
|||
|
|
@ -66,7 +66,7 @@
|
|||
<p><code>headerIcon</code> - url for icon used in header navigation bar.</p>
|
||||
<p><code>headerLinks</code> - Links that will be used in the header navigation bar. The <code>label</code> field of each object will be the link text and will also be translated for each language.</p>
|
||||
<p>Example Usage:</p>
|
||||
<pre><code class="hljs css languages- js">headerLinks: [
|
||||
<pre><code class="hljs css languages-js">headerLinks: [
|
||||
<span class="hljs-comment">// Links to document with id doc1 for current language/version</span>
|
||||
{ <span class="hljs-attr">doc</span>: <span class="hljs-string">"doc1"</span>, <span class="hljs-attr">label</span>: <span class="hljs-string">"Getting Started"</span> },
|
||||
<span class="hljs-comment">// Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language</span>
|
||||
|
|
@ -97,9 +97,9 @@
|
|||
<p><code>blogSidebarCount</code> - Control the number of blog posts that show up in the sidebar. See the <a href="/docs/en/1.0.13/adding-blog#changing-how-many-blog-posts-show-on-sidebar">adding a blog docs</a> for more information.</p>
|
||||
<p><code>cname</code> - The CNAME for your website. It will go into a <code>CNAME</code> file when your site it built.</p>
|
||||
<p><code>customDocsPath</code> - By default, Docusaurus expects your documentation to be in a directory called <code>docs</code>. This directory is at the same level as the <code>website</code> directory (i.e., not inside the <code>website</code> directory). You can specify a custom path to your documentation with this field. <strong>Note that all of your documentation <code>*.md</code> files must still reside in a flat hierarchy. You cannot have your documents in nested directories</strong>.</p>
|
||||
<pre><code class="hljs css languages- js">customDocsPath: <span class="hljs-string">"docs/site"</span>
|
||||
<pre><code class="hljs css languages-js">customDocsPath: <span class="hljs-string">"docs/site"</span>
|
||||
</code></pre>
|
||||
<pre><code class="hljs css languages- js">customDocsPath: <span class="hljs-string">"website-docs"</span>
|
||||
<pre><code class="hljs css languages-js">customDocsPath: <span class="hljs-string">"website-docs"</span>
|
||||
</code></pre>
|
||||
<p><code>disableHeaderTitle</code> - An option to disable showing the title in the header next to the header icon. Exclude this field to keep the header as normal, otherwise set to <code>true</code>.</p>
|
||||
<p><code>disableTitleTagline</code> - An option to disable showing the tagline in the title of main pages. Exclude this field to keep page titles as <code>Title • Tagline</code>. Set to <code>true</code> to make page titles just <code>Title</code>.</p>
|
||||
|
|
|
|||
|
|
@ -66,7 +66,7 @@
|
|||
<p><code>headerIcon</code> - url for icon used in header navigation bar.</p>
|
||||
<p><code>headerLinks</code> - Links that will be used in the header navigation bar. The <code>label</code> field of each object will be the link text and will also be translated for each language.</p>
|
||||
<p>Example Usage:</p>
|
||||
<pre><code class="hljs css languages- js">headerLinks: [
|
||||
<pre><code class="hljs css languages-js">headerLinks: [
|
||||
<span class="hljs-comment">// Links to document with id doc1 for current language/version</span>
|
||||
{ <span class="hljs-attr">doc</span>: <span class="hljs-string">"doc1"</span>, <span class="hljs-attr">label</span>: <span class="hljs-string">"Getting Started"</span> },
|
||||
<span class="hljs-comment">// Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language</span>
|
||||
|
|
@ -97,9 +97,9 @@
|
|||
<p><code>blogSidebarCount</code> - Control the number of blog posts that show up in the sidebar. See the <a href="/docs/en/1.0.13/adding-blog#changing-how-many-blog-posts-show-on-sidebar">adding a blog docs</a> for more information.</p>
|
||||
<p><code>cname</code> - The CNAME for your website. It will go into a <code>CNAME</code> file when your site it built.</p>
|
||||
<p><code>customDocsPath</code> - By default, Docusaurus expects your documentation to be in a directory called <code>docs</code>. This directory is at the same level as the <code>website</code> directory (i.e., not inside the <code>website</code> directory). You can specify a custom path to your documentation with this field. <strong>Note that all of your documentation <code>*.md</code> files must still reside in a flat hierarchy. You cannot have your documents in nested directories</strong>.</p>
|
||||
<pre><code class="hljs css languages- js">customDocsPath: <span class="hljs-string">"docs/site"</span>
|
||||
<pre><code class="hljs css languages-js">customDocsPath: <span class="hljs-string">"docs/site"</span>
|
||||
</code></pre>
|
||||
<pre><code class="hljs css languages- js">customDocsPath: <span class="hljs-string">"website-docs"</span>
|
||||
<pre><code class="hljs css languages-js">customDocsPath: <span class="hljs-string">"website-docs"</span>
|
||||
</code></pre>
|
||||
<p><code>disableHeaderTitle</code> - An option to disable showing the title in the header next to the header icon. Exclude this field to keep the header as normal, otherwise set to <code>true</code>.</p>
|
||||
<p><code>disableTitleTagline</code> - An option to disable showing the tagline in the title of main pages. Exclude this field to keep page titles as <code>Title • Tagline</code>. Set to <code>true</code> to make page titles just <code>Title</code>.</p>
|
||||
|
|
|
|||
|
|
@ -51,7 +51,7 @@
|
|||
<p>After <a href="/docs/en/1.0.13/installation">installation</a> and <a href="/docs/en/1.0.13/site-preparation">preparation</a>, much of the work to create a basic site for your docs is already complete.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="site-structure"></a><a href="#site-structure" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Site Structure</h2>
|
||||
<p>Your site structure looks like the following:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs
|
||||
└── website
|
||||
│ └── blog
|
||||
|
|
|
|||
|
|
@ -51,7 +51,7 @@
|
|||
<p>After <a href="/docs/en/1.0.13/installation">installation</a> and <a href="/docs/en/1.0.13/site-preparation">preparation</a>, much of the work to create a basic site for your docs is already complete.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="site-structure"></a><a href="#site-structure" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Site Structure</h2>
|
||||
<p>Your site structure looks like the following:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs
|
||||
└── website
|
||||
│ └── blog
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@
|
|||
</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/facebook/docusaurus/edit/master/docs/getting-started-preparation.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 class="postHeaderTitle">Site Preparation</h1></header><article><div><span><p>After <a href="/docs/en/1.0.13/installation">installing Docusaurus</a>, you now have a skeleton to work from for your specific website. The following discusses the rest of the Docusaurus structure in order for you to prepare your site.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="directory-structure"></a><a href="#directory-structure" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Directory Structure</h2>
|
||||
<p>As shown after you <a href="/docs/en/1.0.13/installation">installed Docusaurus</a>, the initialization script created a directory structure similar to:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs-examples-from-docusaurus
|
||||
│ └── doc1.md
|
||||
│ └── doc2.md
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@
|
|||
</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/facebook/docusaurus/edit/master/docs/getting-started-preparation.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 class="postHeaderTitle">Site Preparation</h1></header><article><div><span><p>After <a href="/docs/en/1.0.13/installation">installing Docusaurus</a>, you now have a skeleton to work from for your specific website. The following discusses the rest of the Docusaurus structure in order for you to prepare your site.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="directory-structure"></a><a href="#directory-structure" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Directory Structure</h2>
|
||||
<p>As shown after you <a href="/docs/en/1.0.13/installation">installed Docusaurus</a>, the initialization script created a directory structure similar to:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs-examples-from-docusaurus
|
||||
│ └── doc1.md
|
||||
│ └── doc2.md
|
||||
|
|
|
|||
|
|
@ -76,7 +76,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<p>Pages allow you to customize layout and specific content of pages like a custom index page or help page.</p>
|
||||
<p>Pages with text that you want translated should be placed in <code>website/pages/en</code> folder.</p>
|
||||
<p>Wrap strings you want translated in a <code><translate></code> tag, and add the following <code>require</code> statement to the top of the file:</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token operator">...</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token operator">...</span>
|
||||
<span class="token keyword">const</span> translate <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">"../../server/translate.js"</span><span class="token punctuation">)</span><span class="token punctuation">.</span>translate<span class="token punctuation">;</span>
|
||||
<span class="token operator">...</span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>h2</span><span class="token punctuation">></span></span>
|
||||
|
|
@ -85,7 +85,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<span class="token operator">...</span>
|
||||
</code></pre>
|
||||
<p>You can also include an optional description attribute to give more context to a translator about how to translate the string:</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span> <span class="token attr-name">desc</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>flower, not verb<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Rose<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
</code></pre>
|
||||
|
|
@ -95,7 +95,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<h2><a class="anchor" aria-hidden="true" id="gathering-strings-to-translate"></a><a href="#gathering-strings-to-translate" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Gathering Strings to Translate</h2>
|
||||
<p>The strings within localized Pages must be extracted and provided to Crowdin.</p>
|
||||
<p>Add the following script to your <code>website/package.json</code> file, if it does not exist already:</p>
|
||||
<pre><code class="hljs css languages- json">...
|
||||
<pre><code class="hljs css languages-json">...
|
||||
"scripts": {
|
||||
"write-translations": "docusaurus-write-translations"
|
||||
},
|
||||
|
|
@ -133,7 +133,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
</blockquote>
|
||||
<p>The example below can be automatically generated by the Docusaurus cli with the <code>examples</code> script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.</p>
|
||||
<p>Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.</p>
|
||||
<pre><code class="hljs css languages- yaml"><span class="hljs-attr">project_identifier_env:</span> <span class="hljs-string">CROWDIN_DOCUSAURUS_PROJECT_ID</span>
|
||||
<pre><code class="hljs css languages-yaml"><span class="hljs-attr">project_identifier_env:</span> <span class="hljs-string">CROWDIN_DOCUSAURUS_PROJECT_ID</span>
|
||||
<span class="hljs-attr">api_key_env:</span> <span class="hljs-string">CROWDIN_DOCUSAURUS_API_KEY</span>
|
||||
<span class="hljs-attr">base_path:</span> <span class="hljs-string">"./"</span>
|
||||
<span class="hljs-attr">preserve_hierarchy:</span> <span class="hljs-literal">true</span>
|
||||
|
|
@ -158,7 +158,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<h3><a class="anchor" aria-hidden="true" id="setup-the-crowdin-scripts"></a><a href="#setup-the-crowdin-scripts" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Setup the Crowdin Scripts</h3>
|
||||
<p>You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in <code>/docs</code> as well as translatable strings in <code>website/i18n/en.json</code>. (These strings can be generated by running <code>yarn write-translations</code>.)</p>
|
||||
<p>You can add the following to your <code>package.json</code> to manually trigger Crowdin.</p>
|
||||
<pre><code class="hljs css languages- json">"scripts": {
|
||||
<pre><code class="hljs css languages-json">"scripts": {
|
||||
"crowdin-upload": "crowdin --config ../crowdin.yaml upload sources --auto-update -b master",
|
||||
"crowdin-download": "crowdin --config ../crowdin.yaml download -b master"
|
||||
},
|
||||
|
|
@ -183,7 +183,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<h3><a class="anchor" aria-hidden="true" id="automated-file-sync-using-circleci"></a><a href="#automated-file-sync-using-circleci" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Automated File Sync Using CircleCI</h3>
|
||||
<p>You can automate pulling down and uploading translations for your files using the <a href="https://circleci.com">CircleCI</a> web continuous integration service.</p>
|
||||
<p>First, update the <code>circle.yml</code> file in your project directory to include steps to upload English files to be translated and download translated files using the Crowdin CLI. Here is an example <code>circle.yml</code> file:</p>
|
||||
<pre><code class="hljs css languages- yaml"><span class="hljs-attr">machine:</span>
|
||||
<pre><code class="hljs css languages-yaml"><span class="hljs-attr">machine:</span>
|
||||
<span class="hljs-attr"> node:</span>
|
||||
<span class="hljs-attr"> version:</span> <span class="hljs-number">6.10</span><span class="hljs-number">.3</span>
|
||||
<span class="hljs-attr"> npm:</span>
|
||||
|
|
@ -219,7 +219,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<p>If you wish to use Crowdin on your machine locally, you can install the <a href="https://support.crowdin.com/cli-tool/">Crowdin CLI tool</a> and run the same commands found in the <code>circle.yaml</code> file. The only difference is that you must set <code>project_identifier</code> and <code>api_key</code> values in the <code>crowdin.yaml</code> file since you will not have Circle environment variables set up.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="versioned-translations"></a><a href="#versioned-translations" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Versioned Translations</h2>
|
||||
<p>If you wish to have translation and versioning for your documentation, add the following section to the end of your <code>crowdin.yaml</code> file:</p>
|
||||
<pre><code class="hljs css languages- yaml"><span class="hljs-bullet"> -</span>
|
||||
<pre><code class="hljs css languages-yaml"><span class="hljs-bullet"> -</span>
|
||||
<span class="hljs-attr"> source:</span> <span class="hljs-string">'/website/versioned_docs/**/*.md'</span>
|
||||
<span class="hljs-attr"> translation:</span> <span class="hljs-string">'/website/translated_docs/%locale%/**/%original_file_name%'</span>
|
||||
<span class="hljs-attr"> languages_mapping:</span> <span class="hljs-meta">*anchor</span>
|
||||
|
|
|
|||
|
|
@ -76,7 +76,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<p>Pages allow you to customize layout and specific content of pages like a custom index page or help page.</p>
|
||||
<p>Pages with text that you want translated should be placed in <code>website/pages/en</code> folder.</p>
|
||||
<p>Wrap strings you want translated in a <code><translate></code> tag, and add the following <code>require</code> statement to the top of the file:</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token operator">...</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token operator">...</span>
|
||||
<span class="token keyword">const</span> translate <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">"../../server/translate.js"</span><span class="token punctuation">)</span><span class="token punctuation">.</span>translate<span class="token punctuation">;</span>
|
||||
<span class="token operator">...</span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>h2</span><span class="token punctuation">></span></span>
|
||||
|
|
@ -85,7 +85,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<span class="token operator">...</span>
|
||||
</code></pre>
|
||||
<p>You can also include an optional description attribute to give more context to a translator about how to translate the string:</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span> <span class="token attr-name">desc</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>flower, not verb<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Rose<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
</code></pre>
|
||||
|
|
@ -95,7 +95,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<h2><a class="anchor" aria-hidden="true" id="gathering-strings-to-translate"></a><a href="#gathering-strings-to-translate" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Gathering Strings to Translate</h2>
|
||||
<p>The strings within localized Pages must be extracted and provided to Crowdin.</p>
|
||||
<p>Add the following script to your <code>website/package.json</code> file, if it does not exist already:</p>
|
||||
<pre><code class="hljs css languages- json">...
|
||||
<pre><code class="hljs css languages-json">...
|
||||
"scripts": {
|
||||
"write-translations": "docusaurus-write-translations"
|
||||
},
|
||||
|
|
@ -133,7 +133,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
</blockquote>
|
||||
<p>The example below can be automatically generated by the Docusaurus cli with the <code>examples</code> script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.</p>
|
||||
<p>Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.</p>
|
||||
<pre><code class="hljs css languages- yaml"><span class="hljs-attr">project_identifier_env:</span> <span class="hljs-string">CROWDIN_DOCUSAURUS_PROJECT_ID</span>
|
||||
<pre><code class="hljs css languages-yaml"><span class="hljs-attr">project_identifier_env:</span> <span class="hljs-string">CROWDIN_DOCUSAURUS_PROJECT_ID</span>
|
||||
<span class="hljs-attr">api_key_env:</span> <span class="hljs-string">CROWDIN_DOCUSAURUS_API_KEY</span>
|
||||
<span class="hljs-attr">base_path:</span> <span class="hljs-string">"./"</span>
|
||||
<span class="hljs-attr">preserve_hierarchy:</span> <span class="hljs-literal">true</span>
|
||||
|
|
@ -158,7 +158,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<h3><a class="anchor" aria-hidden="true" id="setup-the-crowdin-scripts"></a><a href="#setup-the-crowdin-scripts" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Setup the Crowdin Scripts</h3>
|
||||
<p>You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in <code>/docs</code> as well as translatable strings in <code>website/i18n/en.json</code>. (These strings can be generated by running <code>yarn write-translations</code>.)</p>
|
||||
<p>You can add the following to your <code>package.json</code> to manually trigger Crowdin.</p>
|
||||
<pre><code class="hljs css languages- json">"scripts": {
|
||||
<pre><code class="hljs css languages-json">"scripts": {
|
||||
"crowdin-upload": "crowdin --config ../crowdin.yaml upload sources --auto-update -b master",
|
||||
"crowdin-download": "crowdin --config ../crowdin.yaml download -b master"
|
||||
},
|
||||
|
|
@ -183,7 +183,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<h3><a class="anchor" aria-hidden="true" id="automated-file-sync-using-circleci"></a><a href="#automated-file-sync-using-circleci" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Automated File Sync Using CircleCI</h3>
|
||||
<p>You can automate pulling down and uploading translations for your files using the <a href="https://circleci.com">CircleCI</a> web continuous integration service.</p>
|
||||
<p>First, update the <code>circle.yml</code> file in your project directory to include steps to upload English files to be translated and download translated files using the Crowdin CLI. Here is an example <code>circle.yml</code> file:</p>
|
||||
<pre><code class="hljs css languages- yaml"><span class="hljs-attr">machine:</span>
|
||||
<pre><code class="hljs css languages-yaml"><span class="hljs-attr">machine:</span>
|
||||
<span class="hljs-attr"> node:</span>
|
||||
<span class="hljs-attr"> version:</span> <span class="hljs-number">6.10</span><span class="hljs-number">.3</span>
|
||||
<span class="hljs-attr"> npm:</span>
|
||||
|
|
@ -219,7 +219,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<p>If you wish to use Crowdin on your machine locally, you can install the <a href="https://support.crowdin.com/cli-tool/">Crowdin CLI tool</a> and run the same commands found in the <code>circle.yaml</code> file. The only difference is that you must set <code>project_identifier</code> and <code>api_key</code> values in the <code>crowdin.yaml</code> file since you will not have Circle environment variables set up.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="versioned-translations"></a><a href="#versioned-translations" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Versioned Translations</h2>
|
||||
<p>If you wish to have translation and versioning for your documentation, add the following section to the end of your <code>crowdin.yaml</code> file:</p>
|
||||
<pre><code class="hljs css languages- yaml"><span class="hljs-bullet"> -</span>
|
||||
<pre><code class="hljs css languages-yaml"><span class="hljs-bullet"> -</span>
|
||||
<span class="hljs-attr"> source:</span> <span class="hljs-string">'/website/versioned_docs/**/*.md'</span>
|
||||
<span class="hljs-attr"> translation:</span> <span class="hljs-string">'/website/translated_docs/%locale%/**/%original_file_name%'</span>
|
||||
<span class="hljs-attr"> languages_mapping:</span> <span class="hljs-meta">*anchor</span>
|
||||
|
|
|
|||
|
|
@ -50,19 +50,19 @@
|
|||
</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/facebook/docusaurus/edit/master/docs/guides-versioning.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 class="postHeaderTitle">Versioning</h1></header><article><div><span><p>You 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" aria-hidden="true" id="how-to-create-new-versions"></a><a href="#how-to-create-new-versions" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>How to Create New Versions</h2>
|
||||
<p>Run the following script to generate a starter versions page listing all the site versions:</p>
|
||||
<pre><code class="hljs css languages- bash">yarn examples versions
|
||||
<pre><code class="hljs css languages-bash">yarn examples versions
|
||||
</code></pre>
|
||||
<p>This creates the <code>pages/en/versions.js</code> file.</p>
|
||||
<p>You can edit this file later on to customize how you display the versions.</p>
|
||||
<p>Add the following script to your <code>package.json</code> file if it doesn't already exist:</p>
|
||||
<pre><code class="hljs css languages- json">...
|
||||
<pre><code class="hljs css languages-json">...
|
||||
"scripts": {
|
||||
"version": "docusaurus-version"
|
||||
},
|
||||
...
|
||||
</code></pre>
|
||||
<p>Run the script with a command line argument of the version you wish to create. e.g.,</p>
|
||||
<pre><code class="hljs css languages- bash">yarn run version 1.0.0
|
||||
<pre><code class="hljs css languages-bash">yarn run version 1.0.0
|
||||
</code></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 <code>1.0.0</code> as the version number, version <code>1.0.0</code> is considered the latest release version for your project. The site will display the version number next to the title in the header. This version number links to a versions page that you created earlier.</p>
|
||||
|
|
@ -93,14 +93,14 @@
|
|||
<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" aria-hidden="true" id="renaming-existing-versions"></a><a href="#renaming-existing-versions" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Renaming Existing Versions</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><code class="hljs css languages- json">...
|
||||
<pre><code class="hljs css languages-json">...
|
||||
"scripts": {
|
||||
"rename-version": "docusaurus-rename-version"
|
||||
},
|
||||
...
|
||||
</code></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><code class="hljs css languages- bash">yarn run rename-version 1.0.0 1.0.1
|
||||
<pre><code class="hljs css languages-bash">yarn run rename-version 1.0.0 1.0.1
|
||||
</code></pre>
|
||||
<h2><a class="anchor" aria-hidden="true" id="versioning-and-translations"></a><a href="#versioning-and-translations" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Versioning and Translations</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="/docs/en/1.0.13/translation">translations guide</a>.</p>
|
||||
|
|
|
|||
|
|
@ -50,19 +50,19 @@
|
|||
</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/facebook/docusaurus/edit/master/docs/guides-versioning.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 class="postHeaderTitle">Versioning</h1></header><article><div><span><p>You 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" aria-hidden="true" id="how-to-create-new-versions"></a><a href="#how-to-create-new-versions" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>How to Create New Versions</h2>
|
||||
<p>Run the following script to generate a starter versions page listing all the site versions:</p>
|
||||
<pre><code class="hljs css languages- bash">yarn examples versions
|
||||
<pre><code class="hljs css languages-bash">yarn examples versions
|
||||
</code></pre>
|
||||
<p>This creates the <code>pages/en/versions.js</code> file.</p>
|
||||
<p>You can edit this file later on to customize how you display the versions.</p>
|
||||
<p>Add the following script to your <code>package.json</code> file if it doesn't already exist:</p>
|
||||
<pre><code class="hljs css languages- json">...
|
||||
<pre><code class="hljs css languages-json">...
|
||||
"scripts": {
|
||||
"version": "docusaurus-version"
|
||||
},
|
||||
...
|
||||
</code></pre>
|
||||
<p>Run the script with a command line argument of the version you wish to create. e.g.,</p>
|
||||
<pre><code class="hljs css languages- bash">yarn run version 1.0.0
|
||||
<pre><code class="hljs css languages-bash">yarn run version 1.0.0
|
||||
</code></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 <code>1.0.0</code> as the version number, version <code>1.0.0</code> is considered the latest release version for your project. The site will display the version number next to the title in the header. This version number links to a versions page that you created earlier.</p>
|
||||
|
|
@ -93,14 +93,14 @@
|
|||
<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" aria-hidden="true" id="renaming-existing-versions"></a><a href="#renaming-existing-versions" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Renaming Existing Versions</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><code class="hljs css languages- json">...
|
||||
<pre><code class="hljs css languages-json">...
|
||||
"scripts": {
|
||||
"rename-version": "docusaurus-rename-version"
|
||||
},
|
||||
...
|
||||
</code></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><code class="hljs css languages- bash">yarn run rename-version 1.0.0 1.0.1
|
||||
<pre><code class="hljs css languages-bash">yarn run rename-version 1.0.0 1.0.1
|
||||
</code></pre>
|
||||
<h2><a class="anchor" aria-hidden="true" id="versioning-and-translations"></a><a href="#versioning-and-translations" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Versioning and Translations</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="/docs/en/1.0.13/translation">translations guide</a>.</p>
|
||||
|
|
|
|||
|
|
@ -59,7 +59,7 @@
|
|||
<h3><a class="anchor" aria-hidden="true" id="complibrarymarkdownblock"></a><a href="#complibrarymarkdownblock" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><code>CompLibrary.MarkdownBlock</code></h3>
|
||||
<p>A React component that parses markdown and renders to HTML.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token keyword">const</span> MarkdownBlock <span class="token operator">=</span> CompLibrary<span class="token punctuation">.</span>MarkdownBlock<span class="token punctuation">;</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token keyword">const</span> MarkdownBlock <span class="token operator">=</span> CompLibrary<span class="token punctuation">.</span>MarkdownBlock<span class="token punctuation">;</span>
|
||||
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>MarkdownBlock</span><span class="token punctuation">></span></span>
|
||||
<span class="token punctuation">[</span>Markdown syntax <span class="token keyword">for</span> a link<span class="token punctuation">]</span><span class="token punctuation">(</span>http<span class="token punctuation">:</span><span class="token operator">/</span><span class="token operator">/</span>www<span class="token punctuation">.</span>example<span class="token punctuation">.</span>com<span class="token punctuation">)</span>
|
||||
|
|
@ -79,7 +79,7 @@
|
|||
</tbody>
|
||||
</table>
|
||||
<p><strong>Example</strong></p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>Container</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>Container</span>
|
||||
<span class="token attr-name">padding</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">[</span><span class="token string">'bottom'</span><span class="token punctuation">,</span> <span class="token string">'top'</span><span class="token punctuation">]</span><span class="token punctuation">}</span></span>
|
||||
<span class="token attr-name">background</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>light<span class="token punctuation">"</span></span>
|
||||
<span class="token attr-name">className</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>myCustomClass<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
|
|
@ -144,19 +144,19 @@
|
|||
<h2><a class="anchor" aria-hidden="true" id="translating-strings"></a><a href="#translating-strings" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Translating Strings</h2>
|
||||
<p>When translations are enabled, any pages inside <code>website/pages/en</code> will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the <code>languages.js</code> file. E.g. The url for a French page of <code>website/pages/en/help.js</code> would be found at <code>${baseUrl}fr/help.html</code>.</p>
|
||||
<p>When writing pages that you wish to translate, wrap any strings to be translated inside a <code><translate></code> tag. e.g.,</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span><span class="token punctuation">></span></span><span class="token constant">I</span> like translations<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>p</span><span class="token punctuation">></span></span>
|
||||
</code></pre>
|
||||
<p>You can also provide an optional description attribute to provide context for translators. e.g,</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>a</span> <span class="token attr-name">href</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>/community<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>a</span> <span class="token attr-name">href</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>/community<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span> <span class="token attr-name">desc</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>Footer link to page referring to community GitHub and Slack<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
Community
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>a</span><span class="token punctuation">></span></span>
|
||||
</code></pre>
|
||||
<p>Add the following require statement as well:</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> translate = <span class="hljs-built_in">require</span>(<span class="hljs-string">'../../server/translate.js'</span>).translate;
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> translate = <span class="hljs-built_in">require</span>(<span class="hljs-string">'../../server/translate.js'</span>).translate;
|
||||
</code></pre>
|
||||
<p>Note that this path is valid for files inside <code>pages/en</code> and should be adjusted accordingly if files are in different locations, as discussed <a href="#page-require-paths">above</a>.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="using-static-assets"></a><a href="#using-static-assets" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Using Static Assets</h2>
|
||||
|
|
|
|||
|
|
@ -59,7 +59,7 @@
|
|||
<h3><a class="anchor" aria-hidden="true" id="complibrarymarkdownblock"></a><a href="#complibrarymarkdownblock" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><code>CompLibrary.MarkdownBlock</code></h3>
|
||||
<p>A React component that parses markdown and renders to HTML.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token keyword">const</span> MarkdownBlock <span class="token operator">=</span> CompLibrary<span class="token punctuation">.</span>MarkdownBlock<span class="token punctuation">;</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token keyword">const</span> MarkdownBlock <span class="token operator">=</span> CompLibrary<span class="token punctuation">.</span>MarkdownBlock<span class="token punctuation">;</span>
|
||||
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>MarkdownBlock</span><span class="token punctuation">></span></span>
|
||||
<span class="token punctuation">[</span>Markdown syntax <span class="token keyword">for</span> a link<span class="token punctuation">]</span><span class="token punctuation">(</span>http<span class="token punctuation">:</span><span class="token operator">/</span><span class="token operator">/</span>www<span class="token punctuation">.</span>example<span class="token punctuation">.</span>com<span class="token punctuation">)</span>
|
||||
|
|
@ -79,7 +79,7 @@
|
|||
</tbody>
|
||||
</table>
|
||||
<p><strong>Example</strong></p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>Container</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>Container</span>
|
||||
<span class="token attr-name">padding</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">[</span><span class="token string">'bottom'</span><span class="token punctuation">,</span> <span class="token string">'top'</span><span class="token punctuation">]</span><span class="token punctuation">}</span></span>
|
||||
<span class="token attr-name">background</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>light<span class="token punctuation">"</span></span>
|
||||
<span class="token attr-name">className</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>myCustomClass<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
|
|
@ -144,19 +144,19 @@
|
|||
<h2><a class="anchor" aria-hidden="true" id="translating-strings"></a><a href="#translating-strings" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Translating Strings</h2>
|
||||
<p>When translations are enabled, any pages inside <code>website/pages/en</code> will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the <code>languages.js</code> file. E.g. The url for a French page of <code>website/pages/en/help.js</code> would be found at <code>${baseUrl}fr/help.html</code>.</p>
|
||||
<p>When writing pages that you wish to translate, wrap any strings to be translated inside a <code><translate></code> tag. e.g.,</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span><span class="token punctuation">></span></span><span class="token constant">I</span> like translations<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>p</span><span class="token punctuation">></span></span>
|
||||
</code></pre>
|
||||
<p>You can also provide an optional description attribute to provide context for translators. e.g,</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>a</span> <span class="token attr-name">href</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>/community<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>a</span> <span class="token attr-name">href</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>/community<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span> <span class="token attr-name">desc</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>Footer link to page referring to community GitHub and Slack<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>
|
||||
Community
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>a</span><span class="token punctuation">></span></span>
|
||||
</code></pre>
|
||||
<p>Add the following require statement as well:</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> translate = <span class="hljs-built_in">require</span>(<span class="hljs-string">'../../server/translate.js'</span>).translate;
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> translate = <span class="hljs-built_in">require</span>(<span class="hljs-string">'../../server/translate.js'</span>).translate;
|
||||
</code></pre>
|
||||
<p>Note that this path is valid for files inside <code>pages/en</code> and should be adjusted accordingly if files are in different locations, as discussed <a href="#page-require-paths">above</a>.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="using-static-assets"></a><a href="#using-static-assets" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Using Static Assets</h2>
|
||||
|
|
|
|||
|
|
@ -121,7 +121,7 @@
|
|||
<p>Now, when Docusaurus generates or builds your site, it will copy the file from <code>static/index.html</code> and place it in the site's main folder. The static file is served when a visitor arrives on your page. When the page loads it will redirect the visitor to <code>/blog</code>.</p>
|
||||
</blockquote>
|
||||
<p>You can use this template:</p>
|
||||
<pre><code class="hljs css languages- <!DOCTYPE HTML>"><span class="hljs-tag"><<span class="hljs-name">html</span> <span class="hljs-attr">lang</span>=<span class="hljs-string">"en-US"</span>></span>
|
||||
<pre><code class="hljs css languages-<!DOCTYPE HTML>"><span class="hljs-tag"><<span class="hljs-name">html</span> <span class="hljs-attr">lang</span>=<span class="hljs-string">"en-US"</span>></span>
|
||||
<span class="hljs-tag"><<span class="hljs-name">head</span>></span>
|
||||
<span class="hljs-tag"><<span class="hljs-name">meta</span> <span class="hljs-attr">charset</span>=<span class="hljs-string">"UTF-8"</span>></span>
|
||||
<span class="hljs-tag"><<span class="hljs-name">meta</span> <span class="hljs-attr">http-equiv</span>=<span class="hljs-string">"refresh"</span> <span class="hljs-attr">content</span>=<span class="hljs-string">"0; url=blog/"</span>></span>
|
||||
|
|
|
|||
|
|
@ -121,7 +121,7 @@
|
|||
<p>Now, when Docusaurus generates or builds your site, it will copy the file from <code>static/index.html</code> and place it in the site's main folder. The static file is served when a visitor arrives on your page. When the page loads it will redirect the visitor to <code>/blog</code>.</p>
|
||||
</blockquote>
|
||||
<p>You can use this template:</p>
|
||||
<pre><code class="hljs css languages- <!DOCTYPE HTML>"><span class="hljs-tag"><<span class="hljs-name">html</span> <span class="hljs-attr">lang</span>=<span class="hljs-string">"en-US"</span>></span>
|
||||
<pre><code class="hljs css languages-<!DOCTYPE HTML>"><span class="hljs-tag"><<span class="hljs-name">html</span> <span class="hljs-attr">lang</span>=<span class="hljs-string">"en-US"</span>></span>
|
||||
<span class="hljs-tag"><<span class="hljs-name">head</span>></span>
|
||||
<span class="hljs-tag"><<span class="hljs-name">meta</span> <span class="hljs-attr">charset</span>=<span class="hljs-string">"UTF-8"</span>></span>
|
||||
<span class="hljs-tag"><<span class="hljs-name">meta</span> <span class="hljs-attr">http-equiv</span>=<span class="hljs-string">"refresh"</span> <span class="hljs-attr">content</span>=<span class="hljs-string">"0; url=blog/"</span>></span>
|
||||
|
|
|
|||
|
|
@ -100,7 +100,7 @@
|
|||
<li><code>USE_SSH</code>: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.</li>
|
||||
</ul>
|
||||
<p>e.g.,</p>
|
||||
<pre><code class="hljs css languages- bash">GIT_USER=docusaurus-bot USE_SSH=<span class="hljs-literal">true</span> yarn run publish-gh-pages
|
||||
<pre><code class="hljs css languages-bash">GIT_USER=docusaurus-bot USE_SSH=<span class="hljs-literal">true</span> yarn run publish-gh-pages
|
||||
</code></pre>
|
||||
<p>The following environment variables are <a href="https://circleci.com/docs/1.0/environment-variables/">set by CircleCI</a> during the build process.</p>
|
||||
<ul>
|
||||
|
|
|
|||
|
|
@ -100,7 +100,7 @@
|
|||
<li><code>USE_SSH</code>: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.</li>
|
||||
</ul>
|
||||
<p>e.g.,</p>
|
||||
<pre><code class="hljs css languages- bash">GIT_USER=docusaurus-bot USE_SSH=<span class="hljs-literal">true</span> yarn run publish-gh-pages
|
||||
<pre><code class="hljs css languages-bash">GIT_USER=docusaurus-bot USE_SSH=<span class="hljs-literal">true</span> yarn run publish-gh-pages
|
||||
</code></pre>
|
||||
<p>The following environment variables are <a href="https://circleci.com/docs/1.0/environment-variables/">set by CircleCI</a> during the build process.</p>
|
||||
<ul>
|
||||
|
|
|
|||
|
|
@ -53,7 +53,7 @@
|
|||
<p>You can <a href="/docs/en/1.0.14/site-preparation#verifying-installation">start</a> your local server and go to <code>http://localhost:3000</code> to see what the example home page looks like. From there, edit the <code>website/pages/en/index.js</code> file and its various components to use the images and text you want for your project.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="adding-other-custom-pages"></a><a href="#adding-other-custom-pages" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Adding Other Custom Pages</h2>
|
||||
<p>Docusaurus provides some simple example pages in the <code>website/pages/en</code> directory, including <code>index.js</code>, <code>users.js</code>, and <code>help.js</code>. These are good examples to showcase how to create a custom page for Docusaurus.</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs
|
||||
└── website
|
||||
│ └── blog
|
||||
|
|
@ -85,7 +85,7 @@
|
|||
<p>Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.</p>
|
||||
<p>Your footer will automatically get applied to all pages on your site, including docs and blog posts. The sole exception to this is any static html pages you include.</p>
|
||||
<p>If you do not want a footer for your site, change the <code>render</code> function of <code>core/Footer.js</code> to return <code>null</code>. e.g.,</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token keyword">const</span> React <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">"react"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token keyword">const</span> React <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">"react"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token keyword">class</span> <span class="token class-name">Footer</span> <span class="token keyword">extends</span> <span class="token class-name">React<span class="token punctuation">.</span>Component</span> <span class="token punctuation">{</span>
|
||||
<span class="token function">render</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
|
|
|
|||
|
|
@ -53,7 +53,7 @@
|
|||
<p>You can <a href="/docs/en/1.0.14/site-preparation#verifying-installation">start</a> your local server and go to <code>http://localhost:3000</code> to see what the example home page looks like. From there, edit the <code>website/pages/en/index.js</code> file and its various components to use the images and text you want for your project.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="adding-other-custom-pages"></a><a href="#adding-other-custom-pages" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Adding Other Custom Pages</h2>
|
||||
<p>Docusaurus provides some simple example pages in the <code>website/pages/en</code> directory, including <code>index.js</code>, <code>users.js</code>, and <code>help.js</code>. These are good examples to showcase how to create a custom page for Docusaurus.</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs
|
||||
└── website
|
||||
│ └── blog
|
||||
|
|
@ -85,7 +85,7 @@
|
|||
<p>Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.</p>
|
||||
<p>Your footer will automatically get applied to all pages on your site, including docs and blog posts. The sole exception to this is any static html pages you include.</p>
|
||||
<p>If you do not want a footer for your site, change the <code>render</code> function of <code>core/Footer.js</code> to return <code>null</code>. e.g.,</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token keyword">const</span> React <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">"react"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token keyword">const</span> React <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">"react"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
||||
|
||||
<span class="token keyword">class</span> <span class="token class-name">Footer</span> <span class="token keyword">extends</span> <span class="token class-name">React<span class="token punctuation">.</span>Component</span> <span class="token punctuation">{</span>
|
||||
<span class="token function">render</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
||||
|
|
|
|||
|
|
@ -55,7 +55,7 @@
|
|||
<p><code>hide_title</code>: Whether to hide the title at the top of the doc.</p>
|
||||
<p><code>sidebar_label</code>: The text shown in the document sidebar for this document. If this field is not present, the document's <code>sidebar_label</code> will default to its <code>title</code>.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
id: doc1
|
||||
title: My Document
|
||||
<span class="hljs-section">sidebar_label: Document
|
||||
|
|
@ -63,7 +63,7 @@ title: My Document
|
|||
</code></pre>
|
||||
<p>Versioned documents have their ids altered to include the version number when they get copied. The new <code>id</code> is <code>version-${version}-${id}</code> where <code>${version}</code> is the version number of that document and <code>${id}</code> is the original <code>id</code>. Additionally, versioned documents get an added <code>original_id</code> field with the original document id.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
id: version-1.0.0-doc1
|
||||
title: My Document
|
||||
sidebar_label: Document
|
||||
|
|
@ -72,7 +72,7 @@ sidebar_label: Document
|
|||
</code></pre>
|
||||
<p><code>custom_edit_url</code>: The url for editing this document. If this field is not present, the document's edit url will fallback to <code>editUrl</code> from optional fields of <code>siteConfig.js</code>. See <a href="site-config.md">siteConfig.js</a> docs for more information.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
id: doc-markdown
|
||||
title: Markdown Features
|
||||
<span class="hljs-section">custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
|
||||
|
|
@ -85,7 +85,7 @@ title: Markdown Features
|
|||
<p><code>authorURL</code>: A page to link to when a site user clicks the author's name. If this field is omitted, the author's name will not link to anything.</p>
|
||||
<p><code>authorFBID</code>: The author's Facebook id, used only to get the author's profile picture to display with the blog post. If this field is omitted, no author picture will be shown for the blog post.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
title: My First Blog Post
|
||||
author: Frank Li
|
||||
authorURL: http://twitter.com/franchementli
|
||||
|
|
@ -97,20 +97,20 @@ authorURL: http://twitter.com/franchementli
|
|||
<h3><a class="anchor" aria-hidden="true" id="linking-other-documents"></a><a href="#linking-other-documents" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Linking other Documents</h3>
|
||||
<p>You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- markdown">[<span class="hljs-string">This links to another document</span>](<span class="hljs-link">other-document.md</span>)
|
||||
<pre><code class="hljs css languages-markdown">[<span class="hljs-string">This links to another document</span>](<span class="hljs-link">other-document.md</span>)
|
||||
</code></pre>
|
||||
<p>This markdown will automatically get converted into a link to <code>/docs/other-document.html</code> (or the appropriately translated/versioned link) once it gets rendered.</p>
|
||||
<p>This can help when you want to navigate through docs on GitHub since the links there will be functional links to other documents (still on GitHub), but the documents will have the correct html links when they get rendered.</p>
|
||||
<h3><a class="anchor" aria-hidden="true" id="linking-to-images-and-other-assets"></a><a href="#linking-to-images-and-other-assets" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Linking to Images and Other Assets</h3>
|
||||
<p>Static assets can be linked to in the same way that documents are, using relative urls. Static assets used in documents and blogs should go into <code>docs/assets</code> and <code>website/blog/assets</code>, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- markdown">![<span class="hljs-string">alt-text</span>](<span class="hljs-link">/docs/assets/doc-image.png</span>)
|
||||
<pre><code class="hljs css languages-markdown">![<span class="hljs-string">alt-text</span>](<span class="hljs-link">/docs/assets/doc-image.png</span>)
|
||||
</code></pre>
|
||||
<h3><a class="anchor" aria-hidden="true" id="generating-table-of-contents"></a><a href="#generating-table-of-contents" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Generating Table of Contents</h3>
|
||||
<p>You can make an autogenerated list of links, which can be useful as a table of contents for API docs.</p>
|
||||
<p>In your markdown file, insert a line with the text <<code>AUTOGENERATED_TABLE_OF_CONTENTS</code>>. Write your documentation using <code>h3</code> headers for each function inside a code block. These will be found by Docusaurus and a list of links to these sections will inserted at the text <<code>AUTOGENERATED_TABLE_OF_CONTENTS</code>>.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- markdown"><span class="hljs-section">### `docusaurus.function(a, b)`</span>
|
||||
<pre><code class="hljs css languages-markdown"><span class="hljs-section">### `docusaurus.function(a, b)`</span>
|
||||
|
||||
Text describing my function
|
||||
|
||||
|
|
@ -120,7 +120,7 @@ Text describing my function
|
|||
Text describing my function
|
||||
</code></pre>
|
||||
<p>will lead to a table of contents of the functions:</p>
|
||||
<pre><code class="hljs css languages- markdown"><span class="hljs-bullet">- </span><span class="hljs-code">`docusaurus.function(a, b)`</span>
|
||||
<pre><code class="hljs css languages-markdown"><span class="hljs-bullet">- </span><span class="hljs-code">`docusaurus.function(a, b)`</span>
|
||||
<span class="hljs-bullet">- </span><span class="hljs-code">`docdoc(file)`</span>
|
||||
</code></pre>
|
||||
<p>and each function will link to their corresponding sections in the page.</p>
|
||||
|
|
@ -134,20 +134,20 @@ ReactDOM.render(
|
|||
```
|
||||
</code></pre>
|
||||
<p>...would be rendered with syntax highlighting like so:</p>
|
||||
<pre><code class="hljs css languages- javascript">ReactDOM.render(
|
||||
<pre><code class="hljs css languages-javascript">ReactDOM.render(
|
||||
<span class="xml"><span class="hljs-tag"><<span class="hljs-name">h1</span>></span>Hello, world!<span class="hljs-tag"></<span class="hljs-name">h1</span>></span></span>,
|
||||
<span class="hljs-built_in">document</span>.getElementById(<span class="hljs-string">'root'</span>)
|
||||
);
|
||||
</code></pre>
|
||||
<p>Highlighting is provided by <a href="https://highlightjs.org">Highlight.js</a> using the theme specified in your <code>siteConfig.js</code> file as part of the <code>highlight</code> key:</p>
|
||||
<pre><code class="hljs css languages- javascript">highlight: {
|
||||
<pre><code class="hljs css languages-javascript">highlight: {
|
||||
<span class="hljs-attr">theme</span>: <span class="hljs-string">'default'</span>
|
||||
}
|
||||
</code></pre>
|
||||
<p>You can find the full list of supported themes in the Highlight.js <a href="https://github.com/isagalaev/highlight.js/tree/master/src/styles"><code>styles</code></a> directory.</p>
|
||||
<h3><a class="anchor" aria-hidden="true" id="registering-additional-languages"></a><a href="#registering-additional-languages" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Registering additional languages</h3>
|
||||
<p>While Highlight.js provides support for <a href="https://highlightjs.org/static/demo/">many popular languages out of the box</a>, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the <code>hljs</code> constant as part of the <code>highlight</code> config key. This in turn allows you to call <a href="http://highlightjs.readthedocs.io/en/latest/api.html#registerlanguage-name-language"><code>registerLanguage</code></a>:</p>
|
||||
<pre><code class="hljs css languages- javascript">highlight: {
|
||||
<pre><code class="hljs css languages-javascript">highlight: {
|
||||
<span class="hljs-attr">theme</span>: <span class="hljs-string">'default'</span>,
|
||||
<span class="hljs-attr">hljs</span>: <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">hljs</span>) </span>{
|
||||
hljs.registerLanguage(<span class="hljs-string">'galacticbasic'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">hljs</span>) </span>{
|
||||
|
|
|
|||
|
|
@ -55,7 +55,7 @@
|
|||
<p><code>hide_title</code>: Whether to hide the title at the top of the doc.</p>
|
||||
<p><code>sidebar_label</code>: The text shown in the document sidebar for this document. If this field is not present, the document's <code>sidebar_label</code> will default to its <code>title</code>.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
id: doc1
|
||||
title: My Document
|
||||
<span class="hljs-section">sidebar_label: Document
|
||||
|
|
@ -63,7 +63,7 @@ title: My Document
|
|||
</code></pre>
|
||||
<p>Versioned documents have their ids altered to include the version number when they get copied. The new <code>id</code> is <code>version-${version}-${id}</code> where <code>${version}</code> is the version number of that document and <code>${id}</code> is the original <code>id</code>. Additionally, versioned documents get an added <code>original_id</code> field with the original document id.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
id: version-1.0.0-doc1
|
||||
title: My Document
|
||||
sidebar_label: Document
|
||||
|
|
@ -72,7 +72,7 @@ sidebar_label: Document
|
|||
</code></pre>
|
||||
<p><code>custom_edit_url</code>: The url for editing this document. If this field is not present, the document's edit url will fallback to <code>editUrl</code> from optional fields of <code>siteConfig.js</code>. See <a href="site-config.md">siteConfig.js</a> docs for more information.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
id: doc-markdown
|
||||
title: Markdown Features
|
||||
<span class="hljs-section">custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
|
||||
|
|
@ -85,7 +85,7 @@ title: Markdown Features
|
|||
<p><code>authorURL</code>: A page to link to when a site user clicks the author's name. If this field is omitted, the author's name will not link to anything.</p>
|
||||
<p><code>authorFBID</code>: The author's Facebook id, used only to get the author's profile picture to display with the blog post. If this field is omitted, no author picture will be shown for the blog post.</p>
|
||||
<p>For example:</p>
|
||||
<pre><code class="hljs css languages- markdown">---
|
||||
<pre><code class="hljs css languages-markdown">---
|
||||
title: My First Blog Post
|
||||
author: Frank Li
|
||||
authorURL: http://twitter.com/franchementli
|
||||
|
|
@ -97,20 +97,20 @@ authorURL: http://twitter.com/franchementli
|
|||
<h3><a class="anchor" aria-hidden="true" id="linking-other-documents"></a><a href="#linking-other-documents" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Linking other Documents</h3>
|
||||
<p>You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- markdown">[<span class="hljs-string">This links to another document</span>](<span class="hljs-link">other-document.md</span>)
|
||||
<pre><code class="hljs css languages-markdown">[<span class="hljs-string">This links to another document</span>](<span class="hljs-link">other-document.md</span>)
|
||||
</code></pre>
|
||||
<p>This markdown will automatically get converted into a link to <code>/docs/other-document.html</code> (or the appropriately translated/versioned link) once it gets rendered.</p>
|
||||
<p>This can help when you want to navigate through docs on GitHub since the links there will be functional links to other documents (still on GitHub), but the documents will have the correct html links when they get rendered.</p>
|
||||
<h3><a class="anchor" aria-hidden="true" id="linking-to-images-and-other-assets"></a><a href="#linking-to-images-and-other-assets" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Linking to Images and Other Assets</h3>
|
||||
<p>Static assets can be linked to in the same way that documents are, using relative urls. Static assets used in documents and blogs should go into <code>docs/assets</code> and <code>website/blog/assets</code>, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- markdown">![<span class="hljs-string">alt-text</span>](<span class="hljs-link">/docs/assets/doc-image.png</span>)
|
||||
<pre><code class="hljs css languages-markdown">![<span class="hljs-string">alt-text</span>](<span class="hljs-link">/docs/assets/doc-image.png</span>)
|
||||
</code></pre>
|
||||
<h3><a class="anchor" aria-hidden="true" id="generating-table-of-contents"></a><a href="#generating-table-of-contents" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Generating Table of Contents</h3>
|
||||
<p>You can make an autogenerated list of links, which can be useful as a table of contents for API docs.</p>
|
||||
<p>In your markdown file, insert a line with the text <<code>AUTOGENERATED_TABLE_OF_CONTENTS</code>>. Write your documentation using <code>h3</code> headers for each function inside a code block. These will be found by Docusaurus and a list of links to these sections will inserted at the text <<code>AUTOGENERATED_TABLE_OF_CONTENTS</code>>.</p>
|
||||
<p>Example:</p>
|
||||
<pre><code class="hljs css languages- markdown"><span class="hljs-section">### `docusaurus.function(a, b)`</span>
|
||||
<pre><code class="hljs css languages-markdown"><span class="hljs-section">### `docusaurus.function(a, b)`</span>
|
||||
|
||||
Text describing my function
|
||||
|
||||
|
|
@ -120,7 +120,7 @@ Text describing my function
|
|||
Text describing my function
|
||||
</code></pre>
|
||||
<p>will lead to a table of contents of the functions:</p>
|
||||
<pre><code class="hljs css languages- markdown"><span class="hljs-bullet">- </span><span class="hljs-code">`docusaurus.function(a, b)`</span>
|
||||
<pre><code class="hljs css languages-markdown"><span class="hljs-bullet">- </span><span class="hljs-code">`docusaurus.function(a, b)`</span>
|
||||
<span class="hljs-bullet">- </span><span class="hljs-code">`docdoc(file)`</span>
|
||||
</code></pre>
|
||||
<p>and each function will link to their corresponding sections in the page.</p>
|
||||
|
|
@ -134,20 +134,20 @@ ReactDOM.render(
|
|||
```
|
||||
</code></pre>
|
||||
<p>...would be rendered with syntax highlighting like so:</p>
|
||||
<pre><code class="hljs css languages- javascript">ReactDOM.render(
|
||||
<pre><code class="hljs css languages-javascript">ReactDOM.render(
|
||||
<span class="xml"><span class="hljs-tag"><<span class="hljs-name">h1</span>></span>Hello, world!<span class="hljs-tag"></<span class="hljs-name">h1</span>></span></span>,
|
||||
<span class="hljs-built_in">document</span>.getElementById(<span class="hljs-string">'root'</span>)
|
||||
);
|
||||
</code></pre>
|
||||
<p>Highlighting is provided by <a href="https://highlightjs.org">Highlight.js</a> using the theme specified in your <code>siteConfig.js</code> file as part of the <code>highlight</code> key:</p>
|
||||
<pre><code class="hljs css languages- javascript">highlight: {
|
||||
<pre><code class="hljs css languages-javascript">highlight: {
|
||||
<span class="hljs-attr">theme</span>: <span class="hljs-string">'default'</span>
|
||||
}
|
||||
</code></pre>
|
||||
<p>You can find the full list of supported themes in the Highlight.js <a href="https://github.com/isagalaev/highlight.js/tree/master/src/styles"><code>styles</code></a> directory.</p>
|
||||
<h3><a class="anchor" aria-hidden="true" id="registering-additional-languages"></a><a href="#registering-additional-languages" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Registering additional languages</h3>
|
||||
<p>While Highlight.js provides support for <a href="https://highlightjs.org/static/demo/">many popular languages out of the box</a>, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the <code>hljs</code> constant as part of the <code>highlight</code> config key. This in turn allows you to call <a href="http://highlightjs.readthedocs.io/en/latest/api.html#registerlanguage-name-language"><code>registerLanguage</code></a>:</p>
|
||||
<pre><code class="hljs css languages- javascript">highlight: {
|
||||
<pre><code class="hljs css languages-javascript">highlight: {
|
||||
<span class="hljs-attr">theme</span>: <span class="hljs-string">'default'</span>,
|
||||
<span class="hljs-attr">hljs</span>: <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">hljs</span>) </span>{
|
||||
hljs.registerLanguage(<span class="hljs-string">'galacticbasic'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">hljs</span>) </span>{
|
||||
|
|
|
|||
|
|
@ -64,7 +64,7 @@
|
|||
</blockquote>
|
||||
<h2><a class="anchor" aria-hidden="true" id="verifying-installation"></a><a href="#verifying-installation" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Verifying Installation</h2>
|
||||
<p>Along with previously existing files and directories, your root directory will now contain a structure similar to:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs-examples-from-docusaurus
|
||||
│ └── doc1.md
|
||||
│ └── doc2.md
|
||||
|
|
|
|||
|
|
@ -64,7 +64,7 @@
|
|||
</blockquote>
|
||||
<h2><a class="anchor" aria-hidden="true" id="verifying-installation"></a><a href="#verifying-installation" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Verifying Installation</h2>
|
||||
<p>Along with previously existing files and directories, your root directory will now contain a structure similar to:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs-examples-from-docusaurus
|
||||
│ └── doc1.md
|
||||
│ └── doc2.md
|
||||
|
|
|
|||
|
|
@ -107,7 +107,7 @@
|
|||
</table>
|
||||
<p>Once you have the parameter value information, you can go ahead and run the publish script, ensuring you have inserted your own values inside the various parameter placeholders:</p>
|
||||
<p>To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate.</p>
|
||||
<pre><code class="hljs css languages- bash">GIT_USER=<GIT_USER> \
|
||||
<pre><code class="hljs css languages-bash">GIT_USER=<GIT_USER> \
|
||||
CURRENT_BRANCH=master \
|
||||
USE_SSH=<span class="hljs-literal">true</span> \
|
||||
yarn run publish-gh-pages <span class="hljs-comment"># or `npm run publish-gh-pages`</span>
|
||||
|
|
@ -131,7 +131,7 @@
|
|||
<li>Create a <code>.circleci</code> folder and create a <code>config.yml</code> under that folder.</li>
|
||||
<li>Copy the text below into <code>.circleci/config.yml</code>.</li>
|
||||
</ol>
|
||||
<pre><code class="hljs css languages- yml"><span class="hljs-comment"># If you only one circle to run on direct commits to master, you can uncomment this out</span>
|
||||
<pre><code class="hljs css languages-yml"><span class="hljs-comment"># If you only one circle to run on direct commits to master, you can uncomment this out</span>
|
||||
<span class="hljs-comment"># and uncomment the filters: *filter-only-master down below too</span>
|
||||
<span class="hljs-comment">#</span>
|
||||
<span class="hljs-comment"># aliases:</span>
|
||||
|
|
@ -178,7 +178,7 @@
|
|||
</blockquote>
|
||||
<h3><a class="anchor" aria-hidden="true" id="tips-tricks"></a><a href="#tips-tricks" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Tips & Tricks</h3>
|
||||
<p>When initially deploying to a <code>gh-pages</code> branch using Circle CI, you may notice that some jobs triggered by commits to the <code>gh-pages</code> branch fail to run successfully due to a lack of tests. You can easily work around this by creating a basic Circle CI config with the following contents:</p>
|
||||
<pre><code class="hljs css languages- yml"><span class="hljs-comment"># Circle CI 2.0 Config File</span>
|
||||
<pre><code class="hljs css languages-yml"><span class="hljs-comment"># Circle CI 2.0 Config File</span>
|
||||
<span class="hljs-comment"># This config file will prevent tests from being run on the gh-pages branch.</span>
|
||||
<span class="hljs-attr">version:</span> <span class="hljs-number">2</span>
|
||||
<span class="hljs-attr">jobs:</span>
|
||||
|
|
|
|||
|
|
@ -107,7 +107,7 @@
|
|||
</table>
|
||||
<p>Once you have the parameter value information, you can go ahead and run the publish script, ensuring you have inserted your own values inside the various parameter placeholders:</p>
|
||||
<p>To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate.</p>
|
||||
<pre><code class="hljs css languages- bash">GIT_USER=<GIT_USER> \
|
||||
<pre><code class="hljs css languages-bash">GIT_USER=<GIT_USER> \
|
||||
CURRENT_BRANCH=master \
|
||||
USE_SSH=<span class="hljs-literal">true</span> \
|
||||
yarn run publish-gh-pages <span class="hljs-comment"># or `npm run publish-gh-pages`</span>
|
||||
|
|
@ -131,7 +131,7 @@
|
|||
<li>Create a <code>.circleci</code> folder and create a <code>config.yml</code> under that folder.</li>
|
||||
<li>Copy the text below into <code>.circleci/config.yml</code>.</li>
|
||||
</ol>
|
||||
<pre><code class="hljs css languages- yml"><span class="hljs-comment"># If you only one circle to run on direct commits to master, you can uncomment this out</span>
|
||||
<pre><code class="hljs css languages-yml"><span class="hljs-comment"># If you only one circle to run on direct commits to master, you can uncomment this out</span>
|
||||
<span class="hljs-comment"># and uncomment the filters: *filter-only-master down below too</span>
|
||||
<span class="hljs-comment">#</span>
|
||||
<span class="hljs-comment"># aliases:</span>
|
||||
|
|
@ -178,7 +178,7 @@
|
|||
</blockquote>
|
||||
<h3><a class="anchor" aria-hidden="true" id="tips-tricks"></a><a href="#tips-tricks" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Tips & Tricks</h3>
|
||||
<p>When initially deploying to a <code>gh-pages</code> branch using Circle CI, you may notice that some jobs triggered by commits to the <code>gh-pages</code> branch fail to run successfully due to a lack of tests. You can easily work around this by creating a basic Circle CI config with the following contents:</p>
|
||||
<pre><code class="hljs css languages- yml"><span class="hljs-comment"># Circle CI 2.0 Config File</span>
|
||||
<pre><code class="hljs css languages-yml"><span class="hljs-comment"># Circle CI 2.0 Config File</span>
|
||||
<span class="hljs-comment"># This config file will prevent tests from being run on the gh-pages branch.</span>
|
||||
<span class="hljs-attr">version:</span> <span class="hljs-number">2</span>
|
||||
<span class="hljs-attr">jobs:</span>
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@
|
|||
</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/facebook/docusaurus/edit/master/docs/guides-search.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 class="postHeaderTitle">Enabling Search</h1></header><article><div><span><p>Docusaurus supports search using <a href="https://community.algolia.com/docsearch/">Algolia DocSearch</a>. Once you have set up your site, <a href="https://community.algolia.com/docsearch/">enter your site information</a> to have Algolia crawl your website's documentation pages. Algolia will then send you an API key and index name for your site.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="enabling-the-search-bar"></a><a href="#enabling-the-search-bar" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Enabling the Search Bar</h2>
|
||||
<p>Enter your search-only API key and index name into <code>siteConfig.js</code> in the <code>algolia</code> section to enable search for your site.</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
...
|
||||
algolia: {
|
||||
<span class="hljs-attr">apiKey</span>: <span class="hljs-string">"my-search-only-api-key-1234"</span>,
|
||||
|
|
@ -61,7 +61,7 @@
|
|||
</code></pre>
|
||||
<h2><a class="anchor" aria-hidden="true" id="extra-search-options"></a><a href="#extra-search-options" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Extra Search Options</h2>
|
||||
<p>You can also specify extra <a href="https://community.algolia.com/docsearch/documentation/">search options used by Algolia</a> by using an <code>algoliaOptions</code> field in <code>algolia</code>. This may be useful if you want to provide different search results for the different versions or languages of your docs. Any occurrences of "VERSION" or "LANGUAGE" will be replaced by the version or language of the current page, respectively. More details about search options can be <a href="https://www.algolia.com/doc/api-reference/api-parameters/#overview">found here</a>.</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
...
|
||||
algolia: {
|
||||
...
|
||||
|
|
@ -75,7 +75,7 @@
|
|||
<h2><a class="anchor" aria-hidden="true" id="controlling-the-location-of-the-search-bar"></a><a href="#controlling-the-location-of-the-search-bar" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Controlling the Location of the Search Bar</h2>
|
||||
<p>By default, the search bar will be the rightmost element in the top navigation bar.</p>
|
||||
<p>If you want to change the default location, add the <code>searchBar</code> flag in the <code>headerLinks</code> field of <code>siteConfig.js</code> in your desired location. For example, you may want the search bar in between your internal and external links.</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
...
|
||||
headerLinks: [
|
||||
{...}
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@
|
|||
</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/facebook/docusaurus/edit/master/docs/guides-search.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 class="postHeaderTitle">Enabling Search</h1></header><article><div><span><p>Docusaurus supports search using <a href="https://community.algolia.com/docsearch/">Algolia DocSearch</a>. Once you have set up your site, <a href="https://community.algolia.com/docsearch/">enter your site information</a> to have Algolia crawl your website's documentation pages. Algolia will then send you an API key and index name for your site.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="enabling-the-search-bar"></a><a href="#enabling-the-search-bar" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Enabling the Search Bar</h2>
|
||||
<p>Enter your search-only API key and index name into <code>siteConfig.js</code> in the <code>algolia</code> section to enable search for your site.</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
...
|
||||
algolia: {
|
||||
<span class="hljs-attr">apiKey</span>: <span class="hljs-string">"my-search-only-api-key-1234"</span>,
|
||||
|
|
@ -61,7 +61,7 @@
|
|||
</code></pre>
|
||||
<h2><a class="anchor" aria-hidden="true" id="extra-search-options"></a><a href="#extra-search-options" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Extra Search Options</h2>
|
||||
<p>You can also specify extra <a href="https://community.algolia.com/docsearch/documentation/">search options used by Algolia</a> by using an <code>algoliaOptions</code> field in <code>algolia</code>. This may be useful if you want to provide different search results for the different versions or languages of your docs. Any occurrences of "VERSION" or "LANGUAGE" will be replaced by the version or language of the current page, respectively. More details about search options can be <a href="https://www.algolia.com/doc/api-reference/api-parameters/#overview">found here</a>.</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
...
|
||||
algolia: {
|
||||
...
|
||||
|
|
@ -75,7 +75,7 @@
|
|||
<h2><a class="anchor" aria-hidden="true" id="controlling-the-location-of-the-search-bar"></a><a href="#controlling-the-location-of-the-search-bar" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Controlling the Location of the Search Bar</h2>
|
||||
<p>By default, the search bar will be the rightmost element in the top navigation bar.</p>
|
||||
<p>If you want to change the default location, add the <code>searchBar</code> flag in the <code>headerLinks</code> field of <code>siteConfig.js</code> in your desired location. For example, you may want the search bar in between your internal and external links.</p>
|
||||
<pre><code class="hljs css languages- js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
<pre><code class="hljs css languages-js"><span class="hljs-keyword">const</span> siteConfig = {
|
||||
...
|
||||
headerLinks: [
|
||||
{...}
|
||||
|
|
|
|||
|
|
@ -66,7 +66,7 @@
|
|||
<p><code>headerIcon</code> - url for icon used in header navigation bar.</p>
|
||||
<p><code>headerLinks</code> - Links that will be used in the header navigation bar. The <code>label</code> field of each object will be the link text and will also be translated for each language.</p>
|
||||
<p>Example Usage:</p>
|
||||
<pre><code class="hljs css languages- js">headerLinks: [
|
||||
<pre><code class="hljs css languages-js">headerLinks: [
|
||||
<span class="hljs-comment">// Links to document with id doc1 for current language/version</span>
|
||||
{ <span class="hljs-attr">doc</span>: <span class="hljs-string">"doc1"</span>, <span class="hljs-attr">label</span>: <span class="hljs-string">"Getting Started"</span> },
|
||||
<span class="hljs-comment">// Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language</span>
|
||||
|
|
@ -97,9 +97,9 @@
|
|||
<p><code>blogSidebarCount</code> - Control the number of blog posts that show up in the sidebar. See the <a href="/docs/en/1.0.14/adding-blog#changing-how-many-blog-posts-show-on-sidebar">adding a blog docs</a> for more information.</p>
|
||||
<p><code>cname</code> - The CNAME for your website. It will go into a <code>CNAME</code> file when your site it built.</p>
|
||||
<p><code>customDocsPath</code> - By default, Docusaurus expects your documentation to be in a directory called <code>docs</code>. This directory is at the same level as the <code>website</code> directory (i.e., not inside the <code>website</code> directory). You can specify a custom path to your documentation with this field. <strong>Note that all of your documentation <code>*.md</code> files must still reside in a flat hierarchy. You cannot have your documents in nested directories</strong>.</p>
|
||||
<pre><code class="hljs css languages- js">customDocsPath: <span class="hljs-string">"docs/site"</span>
|
||||
<pre><code class="hljs css languages-js">customDocsPath: <span class="hljs-string">"docs/site"</span>
|
||||
</code></pre>
|
||||
<pre><code class="hljs css languages- js">customDocsPath: <span class="hljs-string">"website-docs"</span>
|
||||
<pre><code class="hljs css languages-js">customDocsPath: <span class="hljs-string">"website-docs"</span>
|
||||
</code></pre>
|
||||
<p><code>disableHeaderTitle</code> - An option to disable showing the title in the header next to the header icon. Exclude this field to keep the header as normal, otherwise set to <code>true</code>.</p>
|
||||
<p><code>disableTitleTagline</code> - An option to disable showing the tagline in the title of main pages. Exclude this field to keep page titles as <code>Title • Tagline</code>. Set to <code>true</code> to make page titles just <code>Title</code>.</p>
|
||||
|
|
|
|||
|
|
@ -66,7 +66,7 @@
|
|||
<p><code>headerIcon</code> - url for icon used in header navigation bar.</p>
|
||||
<p><code>headerLinks</code> - Links that will be used in the header navigation bar. The <code>label</code> field of each object will be the link text and will also be translated for each language.</p>
|
||||
<p>Example Usage:</p>
|
||||
<pre><code class="hljs css languages- js">headerLinks: [
|
||||
<pre><code class="hljs css languages-js">headerLinks: [
|
||||
<span class="hljs-comment">// Links to document with id doc1 for current language/version</span>
|
||||
{ <span class="hljs-attr">doc</span>: <span class="hljs-string">"doc1"</span>, <span class="hljs-attr">label</span>: <span class="hljs-string">"Getting Started"</span> },
|
||||
<span class="hljs-comment">// Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language</span>
|
||||
|
|
@ -97,9 +97,9 @@
|
|||
<p><code>blogSidebarCount</code> - Control the number of blog posts that show up in the sidebar. See the <a href="/docs/en/1.0.14/adding-blog#changing-how-many-blog-posts-show-on-sidebar">adding a blog docs</a> for more information.</p>
|
||||
<p><code>cname</code> - The CNAME for your website. It will go into a <code>CNAME</code> file when your site it built.</p>
|
||||
<p><code>customDocsPath</code> - By default, Docusaurus expects your documentation to be in a directory called <code>docs</code>. This directory is at the same level as the <code>website</code> directory (i.e., not inside the <code>website</code> directory). You can specify a custom path to your documentation with this field. <strong>Note that all of your documentation <code>*.md</code> files must still reside in a flat hierarchy. You cannot have your documents in nested directories</strong>.</p>
|
||||
<pre><code class="hljs css languages- js">customDocsPath: <span class="hljs-string">"docs/site"</span>
|
||||
<pre><code class="hljs css languages-js">customDocsPath: <span class="hljs-string">"docs/site"</span>
|
||||
</code></pre>
|
||||
<pre><code class="hljs css languages- js">customDocsPath: <span class="hljs-string">"website-docs"</span>
|
||||
<pre><code class="hljs css languages-js">customDocsPath: <span class="hljs-string">"website-docs"</span>
|
||||
</code></pre>
|
||||
<p><code>disableHeaderTitle</code> - An option to disable showing the title in the header next to the header icon. Exclude this field to keep the header as normal, otherwise set to <code>true</code>.</p>
|
||||
<p><code>disableTitleTagline</code> - An option to disable showing the tagline in the title of main pages. Exclude this field to keep page titles as <code>Title • Tagline</code>. Set to <code>true</code> to make page titles just <code>Title</code>.</p>
|
||||
|
|
|
|||
|
|
@ -51,7 +51,7 @@
|
|||
<p>After <a href="/docs/en/1.0.14/installation">installation</a> and <a href="/docs/en/1.0.14/site-preparation">preparation</a>, much of the work to create a basic site for your docs is already complete.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="site-structure"></a><a href="#site-structure" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Site Structure</h2>
|
||||
<p>Your site structure looks like the following:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs
|
||||
└── website
|
||||
│ └── blog
|
||||
|
|
@ -104,7 +104,7 @@ yarn <span class="hljs-builtin-name">run</span> start # <span class="hljs-keywor
|
|||
<li>Remove the <code>index.js</code> file from the <code>website/pages</code> directory, if it exists.</li>
|
||||
<li>Add a <a href="/docs/en/1.0.14/custom-pages#adding-static-pages">custom static <code>index.html</code> page</a> in the <code>website/static</code> folder with the following contents:</li>
|
||||
</ol>
|
||||
<pre><code class="hljs css languages- html"><span class="hljs-meta"><!DOCTYPE HTML></span>
|
||||
<pre><code class="hljs css languages-html"><span class="hljs-meta"><!DOCTYPE HTML></span>
|
||||
<span class="hljs-tag"><<span class="hljs-name">html</span> <span class="hljs-attr">lang</span>=<span class="hljs-string">"en-US"</span>></span>
|
||||
<span class="hljs-tag"><<span class="hljs-name">head</span>></span>
|
||||
<span class="hljs-tag"><<span class="hljs-name">meta</span> <span class="hljs-attr">charset</span>=<span class="hljs-string">"UTF-8"</span>></span>
|
||||
|
|
|
|||
|
|
@ -51,7 +51,7 @@
|
|||
<p>After <a href="/docs/en/1.0.14/installation">installation</a> and <a href="/docs/en/1.0.14/site-preparation">preparation</a>, much of the work to create a basic site for your docs is already complete.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="site-structure"></a><a href="#site-structure" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Site Structure</h2>
|
||||
<p>Your site structure looks like the following:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs
|
||||
└── website
|
||||
│ └── blog
|
||||
|
|
@ -104,7 +104,7 @@ yarn <span class="hljs-builtin-name">run</span> start # <span class="hljs-keywor
|
|||
<li>Remove the <code>index.js</code> file from the <code>website/pages</code> directory, if it exists.</li>
|
||||
<li>Add a <a href="/docs/en/1.0.14/custom-pages#adding-static-pages">custom static <code>index.html</code> page</a> in the <code>website/static</code> folder with the following contents:</li>
|
||||
</ol>
|
||||
<pre><code class="hljs css languages- html"><span class="hljs-meta"><!DOCTYPE HTML></span>
|
||||
<pre><code class="hljs css languages-html"><span class="hljs-meta"><!DOCTYPE HTML></span>
|
||||
<span class="hljs-tag"><<span class="hljs-name">html</span> <span class="hljs-attr">lang</span>=<span class="hljs-string">"en-US"</span>></span>
|
||||
<span class="hljs-tag"><<span class="hljs-name">head</span>></span>
|
||||
<span class="hljs-tag"><<span class="hljs-name">meta</span> <span class="hljs-attr">charset</span>=<span class="hljs-string">"UTF-8"</span>></span>
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@
|
|||
</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/facebook/docusaurus/edit/master/docs/getting-started-preparation.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 class="postHeaderTitle">Site Preparation</h1></header><article><div><span><p>After <a href="/docs/en/1.0.14/installation">installing Docusaurus</a>, you now have a skeleton to work from for your specific website. The following discusses the rest of the Docusaurus structure in order for you to prepare your site.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="directory-structure"></a><a href="#directory-structure" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Directory Structure</h2>
|
||||
<p>As shown after you <a href="/docs/en/1.0.14/installation">installed Docusaurus</a>, the initialization script created a directory structure similar to:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs-examples-from-docusaurus
|
||||
│ └── doc1.md
|
||||
│ └── doc2.md
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@
|
|||
</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/facebook/docusaurus/edit/master/docs/getting-started-preparation.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 class="postHeaderTitle">Site Preparation</h1></header><article><div><span><p>After <a href="/docs/en/1.0.14/installation">installing Docusaurus</a>, you now have a skeleton to work from for your specific website. The following discusses the rest of the Docusaurus structure in order for you to prepare your site.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="directory-structure"></a><a href="#directory-structure" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Directory Structure</h2>
|
||||
<p>As shown after you <a href="/docs/en/1.0.14/installation">installed Docusaurus</a>, the initialization script created a directory structure similar to:</p>
|
||||
<pre><code class="hljs css languages- bash">root-of-repo
|
||||
<pre><code class="hljs css languages-bash">root-of-repo
|
||||
├── docs-examples-from-docusaurus
|
||||
│ └── doc1.md
|
||||
│ └── doc2.md
|
||||
|
|
|
|||
|
|
@ -76,7 +76,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<p>Pages allow you to customize layout and specific content of pages like a custom index page or help page.</p>
|
||||
<p>Pages with text that you want translated should be placed in <code>website/pages/en</code> folder.</p>
|
||||
<p>Wrap strings you want translated in a <code><translate></code> tag, and add the following <code>require</code> statement to the top of the file:</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token operator">...</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token operator">...</span>
|
||||
<span class="token keyword">const</span> translate <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">"../../server/translate.js"</span><span class="token punctuation">)</span><span class="token punctuation">.</span>translate<span class="token punctuation">;</span>
|
||||
<span class="token operator">...</span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>h2</span><span class="token punctuation">></span></span>
|
||||
|
|
@ -85,7 +85,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<span class="token operator">...</span>
|
||||
</code></pre>
|
||||
<p>You can also include an optional description attribute to give more context to a translator about how to translate the string:</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span> <span class="token attr-name">desc</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>flower, not verb<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Rose<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
</code></pre>
|
||||
|
|
@ -95,7 +95,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<h2><a class="anchor" aria-hidden="true" id="gathering-strings-to-translate"></a><a href="#gathering-strings-to-translate" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Gathering Strings to Translate</h2>
|
||||
<p>The strings within localized Pages must be extracted and provided to Crowdin.</p>
|
||||
<p>Add the following script to your <code>website/package.json</code> file, if it does not exist already:</p>
|
||||
<pre><code class="hljs css languages- json">...
|
||||
<pre><code class="hljs css languages-json">...
|
||||
"scripts": {
|
||||
"write-translations": "docusaurus-write-translations"
|
||||
},
|
||||
|
|
@ -133,7 +133,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
</blockquote>
|
||||
<p>The example below can be automatically generated by the Docusaurus cli with the <code>examples</code> script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.</p>
|
||||
<p>Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.</p>
|
||||
<pre><code class="hljs css languages- yaml"><span class="hljs-attr">project_identifier_env:</span> <span class="hljs-string">CROWDIN_DOCUSAURUS_PROJECT_ID</span>
|
||||
<pre><code class="hljs css languages-yaml"><span class="hljs-attr">project_identifier_env:</span> <span class="hljs-string">CROWDIN_DOCUSAURUS_PROJECT_ID</span>
|
||||
<span class="hljs-attr">api_key_env:</span> <span class="hljs-string">CROWDIN_DOCUSAURUS_API_KEY</span>
|
||||
<span class="hljs-attr">base_path:</span> <span class="hljs-string">"./"</span>
|
||||
<span class="hljs-attr">preserve_hierarchy:</span> <span class="hljs-literal">true</span>
|
||||
|
|
@ -158,7 +158,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<h3><a class="anchor" aria-hidden="true" id="setup-the-crowdin-scripts"></a><a href="#setup-the-crowdin-scripts" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Setup the Crowdin Scripts</h3>
|
||||
<p>You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in <code>/docs</code> as well as translatable strings in <code>website/i18n/en.json</code>. (These strings can be generated by running <code>yarn write-translations</code>.)</p>
|
||||
<p>You can add the following to your <code>package.json</code> to manually trigger Crowdin.</p>
|
||||
<pre><code class="hljs css languages- json">"scripts": {
|
||||
<pre><code class="hljs css languages-json">"scripts": {
|
||||
"crowdin-upload": "crowdin --config ../crowdin.yaml upload sources --auto-update -b master",
|
||||
"crowdin-download": "crowdin --config ../crowdin.yaml download -b master"
|
||||
},
|
||||
|
|
@ -183,7 +183,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<h3><a class="anchor" aria-hidden="true" id="automated-file-sync-using-circleci"></a><a href="#automated-file-sync-using-circleci" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Automated File Sync Using CircleCI</h3>
|
||||
<p>You can automate pulling down and uploading translations for your files using the <a href="https://circleci.com">CircleCI</a> web continuous integration service.</p>
|
||||
<p>First, update the <code>circle.yml</code> file in your project directory to include steps to upload English files to be translated and download translated files using the Crowdin CLI. Here is an example <code>circle.yml</code> file:</p>
|
||||
<pre><code class="hljs css languages- yaml"><span class="hljs-attr">machine:</span>
|
||||
<pre><code class="hljs css languages-yaml"><span class="hljs-attr">machine:</span>
|
||||
<span class="hljs-attr"> node:</span>
|
||||
<span class="hljs-attr"> version:</span> <span class="hljs-number">6.10</span><span class="hljs-number">.3</span>
|
||||
<span class="hljs-attr"> npm:</span>
|
||||
|
|
@ -219,7 +219,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<p>If you wish to use Crowdin on your machine locally, you can install the <a href="https://support.crowdin.com/cli-tool/">Crowdin CLI tool</a> and run the same commands found in the <code>circle.yaml</code> file. The only difference is that you must set <code>project_identifier</code> and <code>api_key</code> values in the <code>crowdin.yaml</code> file since you will not have Circle environment variables set up.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="versioned-translations"></a><a href="#versioned-translations" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Versioned Translations</h2>
|
||||
<p>If you wish to have translation and versioning for your documentation, add the following section to the end of your <code>crowdin.yaml</code> file:</p>
|
||||
<pre><code class="hljs css languages- yaml"><span class="hljs-bullet"> -</span>
|
||||
<pre><code class="hljs css languages-yaml"><span class="hljs-bullet"> -</span>
|
||||
<span class="hljs-attr"> source:</span> <span class="hljs-string">'/website/versioned_docs/**/*.md'</span>
|
||||
<span class="hljs-attr"> translation:</span> <span class="hljs-string">'/website/translated_docs/%locale%/**/%original_file_name%'</span>
|
||||
<span class="hljs-attr"> languages_mapping:</span> <span class="hljs-meta">*anchor</span>
|
||||
|
|
|
|||
|
|
@ -76,7 +76,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<p>Pages allow you to customize layout and specific content of pages like a custom index page or help page.</p>
|
||||
<p>Pages with text that you want translated should be placed in <code>website/pages/en</code> folder.</p>
|
||||
<p>Wrap strings you want translated in a <code><translate></code> tag, and add the following <code>require</code> statement to the top of the file:</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token operator">...</span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token operator">...</span>
|
||||
<span class="token keyword">const</span> translate <span class="token operator">=</span> <span class="token function">require</span><span class="token punctuation">(</span><span class="token string">"../../server/translate.js"</span><span class="token punctuation">)</span><span class="token punctuation">.</span>translate<span class="token punctuation">;</span>
|
||||
<span class="token operator">...</span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>h2</span><span class="token punctuation">></span></span>
|
||||
|
|
@ -85,7 +85,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<span class="token operator">...</span>
|
||||
</code></pre>
|
||||
<p>You can also include an optional description attribute to give more context to a translator about how to translate the string:</p>
|
||||
<pre><code class="hljs css languages- jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<pre><code class="hljs css languages-jsx"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>translate</span> <span class="token attr-name">desc</span><span class="token attr-value"><span class="token punctuation">=</span><span class="token punctuation">"</span>flower, not verb<span class="token punctuation">"</span></span><span class="token punctuation">></span></span>Rose<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>translate</span><span class="token punctuation">></span></span>
|
||||
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span>p</span><span class="token punctuation">></span></span>
|
||||
</code></pre>
|
||||
|
|
@ -95,7 +95,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<h2><a class="anchor" aria-hidden="true" id="gathering-strings-to-translate"></a><a href="#gathering-strings-to-translate" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Gathering Strings to Translate</h2>
|
||||
<p>The strings within localized Pages must be extracted and provided to Crowdin.</p>
|
||||
<p>Add the following script to your <code>website/package.json</code> file, if it does not exist already:</p>
|
||||
<pre><code class="hljs css languages- json">...
|
||||
<pre><code class="hljs css languages-json">...
|
||||
"scripts": {
|
||||
"write-translations": "docusaurus-write-translations"
|
||||
},
|
||||
|
|
@ -133,7 +133,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
</blockquote>
|
||||
<p>The example below can be automatically generated by the Docusaurus cli with the <code>examples</code> script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.</p>
|
||||
<p>Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.</p>
|
||||
<pre><code class="hljs css languages- yaml"><span class="hljs-attr">project_identifier_env:</span> <span class="hljs-string">CROWDIN_DOCUSAURUS_PROJECT_ID</span>
|
||||
<pre><code class="hljs css languages-yaml"><span class="hljs-attr">project_identifier_env:</span> <span class="hljs-string">CROWDIN_DOCUSAURUS_PROJECT_ID</span>
|
||||
<span class="hljs-attr">api_key_env:</span> <span class="hljs-string">CROWDIN_DOCUSAURUS_API_KEY</span>
|
||||
<span class="hljs-attr">base_path:</span> <span class="hljs-string">"./"</span>
|
||||
<span class="hljs-attr">preserve_hierarchy:</span> <span class="hljs-literal">true</span>
|
||||
|
|
@ -158,7 +158,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<h3><a class="anchor" aria-hidden="true" id="setup-the-crowdin-scripts"></a><a href="#setup-the-crowdin-scripts" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Setup the Crowdin Scripts</h3>
|
||||
<p>You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in <code>/docs</code> as well as translatable strings in <code>website/i18n/en.json</code>. (These strings can be generated by running <code>yarn write-translations</code>.)</p>
|
||||
<p>You can add the following to your <code>package.json</code> to manually trigger Crowdin.</p>
|
||||
<pre><code class="hljs css languages- json">"scripts": {
|
||||
<pre><code class="hljs css languages-json">"scripts": {
|
||||
"crowdin-upload": "crowdin --config ../crowdin.yaml upload sources --auto-update -b master",
|
||||
"crowdin-download": "crowdin --config ../crowdin.yaml download -b master"
|
||||
},
|
||||
|
|
@ -183,7 +183,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<h3><a class="anchor" aria-hidden="true" id="automated-file-sync-using-circleci"></a><a href="#automated-file-sync-using-circleci" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Automated File Sync Using CircleCI</h3>
|
||||
<p>You can automate pulling down and uploading translations for your files using the <a href="https://circleci.com">CircleCI</a> web continuous integration service.</p>
|
||||
<p>First, update the <code>circle.yml</code> file in your project directory to include steps to upload English files to be translated and download translated files using the Crowdin CLI. Here is an example <code>circle.yml</code> file:</p>
|
||||
<pre><code class="hljs css languages- yaml"><span class="hljs-attr">machine:</span>
|
||||
<pre><code class="hljs css languages-yaml"><span class="hljs-attr">machine:</span>
|
||||
<span class="hljs-attr"> node:</span>
|
||||
<span class="hljs-attr"> version:</span> <span class="hljs-number">6.10</span><span class="hljs-number">.3</span>
|
||||
<span class="hljs-attr"> npm:</span>
|
||||
|
|
@ -219,7 +219,7 @@ languages<span class="hljs-selector-class">.js</span>
|
|||
<p>If you wish to use Crowdin on your machine locally, you can install the <a href="https://support.crowdin.com/cli-tool/">Crowdin CLI tool</a> and run the same commands found in the <code>circle.yaml</code> file. The only difference is that you must set <code>project_identifier</code> and <code>api_key</code> values in the <code>crowdin.yaml</code> file since you will not have Circle environment variables set up.</p>
|
||||
<h2><a class="anchor" aria-hidden="true" id="versioned-translations"></a><a href="#versioned-translations" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Versioned Translations</h2>
|
||||
<p>If you wish to have translation and versioning for your documentation, add the following section to the end of your <code>crowdin.yaml</code> file:</p>
|
||||
<pre><code class="hljs css languages- yaml"><span class="hljs-bullet"> -</span>
|
||||
<pre><code class="hljs css languages-yaml"><span class="hljs-bullet"> -</span>
|
||||
<span class="hljs-attr"> source:</span> <span class="hljs-string">'/website/versioned_docs/**/*.md'</span>
|
||||
<span class="hljs-attr"> translation:</span> <span class="hljs-string">'/website/translated_docs/%locale%/**/%original_file_name%'</span>
|
||||
<span class="hljs-attr"> languages_mapping:</span> <span class="hljs-meta">*anchor</span>
|
||||
|
|
|
|||
|
|
@ -50,19 +50,19 @@
|
|||
</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/facebook/docusaurus/edit/master/docs/guides-versioning.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 class="postHeaderTitle">Versioning</h1></header><article><div><span><p>You 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" aria-hidden="true" id="how-to-create-new-versions"></a><a href="#how-to-create-new-versions" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>How to Create New Versions</h2>
|
||||
<p>Run the following script to generate a starter versions page listing all the site versions:</p>
|
||||
<pre><code class="hljs css languages- bash">yarn examples versions
|
||||
<pre><code class="hljs css languages-bash">yarn examples versions
|
||||
</code></pre>
|
||||
<p>This creates the <code>pages/en/versions.js</code> file.</p>
|
||||
<p>You can edit this file later on to customize how you display the versions.</p>
|
||||
<p>Add the following script to your <code>package.json</code> file if it doesn't already exist:</p>
|
||||
<pre><code class="hljs css languages- json">...
|
||||
<pre><code class="hljs css languages-json">...
|
||||
"scripts": {
|
||||
"version": "docusaurus-version"
|
||||
},
|
||||
...
|
||||
</code></pre>
|
||||
<p>Run the script with a command line argument of the version you wish to create. e.g.,</p>
|
||||
<pre><code class="hljs css languages- bash">yarn run version 1.0.0
|
||||
<pre><code class="hljs css languages-bash">yarn run version 1.0.0
|
||||
</code></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 <code>1.0.0</code> as the version number, version <code>1.0.0</code> is considered the latest release version for your project. The site will display the version number next to the title in the header. This version number links to a versions page that you created earlier.</p>
|
||||
|
|
@ -93,14 +93,14 @@
|
|||
<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" aria-hidden="true" id="renaming-existing-versions"></a><a href="#renaming-existing-versions" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Renaming Existing Versions</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><code class="hljs css languages- json">...
|
||||
<pre><code class="hljs css languages-json">...
|
||||
"scripts": {
|
||||
"rename-version": "docusaurus-rename-version"
|
||||
},
|
||||
...
|
||||
</code></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><code class="hljs css languages- bash">yarn run rename-version 1.0.0 1.0.1
|
||||
<pre><code class="hljs css languages-bash">yarn run rename-version 1.0.0 1.0.1
|
||||
</code></pre>
|
||||
<h2><a class="anchor" aria-hidden="true" id="versioning-and-translations"></a><a href="#versioning-and-translations" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Versioning and Translations</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="/docs/en/1.0.14/translation">translations guide</a>.</p>
|
||||
|
|
|
|||
|
|
@ -50,19 +50,19 @@
|
|||
</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/facebook/docusaurus/edit/master/docs/guides-versioning.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 class="postHeaderTitle">Versioning</h1></header><article><div><span><p>You 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" aria-hidden="true" id="how-to-create-new-versions"></a><a href="#how-to-create-new-versions" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>How to Create New Versions</h2>
|
||||
<p>Run the following script to generate a starter versions page listing all the site versions:</p>
|
||||
<pre><code class="hljs css languages- bash">yarn examples versions
|
||||
<pre><code class="hljs css languages-bash">yarn examples versions
|
||||
</code></pre>
|
||||
<p>This creates the <code>pages/en/versions.js</code> file.</p>
|
||||
<p>You can edit this file later on to customize how you display the versions.</p>
|
||||
<p>Add the following script to your <code>package.json</code> file if it doesn't already exist:</p>
|
||||
<pre><code class="hljs css languages- json">...
|
||||
<pre><code class="hljs css languages-json">...
|
||||
"scripts": {
|
||||
"version": "docusaurus-version"
|
||||
},
|
||||
...
|
||||
</code></pre>
|
||||
<p>Run the script with a command line argument of the version you wish to create. e.g.,</p>
|
||||
<pre><code class="hljs css languages- bash">yarn run version 1.0.0
|
||||
<pre><code class="hljs css languages-bash">yarn run version 1.0.0
|
||||
</code></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 <code>1.0.0</code> as the version number, version <code>1.0.0</code> is considered the latest release version for your project. The site will display the version number next to the title in the header. This version number links to a versions page that you created earlier.</p>
|
||||
|
|
@ -93,14 +93,14 @@
|
|||
<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" aria-hidden="true" id="renaming-existing-versions"></a><a href="#renaming-existing-versions" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Renaming Existing Versions</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><code class="hljs css languages- json">...
|
||||
<pre><code class="hljs css languages-json">...
|
||||
"scripts": {
|
||||
"rename-version": "docusaurus-rename-version"
|
||||
},
|
||||
...
|
||||
</code></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><code class="hljs css languages- bash">yarn run rename-version 1.0.0 1.0.1
|
||||
<pre><code class="hljs css languages-bash">yarn run rename-version 1.0.0 1.0.1
|
||||
</code></pre>
|
||||
<h2><a class="anchor" aria-hidden="true" id="versioning-and-translations"></a><a href="#versioning-and-translations" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Versioning and Translations</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="/docs/en/1.0.14/translation">translations guide</a>.</p>
|
||||
|
|
|
|||
Some files were not shown because too many files have changed in this diff Show more
Loading…
Add table
Add a link
Reference in a new issue