diff --git a/blog/2017/12/14/introducing-docusaurus.html b/blog/2017/12/14/introducing-docusaurus.html index 7388c10369..56a2aaf9b0 100644 --- a/blog/2017/12/14/introducing-docusaurus.html +++ b/blog/2017/12/14/introducing-docusaurus.html @@ -71,7 +71,7 @@

Slash Up and Running

At its core, we wanted sites running Docusaurus to be simple to use. With one installation command and some simple configuration, you can actually have a default running website.

When you run docusaurus-init, you will see a structure similar to:

-
root-of-repo
+
root-of-repo
 ├── docs-examples-from-docusaurus
 │   ├── doc1.md
 │   ├── doc2.md
@@ -94,7 +94,7 @@
 

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 blog posts; siteConfig.js is where you make most of the customizations for your site; sidebars.json is where you maintain the layout and content of the sidebar for your documentation; the pages folder is where you add custom pages for your site; the static folder is where all of your static assets go (e.g., CSS stylesheets and images); and the core folder is where you can customize core components of the site, in this case the footer.

How does Docusaurus work?

Docusaurus is written primarily in JavaScript and React, replacing Jekyll which we used in the old template. We use Remarkable for our markdown rendering and highlight.js for our code block syntax highlighting. The core of Docusaurus' functionality is in the lib directory of the Docusaurus repo. The general structure looks like:

-
root-of-Docusaurus
+
root-of-Docusaurus
 ├── lib
 │   ├── core
 │   ├── server
@@ -127,7 +127,7 @@
 
 

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.

The final structure of your compiled site will look similar to:

-
build
+
build
 ├── website
 │   ├── CNAME
 │   ├── blog
diff --git a/blog/2017/12/14/introducing-docusaurus/index.html b/blog/2017/12/14/introducing-docusaurus/index.html
index 7388c10369..56a2aaf9b0 100644
--- a/blog/2017/12/14/introducing-docusaurus/index.html
+++ b/blog/2017/12/14/introducing-docusaurus/index.html
@@ -71,7 +71,7 @@
 

Slash Up and Running

At its core, we wanted sites running Docusaurus to be simple to use. With one installation command and some simple configuration, you can actually have a default running website.

When you run docusaurus-init, you will see a structure similar to:

-
root-of-repo
+
root-of-repo
 ├── docs-examples-from-docusaurus
 │   ├── doc1.md
 │   ├── doc2.md
@@ -94,7 +94,7 @@
 

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 blog posts; siteConfig.js is where you make most of the customizations for your site; sidebars.json is where you maintain the layout and content of the sidebar for your documentation; the pages folder is where you add custom pages for your site; the static folder is where all of your static assets go (e.g., CSS stylesheets and images); and the core folder is where you can customize core components of the site, in this case the footer.

How does Docusaurus work?

Docusaurus is written primarily in JavaScript and React, replacing Jekyll which we used in the old template. We use Remarkable for our markdown rendering and highlight.js for our code block syntax highlighting. The core of Docusaurus' functionality is in the lib directory of the Docusaurus repo. The general structure looks like:

-
root-of-Docusaurus
+
root-of-Docusaurus
 ├── lib
 │   ├── core
 │   ├── server
@@ -127,7 +127,7 @@
 
 

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.

The final structure of your compiled site will look similar to:

-
build
+
build
 ├── website
 │   ├── CNAME
 │   ├── blog
diff --git a/docs/en/1.0.11/api-pages.html b/docs/en/1.0.11/api-pages.html
index c09d69fd91..5526b5446b 100644
--- a/docs/en/1.0.11/api-pages.html
+++ b/docs/en/1.0.11/api-pages.html
@@ -59,7 +59,7 @@
 

CompLibrary.MarkdownBlock

A React component that parses markdown and renders to HTML.

Example:

-
const MarkdownBlock = CompLibrary.MarkdownBlock;
+
const MarkdownBlock = CompLibrary.MarkdownBlock;
 
 <MarkdownBlock>[Markdown syntax for a link](http://www.example.com)</MarkdownBlock>
 
@@ -77,7 +77,7 @@

Example

-
<Container
+
<Container
   padding={['bottom', 'top']}
   background="light"
   className="myCustomClass">
@@ -142,15 +142,15 @@
 

Translating Strings

When translations are enabled, any pages inside website/pages/en will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the languages.js file. E.g. The url for a French page of website/pages/en/help.js would be found at ${baseUrl}fr/help.html.

When writing pages that you wish to translate, wrap any strings to be translated inside a <translate> tag. e.g.,

-
<p><translate>I like translations</translate></p>
+
<p><translate>I like translations</translate></p>
 

You can also provide an optional description attribute to provide context for translators. e.g,

-
<a href="/community">
+
<a href="/community">
   <translate desc="Footer link to page referring to community GitHub and Slack">Community</translate>
 </a>
 

Add the following require statement as well:

-
const translate = require("../../server/translate.js").translate;
+
const translate = require("../../server/translate.js").translate;
 

Note that this path is valid for files inside pages/en and should be adjusted accordingly if files are in different locations, as discussed above.

Using Static Assets

diff --git a/docs/en/1.0.11/api-pages/index.html b/docs/en/1.0.11/api-pages/index.html index c09d69fd91..5526b5446b 100644 --- a/docs/en/1.0.11/api-pages/index.html +++ b/docs/en/1.0.11/api-pages/index.html @@ -59,7 +59,7 @@

CompLibrary.MarkdownBlock

A React component that parses markdown and renders to HTML.

Example:

-
const MarkdownBlock = CompLibrary.MarkdownBlock;
+
const MarkdownBlock = CompLibrary.MarkdownBlock;
 
 <MarkdownBlock>[Markdown syntax for a link](http://www.example.com)</MarkdownBlock>
 
@@ -77,7 +77,7 @@

Example

-
<Container
+
<Container
   padding={['bottom', 'top']}
   background="light"
   className="myCustomClass">
@@ -142,15 +142,15 @@
 

Translating Strings

When translations are enabled, any pages inside website/pages/en will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the languages.js file. E.g. The url for a French page of website/pages/en/help.js would be found at ${baseUrl}fr/help.html.

When writing pages that you wish to translate, wrap any strings to be translated inside a <translate> tag. e.g.,

-
<p><translate>I like translations</translate></p>
+
<p><translate>I like translations</translate></p>
 

You can also provide an optional description attribute to provide context for translators. e.g,

-
<a href="/community">
+
<a href="/community">
   <translate desc="Footer link to page referring to community GitHub and Slack">Community</translate>
 </a>
 

Add the following require statement as well:

-
const translate = require("../../server/translate.js").translate;
+
const translate = require("../../server/translate.js").translate;
 

Note that this path is valid for files inside pages/en and should be adjusted accordingly if files are in different locations, as discussed above.

Using Static Assets

diff --git a/docs/en/1.0.11/commands.html b/docs/en/1.0.11/commands.html index 3f19b6223a..05ab98084e 100644 --- a/docs/en/1.0.11/commands.html +++ b/docs/en/1.0.11/commands.html @@ -100,7 +100,7 @@
  • USE_SSH: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.
  • e.g.,

    -
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
    +
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
     

    The following environment variables are set by CircleCI during the build process.

      diff --git a/docs/en/1.0.11/commands/index.html b/docs/en/1.0.11/commands/index.html index 3f19b6223a..05ab98084e 100644 --- a/docs/en/1.0.11/commands/index.html +++ b/docs/en/1.0.11/commands/index.html @@ -100,7 +100,7 @@
    • USE_SSH: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.

    e.g.,

    -
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
    +
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
     

    The following environment variables are set by CircleCI during the build process.

      diff --git a/docs/en/1.0.11/custom-pages.html b/docs/en/1.0.11/custom-pages.html index 6c23dbf0e2..42fa7690d9 100644 --- a/docs/en/1.0.11/custom-pages.html +++ b/docs/en/1.0.11/custom-pages.html @@ -53,7 +53,7 @@

      You can start your local server and go to http://localhost:3000 to see what the example home page looks like. From there, edit the website/pages/en/index.js file and its various components to use the images and text you want for your project.

      Adding Other Custom Pages

      Docusaurus provides some simple example pages in the website/pages/en directory, including index.js, users.js, and help.js. These are good examples to showcase how to create a custom page for Docusaurus.

      -
      root-of-repo
      +
      root-of-repo
       ├── docs
       └── website
       │   └── blog
      @@ -85,7 +85,7 @@
       

      Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.

      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.

      If you do not want a footer for your site, change the render function of core/Footer.js to return null. e.g.,

      -
      const React = require("react");
      +
      const React = require("react");
       
       class Footer extends React.Component {
         render() {
      diff --git a/docs/en/1.0.11/custom-pages/index.html b/docs/en/1.0.11/custom-pages/index.html
      index 6c23dbf0e2..42fa7690d9 100644
      --- a/docs/en/1.0.11/custom-pages/index.html
      +++ b/docs/en/1.0.11/custom-pages/index.html
      @@ -53,7 +53,7 @@
       

      You can start your local server and go to http://localhost:3000 to see what the example home page looks like. From there, edit the website/pages/en/index.js file and its various components to use the images and text you want for your project.

      Adding Other Custom Pages

      Docusaurus provides some simple example pages in the website/pages/en directory, including index.js, users.js, and help.js. These are good examples to showcase how to create a custom page for Docusaurus.

      -
      root-of-repo
      +
      root-of-repo
       ├── docs
       └── website
       │   └── blog
      @@ -85,7 +85,7 @@
       

      Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.

      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.

      If you do not want a footer for your site, change the render function of core/Footer.js to return null. e.g.,

      -
      const React = require("react");
      +
      const React = require("react");
       
       class Footer extends React.Component {
         render() {
      diff --git a/docs/en/1.0.11/doc-markdown.html b/docs/en/1.0.11/doc-markdown.html
      index fd6277d8d1..5c50812999 100644
      --- a/docs/en/1.0.11/doc-markdown.html
      +++ b/docs/en/1.0.11/doc-markdown.html
      @@ -55,7 +55,7 @@
       

      hide_title: Whether to hide the title at the top of the doc.

      sidebar_label: The text shown in the document sidebar for this document. If this field is not present, the document's sidebar_label will default to its title.

      For example:

      -
      ---
      +
      ---
       id: doc1
       title: My Document
       sidebar_label: Document
      @@ -63,7 +63,7 @@ title: My Document
       

      Versioned documents have their ids altered to include the version number when they get copied. The new id is version-${version}-${id} where ${version} is the version number of that document and ${id} is the original id. Additionally, versioned documents get an added original_id field with the original document id.

      For example:

      -
      ---
      +
      ---
       id: version-1.0.0-doc1
       title: My Document
       sidebar_label: Document
      @@ -72,7 +72,7 @@ sidebar_label: Document
       

      custom_edit_url: The url for editing this document. If this field is not present, the document's edit url will fallback to editUrl from optional fields of siteConfig.js. See siteConfig.js docs for more information.

      For example:

      -
      ---
      +
      ---
       id: doc-markdown
       title: Markdown Features
       custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
      @@ -85,7 +85,7 @@ title: Markdown Features
       

      authorURL: 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.

      authorFBID: 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.

      For example:

      -
      ---
      +
      ---
       title: My First Blog Post
       author: Frank Li
       authorURL: http://twitter.com/franchementli
      @@ -97,20 +97,20 @@ authorURL: http://twitter.com/franchementli
       

      Linking other Documents

      You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.

      Example:

      -
      [This links to another document](other-document.md)
      +
      [This links to another document](other-document.md)
       

      This markdown will automatically get converted into a link to /docs/other-document.html (or the appropriately translated/versioned link) once it gets rendered.

      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.

      Linking to Images and Other Assets

      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 docs/assets and website/blog/assets, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.

      Example:

      -
      ![alt-text](/docs/assets/doc-image.png)
      +
      ![alt-text](/docs/assets/doc-image.png)
       

      Generating Table of Contents

      You can make an autogenerated list of links, which can be useful as a table of contents for API docs.

      In your markdown file, insert a line with the text <AUTOGENERATED_TABLE_OF_CONTENTS>. Write your documentation using h3 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 <AUTOGENERATED_TABLE_OF_CONTENTS>.

      Example:

      -
      ### `docusaurus.function(a, b)`
      +
      ### `docusaurus.function(a, b)`
       
       Text describing my function
       
      @@ -120,7 +120,7 @@ Text describing my function
       Text describing my function
       

      will lead to a table of contents of the functions:

      -
      - `docusaurus.function(a, b)`
      +
      - `docusaurus.function(a, b)`
       - `docdoc(file)`
       

      and each function will link to their corresponding sections in the page.

      @@ -134,20 +134,20 @@ ReactDOM.render( ```

      ...would be rendered with syntax highlighting like so:

      -
      ReactDOM.render(
      +
      ReactDOM.render(
         <h1>Hello, world!</h1>,
         document.getElementById('root')
       );
       

      Highlighting is provided by Highlight.js using the theme specified in your siteConfig.js file as part of the highlight key:

      -
      highlight: {
      +
      highlight: {
         theme: 'default'
       }
       

      You can find the full list of supported themes in the Highlight.js styles directory.

      Registering additional languages

      While Highlight.js provides support for many popular languages out of the box, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the hljs constant as part of the highlight config key. This in turn allows you to call registerLanguage:

      -
      highlight: {
      +
      highlight: {
         theme: 'default',
         hljs: function(hljs) {
           hljs.registerLanguage('galacticbasic', function(hljs) {
      diff --git a/docs/en/1.0.11/doc-markdown/index.html b/docs/en/1.0.11/doc-markdown/index.html
      index fd6277d8d1..5c50812999 100644
      --- a/docs/en/1.0.11/doc-markdown/index.html
      +++ b/docs/en/1.0.11/doc-markdown/index.html
      @@ -55,7 +55,7 @@
       

      hide_title: Whether to hide the title at the top of the doc.

      sidebar_label: The text shown in the document sidebar for this document. If this field is not present, the document's sidebar_label will default to its title.

      For example:

      -
      ---
      +
      ---
       id: doc1
       title: My Document
       sidebar_label: Document
      @@ -63,7 +63,7 @@ title: My Document
       

      Versioned documents have their ids altered to include the version number when they get copied. The new id is version-${version}-${id} where ${version} is the version number of that document and ${id} is the original id. Additionally, versioned documents get an added original_id field with the original document id.

      For example:

      -
      ---
      +
      ---
       id: version-1.0.0-doc1
       title: My Document
       sidebar_label: Document
      @@ -72,7 +72,7 @@ sidebar_label: Document
       

      custom_edit_url: The url for editing this document. If this field is not present, the document's edit url will fallback to editUrl from optional fields of siteConfig.js. See siteConfig.js docs for more information.

      For example:

      -
      ---
      +
      ---
       id: doc-markdown
       title: Markdown Features
       custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
      @@ -85,7 +85,7 @@ title: Markdown Features
       

      authorURL: 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.

      authorFBID: 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.

      For example:

      -
      ---
      +
      ---
       title: My First Blog Post
       author: Frank Li
       authorURL: http://twitter.com/franchementli
      @@ -97,20 +97,20 @@ authorURL: http://twitter.com/franchementli
       

      Linking other Documents

      You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.

      Example:

      -
      [This links to another document](other-document.md)
      +
      [This links to another document](other-document.md)
       

      This markdown will automatically get converted into a link to /docs/other-document.html (or the appropriately translated/versioned link) once it gets rendered.

      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.

      Linking to Images and Other Assets

      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 docs/assets and website/blog/assets, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.

      Example:

      -
      ![alt-text](/docs/assets/doc-image.png)
      +
      ![alt-text](/docs/assets/doc-image.png)
       

      Generating Table of Contents

      You can make an autogenerated list of links, which can be useful as a table of contents for API docs.

      In your markdown file, insert a line with the text <AUTOGENERATED_TABLE_OF_CONTENTS>. Write your documentation using h3 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 <AUTOGENERATED_TABLE_OF_CONTENTS>.

      Example:

      -
      ### `docusaurus.function(a, b)`
      +
      ### `docusaurus.function(a, b)`
       
       Text describing my function
       
      @@ -120,7 +120,7 @@ Text describing my function
       Text describing my function
       

      will lead to a table of contents of the functions:

      -
      - `docusaurus.function(a, b)`
      +
      - `docusaurus.function(a, b)`
       - `docdoc(file)`
       

      and each function will link to their corresponding sections in the page.

      @@ -134,20 +134,20 @@ ReactDOM.render( ```

      ...would be rendered with syntax highlighting like so:

      -
      ReactDOM.render(
      +
      ReactDOM.render(
         <h1>Hello, world!</h1>,
         document.getElementById('root')
       );
       

      Highlighting is provided by Highlight.js using the theme specified in your siteConfig.js file as part of the highlight key:

      -
      highlight: {
      +
      highlight: {
         theme: 'default'
       }
       

      You can find the full list of supported themes in the Highlight.js styles directory.

      Registering additional languages

      While Highlight.js provides support for many popular languages out of the box, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the hljs constant as part of the highlight config key. This in turn allows you to call registerLanguage:

      -
      highlight: {
      +
      highlight: {
         theme: 'default',
         hljs: function(hljs) {
           hljs.registerLanguage('galacticbasic', function(hljs) {
      diff --git a/docs/en/1.0.11/installation.html b/docs/en/1.0.11/installation.html
      index 7b0a495920..d2e69cbec3 100644
      --- a/docs/en/1.0.11/installation.html
      +++ b/docs/en/1.0.11/installation.html
      @@ -61,7 +61,7 @@
       

      After docusaurus is installed, moving forward, you can check your current version of Docusaurus by going into the website directory and typing npm list docusaurus. You can update to the latest version of Docusaurus by typing npm update.

      Along with previously existing files and directories, your root directory will now contain a structure similar to:

      -
      root-of-repo
      +
      root-of-repo
       ├── docs-examples-from-docusaurus
       │   └── doc1.md
       │   └── doc2.md
      diff --git a/docs/en/1.0.11/installation/index.html b/docs/en/1.0.11/installation/index.html
      index 7b0a495920..d2e69cbec3 100644
      --- a/docs/en/1.0.11/installation/index.html
      +++ b/docs/en/1.0.11/installation/index.html
      @@ -61,7 +61,7 @@
       

      After docusaurus is installed, moving forward, you can check your current version of Docusaurus by going into the website directory and typing npm list docusaurus. You can update to the latest version of Docusaurus by typing npm update.

      Along with previously existing files and directories, your root directory will now contain a structure similar to:

      -
      root-of-repo
      +
      root-of-repo
       ├── docs-examples-from-docusaurus
       │   └── doc1.md
       │   └── doc2.md
      diff --git a/docs/en/1.0.11/publishing.html b/docs/en/1.0.11/publishing.html
      index 808ac72982..d694c6a6fc 100644
      --- a/docs/en/1.0.11/publishing.html
      +++ b/docs/en/1.0.11/publishing.html
      @@ -87,7 +87,7 @@
       

    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:

    To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate.

    -
    GIT_USER=<GIT_USER> \
    +
    GIT_USER=<GIT_USER> \
       CURRENT_BRANCH=master \
       USE_SSH=true \
       yarn run publish-gh-pages # or `npm run publish-gh-pages`
    @@ -111,7 +111,7 @@
     
  • Create a .circleci folder and create a config.yml under that folder.
  • Copy the text below into .circleci/config.yml.
  • -
    # If you only one circle to run on direct commits to master, you can uncomment this out
    +
    # If you only one circle to run on direct commits to master, you can uncomment this out
     # and uncomment the filters: *filter-only-master down below too
     #
     # aliases:
    @@ -158,7 +158,7 @@
     
     

    Tips & Tricks

    When initially deploying to a gh-pages branch using Circle CI, you may notice that some jobs triggered by commits to the gh-pages 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:

    -
    # Circle CI 2.0 Config File
    +
    # Circle CI 2.0 Config File
     # This config file will prevent tests from being run on the gh-pages branch.
     version: 2
     jobs:
    diff --git a/docs/en/1.0.11/publishing/index.html b/docs/en/1.0.11/publishing/index.html
    index 808ac72982..d694c6a6fc 100644
    --- a/docs/en/1.0.11/publishing/index.html
    +++ b/docs/en/1.0.11/publishing/index.html
    @@ -87,7 +87,7 @@
     
     

    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:

    To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate.

    -
    GIT_USER=<GIT_USER> \
    +
    GIT_USER=<GIT_USER> \
       CURRENT_BRANCH=master \
       USE_SSH=true \
       yarn run publish-gh-pages # or `npm run publish-gh-pages`
    @@ -111,7 +111,7 @@
     
  • Create a .circleci folder and create a config.yml under that folder.
  • Copy the text below into .circleci/config.yml.
  • -
    # If you only one circle to run on direct commits to master, you can uncomment this out
    +
    # If you only one circle to run on direct commits to master, you can uncomment this out
     # and uncomment the filters: *filter-only-master down below too
     #
     # aliases:
    @@ -158,7 +158,7 @@
     
     

    Tips & Tricks

    When initially deploying to a gh-pages branch using Circle CI, you may notice that some jobs triggered by commits to the gh-pages 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:

    -
    # Circle CI 2.0 Config File
    +
    # Circle CI 2.0 Config File
     # This config file will prevent tests from being run on the gh-pages branch.
     version: 2
     jobs:
    diff --git a/docs/en/1.0.11/search.html b/docs/en/1.0.11/search.html
    index c298fb75dc..3b40509d6f 100644
    --- a/docs/en/1.0.11/search.html
    +++ b/docs/en/1.0.11/search.html
    @@ -50,7 +50,7 @@
             
    Edit

    Enabling Search

    Docusaurus supports search using Algolia DocSearch. Once you have set up your site, enter your site information to have Algolia crawl your website's documentation pages. Algolia will then send you an API key and index name for your site.

    Enabling the Search Bar

    Enter your search-only API key and index name into siteConfig.js in the algolia section to enable search for your site.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       algolia: {
         apiKey: "my-search-only-api-key-1234",
    @@ -61,7 +61,7 @@
     

    Extra Search Options

    You can also specify extra search options used by Algolia by using an algoliaOptions field in algolia. 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 found here.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       algolia: {
         ...
    @@ -75,7 +75,7 @@
     

    Controlling the Location of the Search Bar

    By default, the search bar will be the rightmost element in the top navigation bar.

    If you want to change the default location, add the searchBar flag in the headerLinks field of siteConfig.js in your desired location. For example, you may want the search bar in between your internal and external links.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       headerLinks: [
         {...}
    diff --git a/docs/en/1.0.11/search/index.html b/docs/en/1.0.11/search/index.html
    index c298fb75dc..3b40509d6f 100644
    --- a/docs/en/1.0.11/search/index.html
    +++ b/docs/en/1.0.11/search/index.html
    @@ -50,7 +50,7 @@
             
    Edit

    Enabling Search

    Docusaurus supports search using Algolia DocSearch. Once you have set up your site, enter your site information to have Algolia crawl your website's documentation pages. Algolia will then send you an API key and index name for your site.

    Enabling the Search Bar

    Enter your search-only API key and index name into siteConfig.js in the algolia section to enable search for your site.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       algolia: {
         apiKey: "my-search-only-api-key-1234",
    @@ -61,7 +61,7 @@
     

    Extra Search Options

    You can also specify extra search options used by Algolia by using an algoliaOptions field in algolia. 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 found here.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       algolia: {
         ...
    @@ -75,7 +75,7 @@
     

    Controlling the Location of the Search Bar

    By default, the search bar will be the rightmost element in the top navigation bar.

    If you want to change the default location, add the searchBar flag in the headerLinks field of siteConfig.js in your desired location. For example, you may want the search bar in between your internal and external links.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       headerLinks: [
         {...}
    diff --git a/docs/en/1.0.11/site-config.html b/docs/en/1.0.11/site-config.html
    index b15d6cb7eb..48a85d875e 100644
    --- a/docs/en/1.0.11/site-config.html
    +++ b/docs/en/1.0.11/site-config.html
    @@ -66,7 +66,7 @@
     

    headerIcon - url for icon used in header navigation bar.

    headerLinks - Links that will be used in the header navigation bar. The label field of each object will be the link text and will also be translated for each language.

    Example Usage:

    -
    headerLinks: [
    +
    headerLinks: [
       // Links to document with id doc1 for current language/version
       { doc: "doc1", label: "Getting Started" },
       // Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language
    @@ -97,9 +97,9 @@
     

    blogSidebarCount - Control the number of blog posts that show up in the sidebar. See the adding a blog docs for more information.

    cname - The CNAME for your website. It will go into a CNAME file when your site it built.

    customDocsPath - By default, Docusaurus expects your documentation to be in a directory called docs. This directory is at the same level as the website directory (i.e., not inside the website directory). You can specify a custom path to your documentation with this field. Note that all of your documentation *.md files must still reside in a flat hierarchy. You cannot have your documents in nested directories.

    -
    customDocsPath: "docs/site"
    +
    customDocsPath: "docs/site"
     
    -
    customDocsPath: "website-docs"
    +
    customDocsPath: "website-docs"
     

    disableHeaderTitle - 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 true.

    disableTitleTagline - An option to disable showing the tagline in the title of main pages. Exclude this field to keep page titles as Title • Tagline. Set to true to make page titles just Title.

    diff --git a/docs/en/1.0.11/site-config/index.html b/docs/en/1.0.11/site-config/index.html index b15d6cb7eb..48a85d875e 100644 --- a/docs/en/1.0.11/site-config/index.html +++ b/docs/en/1.0.11/site-config/index.html @@ -66,7 +66,7 @@

    headerIcon - url for icon used in header navigation bar.

    headerLinks - Links that will be used in the header navigation bar. The label field of each object will be the link text and will also be translated for each language.

    Example Usage:

    -
    headerLinks: [
    +
    headerLinks: [
       // Links to document with id doc1 for current language/version
       { doc: "doc1", label: "Getting Started" },
       // Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language
    @@ -97,9 +97,9 @@
     

    blogSidebarCount - Control the number of blog posts that show up in the sidebar. See the adding a blog docs for more information.

    cname - The CNAME for your website. It will go into a CNAME file when your site it built.

    customDocsPath - By default, Docusaurus expects your documentation to be in a directory called docs. This directory is at the same level as the website directory (i.e., not inside the website directory). You can specify a custom path to your documentation with this field. Note that all of your documentation *.md files must still reside in a flat hierarchy. You cannot have your documents in nested directories.

    -
    customDocsPath: "docs/site"
    +
    customDocsPath: "docs/site"
     
    -
    customDocsPath: "website-docs"
    +
    customDocsPath: "website-docs"
     

    disableHeaderTitle - 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 true.

    disableTitleTagline - An option to disable showing the tagline in the title of main pages. Exclude this field to keep page titles as Title • Tagline. Set to true to make page titles just Title.

    diff --git a/docs/en/1.0.11/site-creation.html b/docs/en/1.0.11/site-creation.html index bd5a15c9fc..27b21eb2da 100644 --- a/docs/en/1.0.11/site-creation.html +++ b/docs/en/1.0.11/site-creation.html @@ -51,7 +51,7 @@

    After installation and preparation, much of the work to create a basic site for your docs is already complete.

    Site Structure

    Your site structure looks like the following:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs
     └── website
     │   └── blog
    diff --git a/docs/en/1.0.11/site-creation/index.html b/docs/en/1.0.11/site-creation/index.html
    index bd5a15c9fc..27b21eb2da 100644
    --- a/docs/en/1.0.11/site-creation/index.html
    +++ b/docs/en/1.0.11/site-creation/index.html
    @@ -51,7 +51,7 @@
     

    After installation and preparation, much of the work to create a basic site for your docs is already complete.

    Site Structure

    Your site structure looks like the following:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs
     └── website
     │   └── blog
    diff --git a/docs/en/1.0.11/site-preparation.html b/docs/en/1.0.11/site-preparation.html
    index a53f26c107..1370443646 100644
    --- a/docs/en/1.0.11/site-preparation.html
    +++ b/docs/en/1.0.11/site-preparation.html
    @@ -50,7 +50,7 @@
             
    Edit

    Site Preparation

    After installing Docusaurus, 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.

    Directory Structure

    As shown after you installed Docusaurus, the initialization script created a directory structure similar to:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs-examples-from-docusaurus
     │   └── doc1.md
     │   └── doc2.md
    diff --git a/docs/en/1.0.11/site-preparation/index.html b/docs/en/1.0.11/site-preparation/index.html
    index a53f26c107..1370443646 100644
    --- a/docs/en/1.0.11/site-preparation/index.html
    +++ b/docs/en/1.0.11/site-preparation/index.html
    @@ -50,7 +50,7 @@
             
    Edit

    Site Preparation

    After installing Docusaurus, 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.

    Directory Structure

    As shown after you installed Docusaurus, the initialization script created a directory structure similar to:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs-examples-from-docusaurus
     │   └── doc1.md
     │   └── doc2.md
    diff --git a/docs/en/1.0.11/translation.html b/docs/en/1.0.11/translation.html
    index 06fb174241..169377dc56 100644
    --- a/docs/en/1.0.11/translation.html
    +++ b/docs/en/1.0.11/translation.html
    @@ -76,7 +76,7 @@ languages.js
     

    Pages allow you to customize layout and specific content of pages like a custom index page or help page.

    Pages with text that you want translated should be placed in website/pages/en folder.

    Wrap strings you want translated in a <translate> tag, and add the following require statement to the top of the file:

    -
    ...
    +
    ...
     const translate = require("../../server/translate.js").translate;
     ...
     <h2>
    @@ -85,7 +85,7 @@ languages.js
     ...
     

    You can also include an optional description attribute to give more context to a translator about how to translate the string:

    -
    <p>
    +
    <p>
       <translate desc="flower, not verb">Rose</translate>
     <p>
     
    @@ -95,7 +95,7 @@ languages.js

    Gathering Strings to Translate

    The strings within localized Pages must be extracted and provided to Crowdin.

    Add the following script to your website/package.json file, if it does not exist already:

    -
    ...
    +
    ...
     "scripts": {
       "write-translations": "docusaurus-write-translations"
     },
    @@ -133,7 +133,7 @@ languages.js
     
     

    The example below can be automatically generated by the Docusaurus cli with the examples script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.

    Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.

    -
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
    +
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
     api_key_env: CROWDIN_DOCUSAURUS_API_KEY
     base_path: "./"
     preserve_hierarchy: true
    @@ -158,7 +158,7 @@ languages.js
     

    Setup the Crowdin Scripts

    You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in /docs as well as translatable strings in website/i18n/en.json. (These strings can be generated by running yarn write-translations.)

    You can add the following to your package.json to manually trigger Crowdin.

    -
    "scripts": {
    +
    "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.js
     

    Automated File Sync Using CircleCI

    You can automate pulling down and uploading translations for your files using the CircleCI web continuous integration service.

    First, update the circle.yml 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 circle.yml file:

    -
    machine:
    +
    machine:
       node:
         version: 6.10.3
       npm:
    @@ -219,7 +219,7 @@ languages.js
     

    If you wish to use Crowdin on your machine locally, you can install the Crowdin CLI tool and run the same commands found in the circle.yaml file. The only difference is that you must set project_identifier and api_key values in the crowdin.yaml file since you will not have Circle environment variables set up.

    Versioned Translations

    If you wish to have translation and versioning for your documentation, add the following section to the end of your crowdin.yaml file:

    -
      -
    +
      -
         source: '/website/versioned_docs/**/*.md'
         translation: '/website/translated_docs/%locale%/**/%original_file_name%'
         languages_mapping: *anchor
    diff --git a/docs/en/1.0.11/translation/index.html b/docs/en/1.0.11/translation/index.html
    index 06fb174241..169377dc56 100644
    --- a/docs/en/1.0.11/translation/index.html
    +++ b/docs/en/1.0.11/translation/index.html
    @@ -76,7 +76,7 @@ languages.js
     

    Pages allow you to customize layout and specific content of pages like a custom index page or help page.

    Pages with text that you want translated should be placed in website/pages/en folder.

    Wrap strings you want translated in a <translate> tag, and add the following require statement to the top of the file:

    -
    ...
    +
    ...
     const translate = require("../../server/translate.js").translate;
     ...
     <h2>
    @@ -85,7 +85,7 @@ languages.js
     ...
     

    You can also include an optional description attribute to give more context to a translator about how to translate the string:

    -
    <p>
    +
    <p>
       <translate desc="flower, not verb">Rose</translate>
     <p>
     
    @@ -95,7 +95,7 @@ languages.js

    Gathering Strings to Translate

    The strings within localized Pages must be extracted and provided to Crowdin.

    Add the following script to your website/package.json file, if it does not exist already:

    -
    ...
    +
    ...
     "scripts": {
       "write-translations": "docusaurus-write-translations"
     },
    @@ -133,7 +133,7 @@ languages.js
     
     

    The example below can be automatically generated by the Docusaurus cli with the examples script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.

    Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.

    -
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
    +
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
     api_key_env: CROWDIN_DOCUSAURUS_API_KEY
     base_path: "./"
     preserve_hierarchy: true
    @@ -158,7 +158,7 @@ languages.js
     

    Setup the Crowdin Scripts

    You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in /docs as well as translatable strings in website/i18n/en.json. (These strings can be generated by running yarn write-translations.)

    You can add the following to your package.json to manually trigger Crowdin.

    -
    "scripts": {
    +
    "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.js
     

    Automated File Sync Using CircleCI

    You can automate pulling down and uploading translations for your files using the CircleCI web continuous integration service.

    First, update the circle.yml 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 circle.yml file:

    -
    machine:
    +
    machine:
       node:
         version: 6.10.3
       npm:
    @@ -219,7 +219,7 @@ languages.js
     

    If you wish to use Crowdin on your machine locally, you can install the Crowdin CLI tool and run the same commands found in the circle.yaml file. The only difference is that you must set project_identifier and api_key values in the crowdin.yaml file since you will not have Circle environment variables set up.

    Versioned Translations

    If you wish to have translation and versioning for your documentation, add the following section to the end of your crowdin.yaml file:

    -
      -
    +
      -
         source: '/website/versioned_docs/**/*.md'
         translation: '/website/translated_docs/%locale%/**/%original_file_name%'
         languages_mapping: *anchor
    diff --git a/docs/en/1.0.11/versioning.html b/docs/en/1.0.11/versioning.html
    index fc903eb43f..5298deba0c 100644
    --- a/docs/en/1.0.11/versioning.html
    +++ b/docs/en/1.0.11/versioning.html
    @@ -50,19 +50,19 @@
             
    Edit

    Versioning

    You can use the version script to cut a new documentation version based on the latest content in the docs folder. That specific set of documentation will then be preserved and accessible even as the documentation in the docs folder changes moving forward.

    How to Create New Versions

    Run the following script to generate a starter versions page listing all the site versions:

    -
    yarn examples versions
    +
    yarn examples versions
     

    This creates the pages/en/versions.js file.

    You can edit this file later on to customize how you display the versions.

    Add the following script to your package.json file if it doesn't already exist:

    -
    ...
    +
    ...
     "scripts": {
       "version": "docusaurus-version"
     },
     ...
     

    Run the script with a command line argument of the version you wish to create. e.g.,

    -
    yarn run version 1.0.0
    +
    yarn run version 1.0.0
     

    This will preserve all documents currently in the docs folder and make them available as documentation for version 1.0.0.

    If, for example, you ran the version script with 1.0.0 as the version number, version 1.0.0 is considered the latest release version for your project. 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.

    @@ -81,14 +81,14 @@

    For example, a document with the original id doc1 exists for the latest version, 1.0.0, and has the same content as the document with the id doc1 in the docs folder. When a new version 2.0.0 is created, the file for doc1 will not be copied into versioned_docs/version-2.0.0/. There will still be a page for docs/2.0.0/doc1.html, but it will use the file from version 1.0.0.

    Renaming Existing Versions

    To rename an existing version number to something else, first make sure the following script is in your package.json file:

    -
    ...
    +
    ...
     "scripts": {
       "rename-version": "docusaurus-rename-version"
     },
     ...
     

    Run the script with command line arguments of first, the current version name, then second, the new version name. e.g.,

    -
    yarn run rename-version 1.0.0 1.0.1
    +
    yarn run rename-version 1.0.0 1.0.1
     

    Versioning and Translations

    If you wish to use versioning and translations features, the crowdin.yaml 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 translated_docs/${language}/version-${version}/. For more information, check out the translations guide.

    diff --git a/docs/en/1.0.11/versioning/index.html b/docs/en/1.0.11/versioning/index.html index fc903eb43f..5298deba0c 100644 --- a/docs/en/1.0.11/versioning/index.html +++ b/docs/en/1.0.11/versioning/index.html @@ -50,19 +50,19 @@
    Edit

    Versioning

    You can use the version script to cut a new documentation version based on the latest content in the docs folder. That specific set of documentation will then be preserved and accessible even as the documentation in the docs folder changes moving forward.

    How to Create New Versions

    Run the following script to generate a starter versions page listing all the site versions:

    -
    yarn examples versions
    +
    yarn examples versions
     

    This creates the pages/en/versions.js file.

    You can edit this file later on to customize how you display the versions.

    Add the following script to your package.json file if it doesn't already exist:

    -
    ...
    +
    ...
     "scripts": {
       "version": "docusaurus-version"
     },
     ...
     

    Run the script with a command line argument of the version you wish to create. e.g.,

    -
    yarn run version 1.0.0
    +
    yarn run version 1.0.0
     

    This will preserve all documents currently in the docs folder and make them available as documentation for version 1.0.0.

    If, for example, you ran the version script with 1.0.0 as the version number, version 1.0.0 is considered the latest release version for your project. 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.

    @@ -81,14 +81,14 @@

    For example, a document with the original id doc1 exists for the latest version, 1.0.0, and has the same content as the document with the id doc1 in the docs folder. When a new version 2.0.0 is created, the file for doc1 will not be copied into versioned_docs/version-2.0.0/. There will still be a page for docs/2.0.0/doc1.html, but it will use the file from version 1.0.0.

    Renaming Existing Versions

    To rename an existing version number to something else, first make sure the following script is in your package.json file:

    -
    ...
    +
    ...
     "scripts": {
       "rename-version": "docusaurus-rename-version"
     },
     ...
     

    Run the script with command line arguments of first, the current version name, then second, the new version name. e.g.,

    -
    yarn run rename-version 1.0.0 1.0.1
    +
    yarn run rename-version 1.0.0 1.0.1
     

    Versioning and Translations

    If you wish to use versioning and translations features, the crowdin.yaml 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 translated_docs/${language}/version-${version}/. For more information, check out the translations guide.

    diff --git a/docs/en/1.0.12/api-pages.html b/docs/en/1.0.12/api-pages.html index 02a82a81fe..05dfe49912 100644 --- a/docs/en/1.0.12/api-pages.html +++ b/docs/en/1.0.12/api-pages.html @@ -59,7 +59,7 @@

    CompLibrary.MarkdownBlock

    A React component that parses markdown and renders to HTML.

    Example:

    -
    const MarkdownBlock = CompLibrary.MarkdownBlock;
    +
    const MarkdownBlock = CompLibrary.MarkdownBlock;
     
     <MarkdownBlock>
       [Markdown syntax for a link](http://www.example.com)
    @@ -79,7 +79,7 @@
     
     
     

    Example

    -
    <Container
    +
    <Container
       padding={['bottom', 'top']}
       background="light"
       className="myCustomClass">
    @@ -144,19 +144,19 @@
     

    Translating Strings

    When translations are enabled, any pages inside website/pages/en will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the languages.js file. E.g. The url for a French page of website/pages/en/help.js would be found at ${baseUrl}fr/help.html.

    When writing pages that you wish to translate, wrap any strings to be translated inside a <translate> tag. e.g.,

    -
    <p>
    +
    <p>
       <translate>I like translations</translate>
     </p>
     

    You can also provide an optional description attribute to provide context for translators. e.g,

    -
    <a href="/community">
    +
    <a href="/community">
       <translate desc="Footer link to page referring to community GitHub and Slack">
         Community
       </translate>
     </a>
     

    Add the following require statement as well:

    -
    const translate = require('../../server/translate.js').translate;
    +
    const translate = require('../../server/translate.js').translate;
     

    Note that this path is valid for files inside pages/en and should be adjusted accordingly if files are in different locations, as discussed above.

    Using Static Assets

    diff --git a/docs/en/1.0.12/api-pages/index.html b/docs/en/1.0.12/api-pages/index.html index 02a82a81fe..05dfe49912 100644 --- a/docs/en/1.0.12/api-pages/index.html +++ b/docs/en/1.0.12/api-pages/index.html @@ -59,7 +59,7 @@

    CompLibrary.MarkdownBlock

    A React component that parses markdown and renders to HTML.

    Example:

    -
    const MarkdownBlock = CompLibrary.MarkdownBlock;
    +
    const MarkdownBlock = CompLibrary.MarkdownBlock;
     
     <MarkdownBlock>
       [Markdown syntax for a link](http://www.example.com)
    @@ -79,7 +79,7 @@
     
     
     

    Example

    -
    <Container
    +
    <Container
       padding={['bottom', 'top']}
       background="light"
       className="myCustomClass">
    @@ -144,19 +144,19 @@
     

    Translating Strings

    When translations are enabled, any pages inside website/pages/en will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the languages.js file. E.g. The url for a French page of website/pages/en/help.js would be found at ${baseUrl}fr/help.html.

    When writing pages that you wish to translate, wrap any strings to be translated inside a <translate> tag. e.g.,

    -
    <p>
    +
    <p>
       <translate>I like translations</translate>
     </p>
     

    You can also provide an optional description attribute to provide context for translators. e.g,

    -
    <a href="/community">
    +
    <a href="/community">
       <translate desc="Footer link to page referring to community GitHub and Slack">
         Community
       </translate>
     </a>
     

    Add the following require statement as well:

    -
    const translate = require('../../server/translate.js').translate;
    +
    const translate = require('../../server/translate.js').translate;
     

    Note that this path is valid for files inside pages/en and should be adjusted accordingly if files are in different locations, as discussed above.

    Using Static Assets

    diff --git a/docs/en/1.0.12/commands.html b/docs/en/1.0.12/commands.html index 3d15d2eaaf..408caa1bbf 100644 --- a/docs/en/1.0.12/commands.html +++ b/docs/en/1.0.12/commands.html @@ -100,7 +100,7 @@
  • USE_SSH: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.
  • e.g.,

    -
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
    +
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
     

    The following environment variables are set by CircleCI during the build process.

      diff --git a/docs/en/1.0.12/commands/index.html b/docs/en/1.0.12/commands/index.html index 3d15d2eaaf..408caa1bbf 100644 --- a/docs/en/1.0.12/commands/index.html +++ b/docs/en/1.0.12/commands/index.html @@ -100,7 +100,7 @@
    • USE_SSH: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.

    e.g.,

    -
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
    +
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
     

    The following environment variables are set by CircleCI during the build process.

      diff --git a/docs/en/1.0.12/custom-pages.html b/docs/en/1.0.12/custom-pages.html index 5a40c99785..4b5ab7a080 100644 --- a/docs/en/1.0.12/custom-pages.html +++ b/docs/en/1.0.12/custom-pages.html @@ -53,7 +53,7 @@

      You can start your local server and go to http://localhost:3000 to see what the example home page looks like. From there, edit the website/pages/en/index.js file and its various components to use the images and text you want for your project.

      Adding Other Custom Pages

      Docusaurus provides some simple example pages in the website/pages/en directory, including index.js, users.js, and help.js. These are good examples to showcase how to create a custom page for Docusaurus.

      -
      root-of-repo
      +
      root-of-repo
       ├── docs
       └── website
       │   └── blog
      @@ -85,7 +85,7 @@
       

      Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.

      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.

      If you do not want a footer for your site, change the render function of core/Footer.js to return null. e.g.,

      -
      const React = require("react");
      +
      const React = require("react");
       
       class Footer extends React.Component {
         render() {
      diff --git a/docs/en/1.0.12/custom-pages/index.html b/docs/en/1.0.12/custom-pages/index.html
      index 5a40c99785..4b5ab7a080 100644
      --- a/docs/en/1.0.12/custom-pages/index.html
      +++ b/docs/en/1.0.12/custom-pages/index.html
      @@ -53,7 +53,7 @@
       

      You can start your local server and go to http://localhost:3000 to see what the example home page looks like. From there, edit the website/pages/en/index.js file and its various components to use the images and text you want for your project.

      Adding Other Custom Pages

      Docusaurus provides some simple example pages in the website/pages/en directory, including index.js, users.js, and help.js. These are good examples to showcase how to create a custom page for Docusaurus.

      -
      root-of-repo
      +
      root-of-repo
       ├── docs
       └── website
       │   └── blog
      @@ -85,7 +85,7 @@
       

      Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.

      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.

      If you do not want a footer for your site, change the render function of core/Footer.js to return null. e.g.,

      -
      const React = require("react");
      +
      const React = require("react");
       
       class Footer extends React.Component {
         render() {
      diff --git a/docs/en/1.0.12/doc-markdown.html b/docs/en/1.0.12/doc-markdown.html
      index a74c8fd05d..63d0c64107 100644
      --- a/docs/en/1.0.12/doc-markdown.html
      +++ b/docs/en/1.0.12/doc-markdown.html
      @@ -55,7 +55,7 @@
       

      hide_title: Whether to hide the title at the top of the doc.

      sidebar_label: The text shown in the document sidebar for this document. If this field is not present, the document's sidebar_label will default to its title.

      For example:

      -
      ---
      +
      ---
       id: doc1
       title: My Document
       sidebar_label: Document
      @@ -63,7 +63,7 @@ title: My Document
       

      Versioned documents have their ids altered to include the version number when they get copied. The new id is version-${version}-${id} where ${version} is the version number of that document and ${id} is the original id. Additionally, versioned documents get an added original_id field with the original document id.

      For example:

      -
      ---
      +
      ---
       id: version-1.0.0-doc1
       title: My Document
       sidebar_label: Document
      @@ -72,7 +72,7 @@ sidebar_label: Document
       

      custom_edit_url: The url for editing this document. If this field is not present, the document's edit url will fallback to editUrl from optional fields of siteConfig.js. See siteConfig.js docs for more information.

      For example:

      -
      ---
      +
      ---
       id: doc-markdown
       title: Markdown Features
       custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
      @@ -85,7 +85,7 @@ title: Markdown Features
       

      authorURL: 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.

      authorFBID: 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.

      For example:

      -
      ---
      +
      ---
       title: My First Blog Post
       author: Frank Li
       authorURL: http://twitter.com/franchementli
      @@ -97,20 +97,20 @@ authorURL: http://twitter.com/franchementli
       

      Linking other Documents

      You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.

      Example:

      -
      [This links to another document](other-document.md)
      +
      [This links to another document](other-document.md)
       

      This markdown will automatically get converted into a link to /docs/other-document.html (or the appropriately translated/versioned link) once it gets rendered.

      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.

      Linking to Images and Other Assets

      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 docs/assets and website/blog/assets, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.

      Example:

      -
      ![alt-text](/docs/assets/doc-image.png)
      +
      ![alt-text](/docs/assets/doc-image.png)
       

      Generating Table of Contents

      You can make an autogenerated list of links, which can be useful as a table of contents for API docs.

      In your markdown file, insert a line with the text <AUTOGENERATED_TABLE_OF_CONTENTS>. Write your documentation using h3 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 <AUTOGENERATED_TABLE_OF_CONTENTS>.

      Example:

      -
      ### `docusaurus.function(a, b)`
      +
      ### `docusaurus.function(a, b)`
       
       Text describing my function
       
      @@ -120,7 +120,7 @@ Text describing my function
       Text describing my function
       

      will lead to a table of contents of the functions:

      -
      - `docusaurus.function(a, b)`
      +
      - `docusaurus.function(a, b)`
       - `docdoc(file)`
       

      and each function will link to their corresponding sections in the page.

      @@ -134,20 +134,20 @@ ReactDOM.render( ```

      ...would be rendered with syntax highlighting like so:

      -
      ReactDOM.render(
      +
      ReactDOM.render(
         <h1>Hello, world!</h1>,
         document.getElementById('root')
       );
       

      Highlighting is provided by Highlight.js using the theme specified in your siteConfig.js file as part of the highlight key:

      -
      highlight: {
      +
      highlight: {
         theme: 'default'
       }
       

      You can find the full list of supported themes in the Highlight.js styles directory.

      Registering additional languages

      While Highlight.js provides support for many popular languages out of the box, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the hljs constant as part of the highlight config key. This in turn allows you to call registerLanguage:

      -
      highlight: {
      +
      highlight: {
         theme: 'default',
         hljs: function(hljs) {
           hljs.registerLanguage('galacticbasic', function(hljs) {
      diff --git a/docs/en/1.0.12/doc-markdown/index.html b/docs/en/1.0.12/doc-markdown/index.html
      index a74c8fd05d..63d0c64107 100644
      --- a/docs/en/1.0.12/doc-markdown/index.html
      +++ b/docs/en/1.0.12/doc-markdown/index.html
      @@ -55,7 +55,7 @@
       

      hide_title: Whether to hide the title at the top of the doc.

      sidebar_label: The text shown in the document sidebar for this document. If this field is not present, the document's sidebar_label will default to its title.

      For example:

      -
      ---
      +
      ---
       id: doc1
       title: My Document
       sidebar_label: Document
      @@ -63,7 +63,7 @@ title: My Document
       

      Versioned documents have their ids altered to include the version number when they get copied. The new id is version-${version}-${id} where ${version} is the version number of that document and ${id} is the original id. Additionally, versioned documents get an added original_id field with the original document id.

      For example:

      -
      ---
      +
      ---
       id: version-1.0.0-doc1
       title: My Document
       sidebar_label: Document
      @@ -72,7 +72,7 @@ sidebar_label: Document
       

      custom_edit_url: The url for editing this document. If this field is not present, the document's edit url will fallback to editUrl from optional fields of siteConfig.js. See siteConfig.js docs for more information.

      For example:

      -
      ---
      +
      ---
       id: doc-markdown
       title: Markdown Features
       custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
      @@ -85,7 +85,7 @@ title: Markdown Features
       

      authorURL: 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.

      authorFBID: 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.

      For example:

      -
      ---
      +
      ---
       title: My First Blog Post
       author: Frank Li
       authorURL: http://twitter.com/franchementli
      @@ -97,20 +97,20 @@ authorURL: http://twitter.com/franchementli
       

      Linking other Documents

      You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.

      Example:

      -
      [This links to another document](other-document.md)
      +
      [This links to another document](other-document.md)
       

      This markdown will automatically get converted into a link to /docs/other-document.html (or the appropriately translated/versioned link) once it gets rendered.

      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.

      Linking to Images and Other Assets

      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 docs/assets and website/blog/assets, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.

      Example:

      -
      ![alt-text](/docs/assets/doc-image.png)
      +
      ![alt-text](/docs/assets/doc-image.png)
       

      Generating Table of Contents

      You can make an autogenerated list of links, which can be useful as a table of contents for API docs.

      In your markdown file, insert a line with the text <AUTOGENERATED_TABLE_OF_CONTENTS>. Write your documentation using h3 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 <AUTOGENERATED_TABLE_OF_CONTENTS>.

      Example:

      -
      ### `docusaurus.function(a, b)`
      +
      ### `docusaurus.function(a, b)`
       
       Text describing my function
       
      @@ -120,7 +120,7 @@ Text describing my function
       Text describing my function
       

      will lead to a table of contents of the functions:

      -
      - `docusaurus.function(a, b)`
      +
      - `docusaurus.function(a, b)`
       - `docdoc(file)`
       

      and each function will link to their corresponding sections in the page.

      @@ -134,20 +134,20 @@ ReactDOM.render( ```

      ...would be rendered with syntax highlighting like so:

      -
      ReactDOM.render(
      +
      ReactDOM.render(
         <h1>Hello, world!</h1>,
         document.getElementById('root')
       );
       

      Highlighting is provided by Highlight.js using the theme specified in your siteConfig.js file as part of the highlight key:

      -
      highlight: {
      +
      highlight: {
         theme: 'default'
       }
       

      You can find the full list of supported themes in the Highlight.js styles directory.

      Registering additional languages

      While Highlight.js provides support for many popular languages out of the box, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the hljs constant as part of the highlight config key. This in turn allows you to call registerLanguage:

      -
      highlight: {
      +
      highlight: {
         theme: 'default',
         hljs: function(hljs) {
           hljs.registerLanguage('galacticbasic', function(hljs) {
      diff --git a/docs/en/1.0.12/installation.html b/docs/en/1.0.12/installation.html
      index e270ba928f..1f265d42e3 100644
      --- a/docs/en/1.0.12/installation.html
      +++ b/docs/en/1.0.12/installation.html
      @@ -61,7 +61,7 @@
       

      After docusaurus is installed, moving forward, you can check your current version of Docusaurus by going into the website directory and typing npm list docusaurus. You can update to the latest version of Docusaurus by typing npm update.

      Along with previously existing files and directories, your root directory will now contain a structure similar to:

      -
      root-of-repo
      +
      root-of-repo
       ├── docs-examples-from-docusaurus
       │   └── doc1.md
       │   └── doc2.md
      diff --git a/docs/en/1.0.12/installation/index.html b/docs/en/1.0.12/installation/index.html
      index e270ba928f..1f265d42e3 100644
      --- a/docs/en/1.0.12/installation/index.html
      +++ b/docs/en/1.0.12/installation/index.html
      @@ -61,7 +61,7 @@
       

      After docusaurus is installed, moving forward, you can check your current version of Docusaurus by going into the website directory and typing npm list docusaurus. You can update to the latest version of Docusaurus by typing npm update.

      Along with previously existing files and directories, your root directory will now contain a structure similar to:

      -
      root-of-repo
      +
      root-of-repo
       ├── docs-examples-from-docusaurus
       │   └── doc1.md
       │   └── doc2.md
      diff --git a/docs/en/1.0.12/publishing.html b/docs/en/1.0.12/publishing.html
      index e159933e0c..85c39a9961 100644
      --- a/docs/en/1.0.12/publishing.html
      +++ b/docs/en/1.0.12/publishing.html
      @@ -102,7 +102,7 @@
       
       

      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:

      To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate.

      -
      GIT_USER=<GIT_USER> \
      +
      GIT_USER=<GIT_USER> \
         CURRENT_BRANCH=master \
         USE_SSH=true \
         yarn run publish-gh-pages # or `npm run publish-gh-pages`
      @@ -126,7 +126,7 @@
       
    • Create a .circleci folder and create a config.yml under that folder.
    • Copy the text below into .circleci/config.yml.
    • -
      # If you only one circle to run on direct commits to master, you can uncomment this out
      +
      # If you only one circle to run on direct commits to master, you can uncomment this out
       # and uncomment the filters: *filter-only-master down below too
       #
       # aliases:
      @@ -173,7 +173,7 @@
       
       

      Tips & Tricks

      When initially deploying to a gh-pages branch using Circle CI, you may notice that some jobs triggered by commits to the gh-pages 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:

      -
      # Circle CI 2.0 Config File
      +
      # Circle CI 2.0 Config File
       # This config file will prevent tests from being run on the gh-pages branch.
       version: 2
       jobs:
      diff --git a/docs/en/1.0.12/publishing/index.html b/docs/en/1.0.12/publishing/index.html
      index e159933e0c..85c39a9961 100644
      --- a/docs/en/1.0.12/publishing/index.html
      +++ b/docs/en/1.0.12/publishing/index.html
      @@ -102,7 +102,7 @@
       
       

      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:

      To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate.

      -
      GIT_USER=<GIT_USER> \
      +
      GIT_USER=<GIT_USER> \
         CURRENT_BRANCH=master \
         USE_SSH=true \
         yarn run publish-gh-pages # or `npm run publish-gh-pages`
      @@ -126,7 +126,7 @@
       
    • Create a .circleci folder and create a config.yml under that folder.
    • Copy the text below into .circleci/config.yml.
    • -
      # If you only one circle to run on direct commits to master, you can uncomment this out
      +
      # If you only one circle to run on direct commits to master, you can uncomment this out
       # and uncomment the filters: *filter-only-master down below too
       #
       # aliases:
      @@ -173,7 +173,7 @@
       
       

      Tips & Tricks

      When initially deploying to a gh-pages branch using Circle CI, you may notice that some jobs triggered by commits to the gh-pages 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:

      -
      # Circle CI 2.0 Config File
      +
      # Circle CI 2.0 Config File
       # This config file will prevent tests from being run on the gh-pages branch.
       version: 2
       jobs:
      diff --git a/docs/en/1.0.12/search.html b/docs/en/1.0.12/search.html
      index 7c9d968011..f7d6ac2529 100644
      --- a/docs/en/1.0.12/search.html
      +++ b/docs/en/1.0.12/search.html
      @@ -50,7 +50,7 @@
               
    Edit

    Enabling Search

    Docusaurus supports search using Algolia DocSearch. Once you have set up your site, enter your site information to have Algolia crawl your website's documentation pages. Algolia will then send you an API key and index name for your site.

    Enabling the Search Bar

    Enter your search-only API key and index name into siteConfig.js in the algolia section to enable search for your site.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       algolia: {
         apiKey: "my-search-only-api-key-1234",
    @@ -61,7 +61,7 @@
     

    Extra Search Options

    You can also specify extra search options used by Algolia by using an algoliaOptions field in algolia. 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 found here.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       algolia: {
         ...
    @@ -75,7 +75,7 @@
     

    Controlling the Location of the Search Bar

    By default, the search bar will be the rightmost element in the top navigation bar.

    If you want to change the default location, add the searchBar flag in the headerLinks field of siteConfig.js in your desired location. For example, you may want the search bar in between your internal and external links.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       headerLinks: [
         {...}
    diff --git a/docs/en/1.0.12/search/index.html b/docs/en/1.0.12/search/index.html
    index 7c9d968011..f7d6ac2529 100644
    --- a/docs/en/1.0.12/search/index.html
    +++ b/docs/en/1.0.12/search/index.html
    @@ -50,7 +50,7 @@
             
    Edit

    Enabling Search

    Docusaurus supports search using Algolia DocSearch. Once you have set up your site, enter your site information to have Algolia crawl your website's documentation pages. Algolia will then send you an API key and index name for your site.

    Enabling the Search Bar

    Enter your search-only API key and index name into siteConfig.js in the algolia section to enable search for your site.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       algolia: {
         apiKey: "my-search-only-api-key-1234",
    @@ -61,7 +61,7 @@
     

    Extra Search Options

    You can also specify extra search options used by Algolia by using an algoliaOptions field in algolia. 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 found here.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       algolia: {
         ...
    @@ -75,7 +75,7 @@
     

    Controlling the Location of the Search Bar

    By default, the search bar will be the rightmost element in the top navigation bar.

    If you want to change the default location, add the searchBar flag in the headerLinks field of siteConfig.js in your desired location. For example, you may want the search bar in between your internal and external links.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       headerLinks: [
         {...}
    diff --git a/docs/en/1.0.12/site-config.html b/docs/en/1.0.12/site-config.html
    index c4a04bbcbd..55bf3f3c77 100644
    --- a/docs/en/1.0.12/site-config.html
    +++ b/docs/en/1.0.12/site-config.html
    @@ -66,7 +66,7 @@
     

    headerIcon - url for icon used in header navigation bar.

    headerLinks - Links that will be used in the header navigation bar. The label field of each object will be the link text and will also be translated for each language.

    Example Usage:

    -
    headerLinks: [
    +
    headerLinks: [
       // Links to document with id doc1 for current language/version
       { doc: "doc1", label: "Getting Started" },
       // Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language
    @@ -97,9 +97,9 @@
     

    blogSidebarCount - Control the number of blog posts that show up in the sidebar. See the adding a blog docs for more information.

    cname - The CNAME for your website. It will go into a CNAME file when your site it built.

    customDocsPath - By default, Docusaurus expects your documentation to be in a directory called docs. This directory is at the same level as the website directory (i.e., not inside the website directory). You can specify a custom path to your documentation with this field. Note that all of your documentation *.md files must still reside in a flat hierarchy. You cannot have your documents in nested directories.

    -
    customDocsPath: "docs/site"
    +
    customDocsPath: "docs/site"
     
    -
    customDocsPath: "website-docs"
    +
    customDocsPath: "website-docs"
     

    disableHeaderTitle - 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 true.

    disableTitleTagline - An option to disable showing the tagline in the title of main pages. Exclude this field to keep page titles as Title • Tagline. Set to true to make page titles just Title.

    diff --git a/docs/en/1.0.12/site-config/index.html b/docs/en/1.0.12/site-config/index.html index c4a04bbcbd..55bf3f3c77 100644 --- a/docs/en/1.0.12/site-config/index.html +++ b/docs/en/1.0.12/site-config/index.html @@ -66,7 +66,7 @@

    headerIcon - url for icon used in header navigation bar.

    headerLinks - Links that will be used in the header navigation bar. The label field of each object will be the link text and will also be translated for each language.

    Example Usage:

    -
    headerLinks: [
    +
    headerLinks: [
       // Links to document with id doc1 for current language/version
       { doc: "doc1", label: "Getting Started" },
       // Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language
    @@ -97,9 +97,9 @@
     

    blogSidebarCount - Control the number of blog posts that show up in the sidebar. See the adding a blog docs for more information.

    cname - The CNAME for your website. It will go into a CNAME file when your site it built.

    customDocsPath - By default, Docusaurus expects your documentation to be in a directory called docs. This directory is at the same level as the website directory (i.e., not inside the website directory). You can specify a custom path to your documentation with this field. Note that all of your documentation *.md files must still reside in a flat hierarchy. You cannot have your documents in nested directories.

    -
    customDocsPath: "docs/site"
    +
    customDocsPath: "docs/site"
     
    -
    customDocsPath: "website-docs"
    +
    customDocsPath: "website-docs"
     

    disableHeaderTitle - 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 true.

    disableTitleTagline - An option to disable showing the tagline in the title of main pages. Exclude this field to keep page titles as Title • Tagline. Set to true to make page titles just Title.

    diff --git a/docs/en/1.0.12/site-creation.html b/docs/en/1.0.12/site-creation.html index 08a11b79a0..eb80a4b4d3 100644 --- a/docs/en/1.0.12/site-creation.html +++ b/docs/en/1.0.12/site-creation.html @@ -51,7 +51,7 @@

    After installation and preparation, much of the work to create a basic site for your docs is already complete.

    Site Structure

    Your site structure looks like the following:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs
     └── website
     │   └── blog
    diff --git a/docs/en/1.0.12/site-creation/index.html b/docs/en/1.0.12/site-creation/index.html
    index 08a11b79a0..eb80a4b4d3 100644
    --- a/docs/en/1.0.12/site-creation/index.html
    +++ b/docs/en/1.0.12/site-creation/index.html
    @@ -51,7 +51,7 @@
     

    After installation and preparation, much of the work to create a basic site for your docs is already complete.

    Site Structure

    Your site structure looks like the following:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs
     └── website
     │   └── blog
    diff --git a/docs/en/1.0.12/site-preparation.html b/docs/en/1.0.12/site-preparation.html
    index 7a496d9ecd..c32cf39d32 100644
    --- a/docs/en/1.0.12/site-preparation.html
    +++ b/docs/en/1.0.12/site-preparation.html
    @@ -50,7 +50,7 @@
             
    Edit

    Site Preparation

    After installing Docusaurus, 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.

    Directory Structure

    As shown after you installed Docusaurus, the initialization script created a directory structure similar to:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs-examples-from-docusaurus
     │   └── doc1.md
     │   └── doc2.md
    diff --git a/docs/en/1.0.12/site-preparation/index.html b/docs/en/1.0.12/site-preparation/index.html
    index 7a496d9ecd..c32cf39d32 100644
    --- a/docs/en/1.0.12/site-preparation/index.html
    +++ b/docs/en/1.0.12/site-preparation/index.html
    @@ -50,7 +50,7 @@
             
    Edit

    Site Preparation

    After installing Docusaurus, 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.

    Directory Structure

    As shown after you installed Docusaurus, the initialization script created a directory structure similar to:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs-examples-from-docusaurus
     │   └── doc1.md
     │   └── doc2.md
    diff --git a/docs/en/1.0.12/translation.html b/docs/en/1.0.12/translation.html
    index 04ce68e23a..022c70f566 100644
    --- a/docs/en/1.0.12/translation.html
    +++ b/docs/en/1.0.12/translation.html
    @@ -76,7 +76,7 @@ languages.js
     

    Pages allow you to customize layout and specific content of pages like a custom index page or help page.

    Pages with text that you want translated should be placed in website/pages/en folder.

    Wrap strings you want translated in a <translate> tag, and add the following require statement to the top of the file:

    -
    ...
    +
    ...
     const translate = require("../../server/translate.js").translate;
     ...
     <h2>
    @@ -85,7 +85,7 @@ languages.js
     ...
     

    You can also include an optional description attribute to give more context to a translator about how to translate the string:

    -
    <p>
    +
    <p>
       <translate desc="flower, not verb">Rose</translate>
     <p>
     
    @@ -95,7 +95,7 @@ languages.js

    Gathering Strings to Translate

    The strings within localized Pages must be extracted and provided to Crowdin.

    Add the following script to your website/package.json file, if it does not exist already:

    -
    ...
    +
    ...
     "scripts": {
       "write-translations": "docusaurus-write-translations"
     },
    @@ -133,7 +133,7 @@ languages.js
     
     

    The example below can be automatically generated by the Docusaurus cli with the examples script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.

    Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.

    -
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
    +
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
     api_key_env: CROWDIN_DOCUSAURUS_API_KEY
     base_path: "./"
     preserve_hierarchy: true
    @@ -158,7 +158,7 @@ languages.js
     

    Setup the Crowdin Scripts

    You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in /docs as well as translatable strings in website/i18n/en.json. (These strings can be generated by running yarn write-translations.)

    You can add the following to your package.json to manually trigger Crowdin.

    -
    "scripts": {
    +
    "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.js
     

    Automated File Sync Using CircleCI

    You can automate pulling down and uploading translations for your files using the CircleCI web continuous integration service.

    First, update the circle.yml 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 circle.yml file:

    -
    machine:
    +
    machine:
       node:
         version: 6.10.3
       npm:
    @@ -219,7 +219,7 @@ languages.js
     

    If you wish to use Crowdin on your machine locally, you can install the Crowdin CLI tool and run the same commands found in the circle.yaml file. The only difference is that you must set project_identifier and api_key values in the crowdin.yaml file since you will not have Circle environment variables set up.

    Versioned Translations

    If you wish to have translation and versioning for your documentation, add the following section to the end of your crowdin.yaml file:

    -
      -
    +
      -
         source: '/website/versioned_docs/**/*.md'
         translation: '/website/translated_docs/%locale%/**/%original_file_name%'
         languages_mapping: *anchor
    diff --git a/docs/en/1.0.12/translation/index.html b/docs/en/1.0.12/translation/index.html
    index 04ce68e23a..022c70f566 100644
    --- a/docs/en/1.0.12/translation/index.html
    +++ b/docs/en/1.0.12/translation/index.html
    @@ -76,7 +76,7 @@ languages.js
     

    Pages allow you to customize layout and specific content of pages like a custom index page or help page.

    Pages with text that you want translated should be placed in website/pages/en folder.

    Wrap strings you want translated in a <translate> tag, and add the following require statement to the top of the file:

    -
    ...
    +
    ...
     const translate = require("../../server/translate.js").translate;
     ...
     <h2>
    @@ -85,7 +85,7 @@ languages.js
     ...
     

    You can also include an optional description attribute to give more context to a translator about how to translate the string:

    -
    <p>
    +
    <p>
       <translate desc="flower, not verb">Rose</translate>
     <p>
     
    @@ -95,7 +95,7 @@ languages.js

    Gathering Strings to Translate

    The strings within localized Pages must be extracted and provided to Crowdin.

    Add the following script to your website/package.json file, if it does not exist already:

    -
    ...
    +
    ...
     "scripts": {
       "write-translations": "docusaurus-write-translations"
     },
    @@ -133,7 +133,7 @@ languages.js
     
     

    The example below can be automatically generated by the Docusaurus cli with the examples script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.

    Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.

    -
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
    +
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
     api_key_env: CROWDIN_DOCUSAURUS_API_KEY
     base_path: "./"
     preserve_hierarchy: true
    @@ -158,7 +158,7 @@ languages.js
     

    Setup the Crowdin Scripts

    You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in /docs as well as translatable strings in website/i18n/en.json. (These strings can be generated by running yarn write-translations.)

    You can add the following to your package.json to manually trigger Crowdin.

    -
    "scripts": {
    +
    "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.js
     

    Automated File Sync Using CircleCI

    You can automate pulling down and uploading translations for your files using the CircleCI web continuous integration service.

    First, update the circle.yml 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 circle.yml file:

    -
    machine:
    +
    machine:
       node:
         version: 6.10.3
       npm:
    @@ -219,7 +219,7 @@ languages.js
     

    If you wish to use Crowdin on your machine locally, you can install the Crowdin CLI tool and run the same commands found in the circle.yaml file. The only difference is that you must set project_identifier and api_key values in the crowdin.yaml file since you will not have Circle environment variables set up.

    Versioned Translations

    If you wish to have translation and versioning for your documentation, add the following section to the end of your crowdin.yaml file:

    -
      -
    +
      -
         source: '/website/versioned_docs/**/*.md'
         translation: '/website/translated_docs/%locale%/**/%original_file_name%'
         languages_mapping: *anchor
    diff --git a/docs/en/1.0.12/versioning.html b/docs/en/1.0.12/versioning.html
    index ac284b03b3..38239b6c9f 100644
    --- a/docs/en/1.0.12/versioning.html
    +++ b/docs/en/1.0.12/versioning.html
    @@ -50,19 +50,19 @@
             
    Edit

    Versioning

    You can use the version script to cut a new documentation version based on the latest content in the docs folder. That specific set of documentation will then be preserved and accessible even as the documentation in the docs folder changes moving forward.

    How to Create New Versions

    Run the following script to generate a starter versions page listing all the site versions:

    -
    yarn examples versions
    +
    yarn examples versions
     

    This creates the pages/en/versions.js file.

    You can edit this file later on to customize how you display the versions.

    Add the following script to your package.json file if it doesn't already exist:

    -
    ...
    +
    ...
     "scripts": {
       "version": "docusaurus-version"
     },
     ...
     

    Run the script with a command line argument of the version you wish to create. e.g.,

    -
    yarn run version 1.0.0
    +
    yarn run version 1.0.0
     

    This will preserve all documents currently in the docs folder and make them available as documentation for version 1.0.0.

    If, for example, you ran the version script with 1.0.0 as the version number, version 1.0.0 is considered the latest release version for your project. 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.

    @@ -93,14 +93,14 @@

    For example, a document with the original id doc1 exists for the latest version, 1.0.0, and has the same content as the document with the id doc1 in the docs folder. When a new version 2.0.0 is created, the file for doc1 will not be copied into versioned_docs/version-2.0.0/. There will still be a page for docs/2.0.0/doc1.html, but it will use the file from version 1.0.0.

    Renaming Existing Versions

    To rename an existing version number to something else, first make sure the following script is in your package.json file:

    -
    ...
    +
    ...
     "scripts": {
       "rename-version": "docusaurus-rename-version"
     },
     ...
     

    Run the script with command line arguments of first, the current version name, then second, the new version name. e.g.,

    -
    yarn run rename-version 1.0.0 1.0.1
    +
    yarn run rename-version 1.0.0 1.0.1
     

    Versioning and Translations

    If you wish to use versioning and translations features, the crowdin.yaml 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 translated_docs/${language}/version-${version}/. For more information, check out the translations guide.

    diff --git a/docs/en/1.0.12/versioning/index.html b/docs/en/1.0.12/versioning/index.html index ac284b03b3..38239b6c9f 100644 --- a/docs/en/1.0.12/versioning/index.html +++ b/docs/en/1.0.12/versioning/index.html @@ -50,19 +50,19 @@
    Edit

    Versioning

    You can use the version script to cut a new documentation version based on the latest content in the docs folder. That specific set of documentation will then be preserved and accessible even as the documentation in the docs folder changes moving forward.

    How to Create New Versions

    Run the following script to generate a starter versions page listing all the site versions:

    -
    yarn examples versions
    +
    yarn examples versions
     

    This creates the pages/en/versions.js file.

    You can edit this file later on to customize how you display the versions.

    Add the following script to your package.json file if it doesn't already exist:

    -
    ...
    +
    ...
     "scripts": {
       "version": "docusaurus-version"
     },
     ...
     

    Run the script with a command line argument of the version you wish to create. e.g.,

    -
    yarn run version 1.0.0
    +
    yarn run version 1.0.0
     

    This will preserve all documents currently in the docs folder and make them available as documentation for version 1.0.0.

    If, for example, you ran the version script with 1.0.0 as the version number, version 1.0.0 is considered the latest release version for your project. 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.

    @@ -93,14 +93,14 @@

    For example, a document with the original id doc1 exists for the latest version, 1.0.0, and has the same content as the document with the id doc1 in the docs folder. When a new version 2.0.0 is created, the file for doc1 will not be copied into versioned_docs/version-2.0.0/. There will still be a page for docs/2.0.0/doc1.html, but it will use the file from version 1.0.0.

    Renaming Existing Versions

    To rename an existing version number to something else, first make sure the following script is in your package.json file:

    -
    ...
    +
    ...
     "scripts": {
       "rename-version": "docusaurus-rename-version"
     },
     ...
     

    Run the script with command line arguments of first, the current version name, then second, the new version name. e.g.,

    -
    yarn run rename-version 1.0.0 1.0.1
    +
    yarn run rename-version 1.0.0 1.0.1
     

    Versioning and Translations

    If you wish to use versioning and translations features, the crowdin.yaml 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 translated_docs/${language}/version-${version}/. For more information, check out the translations guide.

    diff --git a/docs/en/1.0.13/api-pages.html b/docs/en/1.0.13/api-pages.html index 5ea14f87c9..2e813196ae 100644 --- a/docs/en/1.0.13/api-pages.html +++ b/docs/en/1.0.13/api-pages.html @@ -59,7 +59,7 @@

    CompLibrary.MarkdownBlock

    A React component that parses markdown and renders to HTML.

    Example:

    -
    const MarkdownBlock = CompLibrary.MarkdownBlock;
    +
    const MarkdownBlock = CompLibrary.MarkdownBlock;
     
     <MarkdownBlock>
       [Markdown syntax for a link](http://www.example.com)
    @@ -79,7 +79,7 @@
     
     
     

    Example

    -
    <Container
    +
    <Container
       padding={['bottom', 'top']}
       background="light"
       className="myCustomClass">
    @@ -144,19 +144,19 @@
     

    Translating Strings

    When translations are enabled, any pages inside website/pages/en will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the languages.js file. E.g. The url for a French page of website/pages/en/help.js would be found at ${baseUrl}fr/help.html.

    When writing pages that you wish to translate, wrap any strings to be translated inside a <translate> tag. e.g.,

    -
    <p>
    +
    <p>
       <translate>I like translations</translate>
     </p>
     

    You can also provide an optional description attribute to provide context for translators. e.g,

    -
    <a href="/community">
    +
    <a href="/community">
       <translate desc="Footer link to page referring to community GitHub and Slack">
         Community
       </translate>
     </a>
     

    Add the following require statement as well:

    -
    const translate = require('../../server/translate.js').translate;
    +
    const translate = require('../../server/translate.js').translate;
     

    Note that this path is valid for files inside pages/en and should be adjusted accordingly if files are in different locations, as discussed above.

    Using Static Assets

    diff --git a/docs/en/1.0.13/api-pages/index.html b/docs/en/1.0.13/api-pages/index.html index 5ea14f87c9..2e813196ae 100644 --- a/docs/en/1.0.13/api-pages/index.html +++ b/docs/en/1.0.13/api-pages/index.html @@ -59,7 +59,7 @@

    CompLibrary.MarkdownBlock

    A React component that parses markdown and renders to HTML.

    Example:

    -
    const MarkdownBlock = CompLibrary.MarkdownBlock;
    +
    const MarkdownBlock = CompLibrary.MarkdownBlock;
     
     <MarkdownBlock>
       [Markdown syntax for a link](http://www.example.com)
    @@ -79,7 +79,7 @@
     
     
     

    Example

    -
    <Container
    +
    <Container
       padding={['bottom', 'top']}
       background="light"
       className="myCustomClass">
    @@ -144,19 +144,19 @@
     

    Translating Strings

    When translations are enabled, any pages inside website/pages/en will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the languages.js file. E.g. The url for a French page of website/pages/en/help.js would be found at ${baseUrl}fr/help.html.

    When writing pages that you wish to translate, wrap any strings to be translated inside a <translate> tag. e.g.,

    -
    <p>
    +
    <p>
       <translate>I like translations</translate>
     </p>
     

    You can also provide an optional description attribute to provide context for translators. e.g,

    -
    <a href="/community">
    +
    <a href="/community">
       <translate desc="Footer link to page referring to community GitHub and Slack">
         Community
       </translate>
     </a>
     

    Add the following require statement as well:

    -
    const translate = require('../../server/translate.js').translate;
    +
    const translate = require('../../server/translate.js').translate;
     

    Note that this path is valid for files inside pages/en and should be adjusted accordingly if files are in different locations, as discussed above.

    Using Static Assets

    diff --git a/docs/en/1.0.13/commands.html b/docs/en/1.0.13/commands.html index 394b2cacf7..2895de559d 100644 --- a/docs/en/1.0.13/commands.html +++ b/docs/en/1.0.13/commands.html @@ -100,7 +100,7 @@
  • USE_SSH: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.
  • e.g.,

    -
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
    +
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
     

    The following environment variables are set by CircleCI during the build process.

      diff --git a/docs/en/1.0.13/commands/index.html b/docs/en/1.0.13/commands/index.html index 394b2cacf7..2895de559d 100644 --- a/docs/en/1.0.13/commands/index.html +++ b/docs/en/1.0.13/commands/index.html @@ -100,7 +100,7 @@
    • USE_SSH: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.

    e.g.,

    -
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
    +
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
     

    The following environment variables are set by CircleCI during the build process.

      diff --git a/docs/en/1.0.13/custom-pages.html b/docs/en/1.0.13/custom-pages.html index d9fcb865cf..5d175bac8b 100644 --- a/docs/en/1.0.13/custom-pages.html +++ b/docs/en/1.0.13/custom-pages.html @@ -53,7 +53,7 @@

      You can start your local server and go to http://localhost:3000 to see what the example home page looks like. From there, edit the website/pages/en/index.js file and its various components to use the images and text you want for your project.

      Adding Other Custom Pages

      Docusaurus provides some simple example pages in the website/pages/en directory, including index.js, users.js, and help.js. These are good examples to showcase how to create a custom page for Docusaurus.

      -
      root-of-repo
      +
      root-of-repo
       ├── docs
       └── website
       │   └── blog
      @@ -85,7 +85,7 @@
       

      Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.

      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.

      If you do not want a footer for your site, change the render function of core/Footer.js to return null. e.g.,

      -
      const React = require("react");
      +
      const React = require("react");
       
       class Footer extends React.Component {
         render() {
      diff --git a/docs/en/1.0.13/custom-pages/index.html b/docs/en/1.0.13/custom-pages/index.html
      index d9fcb865cf..5d175bac8b 100644
      --- a/docs/en/1.0.13/custom-pages/index.html
      +++ b/docs/en/1.0.13/custom-pages/index.html
      @@ -53,7 +53,7 @@
       

      You can start your local server and go to http://localhost:3000 to see what the example home page looks like. From there, edit the website/pages/en/index.js file and its various components to use the images and text you want for your project.

      Adding Other Custom Pages

      Docusaurus provides some simple example pages in the website/pages/en directory, including index.js, users.js, and help.js. These are good examples to showcase how to create a custom page for Docusaurus.

      -
      root-of-repo
      +
      root-of-repo
       ├── docs
       └── website
       │   └── blog
      @@ -85,7 +85,7 @@
       

      Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.

      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.

      If you do not want a footer for your site, change the render function of core/Footer.js to return null. e.g.,

      -
      const React = require("react");
      +
      const React = require("react");
       
       class Footer extends React.Component {
         render() {
      diff --git a/docs/en/1.0.13/doc-markdown.html b/docs/en/1.0.13/doc-markdown.html
      index 535874230a..dfffbe69b6 100644
      --- a/docs/en/1.0.13/doc-markdown.html
      +++ b/docs/en/1.0.13/doc-markdown.html
      @@ -55,7 +55,7 @@
       

      hide_title: Whether to hide the title at the top of the doc.

      sidebar_label: The text shown in the document sidebar for this document. If this field is not present, the document's sidebar_label will default to its title.

      For example:

      -
      ---
      +
      ---
       id: doc1
       title: My Document
       sidebar_label: Document
      @@ -63,7 +63,7 @@ title: My Document
       

      Versioned documents have their ids altered to include the version number when they get copied. The new id is version-${version}-${id} where ${version} is the version number of that document and ${id} is the original id. Additionally, versioned documents get an added original_id field with the original document id.

      For example:

      -
      ---
      +
      ---
       id: version-1.0.0-doc1
       title: My Document
       sidebar_label: Document
      @@ -72,7 +72,7 @@ sidebar_label: Document
       

      custom_edit_url: The url for editing this document. If this field is not present, the document's edit url will fallback to editUrl from optional fields of siteConfig.js. See siteConfig.js docs for more information.

      For example:

      -
      ---
      +
      ---
       id: doc-markdown
       title: Markdown Features
       custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
      @@ -85,7 +85,7 @@ title: Markdown Features
       

      authorURL: 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.

      authorFBID: 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.

      For example:

      -
      ---
      +
      ---
       title: My First Blog Post
       author: Frank Li
       authorURL: http://twitter.com/franchementli
      @@ -97,20 +97,20 @@ authorURL: http://twitter.com/franchementli
       

      Linking other Documents

      You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.

      Example:

      -
      [This links to another document](other-document.md)
      +
      [This links to another document](other-document.md)
       

      This markdown will automatically get converted into a link to /docs/other-document.html (or the appropriately translated/versioned link) once it gets rendered.

      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.

      Linking to Images and Other Assets

      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 docs/assets and website/blog/assets, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.

      Example:

      -
      ![alt-text](/docs/assets/doc-image.png)
      +
      ![alt-text](/docs/assets/doc-image.png)
       

      Generating Table of Contents

      You can make an autogenerated list of links, which can be useful as a table of contents for API docs.

      In your markdown file, insert a line with the text <AUTOGENERATED_TABLE_OF_CONTENTS>. Write your documentation using h3 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 <AUTOGENERATED_TABLE_OF_CONTENTS>.

      Example:

      -
      ### `docusaurus.function(a, b)`
      +
      ### `docusaurus.function(a, b)`
       
       Text describing my function
       
      @@ -120,7 +120,7 @@ Text describing my function
       Text describing my function
       

      will lead to a table of contents of the functions:

      -
      - `docusaurus.function(a, b)`
      +
      - `docusaurus.function(a, b)`
       - `docdoc(file)`
       

      and each function will link to their corresponding sections in the page.

      @@ -134,20 +134,20 @@ ReactDOM.render( ```

      ...would be rendered with syntax highlighting like so:

      -
      ReactDOM.render(
      +
      ReactDOM.render(
         <h1>Hello, world!</h1>,
         document.getElementById('root')
       );
       

      Highlighting is provided by Highlight.js using the theme specified in your siteConfig.js file as part of the highlight key:

      -
      highlight: {
      +
      highlight: {
         theme: 'default'
       }
       

      You can find the full list of supported themes in the Highlight.js styles directory.

      Registering additional languages

      While Highlight.js provides support for many popular languages out of the box, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the hljs constant as part of the highlight config key. This in turn allows you to call registerLanguage:

      -
      highlight: {
      +
      highlight: {
         theme: 'default',
         hljs: function(hljs) {
           hljs.registerLanguage('galacticbasic', function(hljs) {
      diff --git a/docs/en/1.0.13/doc-markdown/index.html b/docs/en/1.0.13/doc-markdown/index.html
      index 535874230a..dfffbe69b6 100644
      --- a/docs/en/1.0.13/doc-markdown/index.html
      +++ b/docs/en/1.0.13/doc-markdown/index.html
      @@ -55,7 +55,7 @@
       

      hide_title: Whether to hide the title at the top of the doc.

      sidebar_label: The text shown in the document sidebar for this document. If this field is not present, the document's sidebar_label will default to its title.

      For example:

      -
      ---
      +
      ---
       id: doc1
       title: My Document
       sidebar_label: Document
      @@ -63,7 +63,7 @@ title: My Document
       

      Versioned documents have their ids altered to include the version number when they get copied. The new id is version-${version}-${id} where ${version} is the version number of that document and ${id} is the original id. Additionally, versioned documents get an added original_id field with the original document id.

      For example:

      -
      ---
      +
      ---
       id: version-1.0.0-doc1
       title: My Document
       sidebar_label: Document
      @@ -72,7 +72,7 @@ sidebar_label: Document
       

      custom_edit_url: The url for editing this document. If this field is not present, the document's edit url will fallback to editUrl from optional fields of siteConfig.js. See siteConfig.js docs for more information.

      For example:

      -
      ---
      +
      ---
       id: doc-markdown
       title: Markdown Features
       custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
      @@ -85,7 +85,7 @@ title: Markdown Features
       

      authorURL: 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.

      authorFBID: 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.

      For example:

      -
      ---
      +
      ---
       title: My First Blog Post
       author: Frank Li
       authorURL: http://twitter.com/franchementli
      @@ -97,20 +97,20 @@ authorURL: http://twitter.com/franchementli
       

      Linking other Documents

      You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.

      Example:

      -
      [This links to another document](other-document.md)
      +
      [This links to another document](other-document.md)
       

      This markdown will automatically get converted into a link to /docs/other-document.html (or the appropriately translated/versioned link) once it gets rendered.

      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.

      Linking to Images and Other Assets

      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 docs/assets and website/blog/assets, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.

      Example:

      -
      ![alt-text](/docs/assets/doc-image.png)
      +
      ![alt-text](/docs/assets/doc-image.png)
       

      Generating Table of Contents

      You can make an autogenerated list of links, which can be useful as a table of contents for API docs.

      In your markdown file, insert a line with the text <AUTOGENERATED_TABLE_OF_CONTENTS>. Write your documentation using h3 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 <AUTOGENERATED_TABLE_OF_CONTENTS>.

      Example:

      -
      ### `docusaurus.function(a, b)`
      +
      ### `docusaurus.function(a, b)`
       
       Text describing my function
       
      @@ -120,7 +120,7 @@ Text describing my function
       Text describing my function
       

      will lead to a table of contents of the functions:

      -
      - `docusaurus.function(a, b)`
      +
      - `docusaurus.function(a, b)`
       - `docdoc(file)`
       

      and each function will link to their corresponding sections in the page.

      @@ -134,20 +134,20 @@ ReactDOM.render( ```

      ...would be rendered with syntax highlighting like so:

      -
      ReactDOM.render(
      +
      ReactDOM.render(
         <h1>Hello, world!</h1>,
         document.getElementById('root')
       );
       

      Highlighting is provided by Highlight.js using the theme specified in your siteConfig.js file as part of the highlight key:

      -
      highlight: {
      +
      highlight: {
         theme: 'default'
       }
       

      You can find the full list of supported themes in the Highlight.js styles directory.

      Registering additional languages

      While Highlight.js provides support for many popular languages out of the box, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the hljs constant as part of the highlight config key. This in turn allows you to call registerLanguage:

      -
      highlight: {
      +
      highlight: {
         theme: 'default',
         hljs: function(hljs) {
           hljs.registerLanguage('galacticbasic', function(hljs) {
      diff --git a/docs/en/1.0.13/installation.html b/docs/en/1.0.13/installation.html
      index fc54fbb36f..9b50ea9fae 100644
      --- a/docs/en/1.0.13/installation.html
      +++ b/docs/en/1.0.13/installation.html
      @@ -61,7 +61,7 @@
       

      After docusaurus is installed, moving forward, you can check your current version of Docusaurus by going into the website directory and typing npm list docusaurus. You can update to the latest version of Docusaurus by typing npm update.

      Along with previously existing files and directories, your root directory will now contain a structure similar to:

      -
      root-of-repo
      +
      root-of-repo
       ├── docs-examples-from-docusaurus
       │   └── doc1.md
       │   └── doc2.md
      diff --git a/docs/en/1.0.13/installation/index.html b/docs/en/1.0.13/installation/index.html
      index fc54fbb36f..9b50ea9fae 100644
      --- a/docs/en/1.0.13/installation/index.html
      +++ b/docs/en/1.0.13/installation/index.html
      @@ -61,7 +61,7 @@
       

      After docusaurus is installed, moving forward, you can check your current version of Docusaurus by going into the website directory and typing npm list docusaurus. You can update to the latest version of Docusaurus by typing npm update.

      Along with previously existing files and directories, your root directory will now contain a structure similar to:

      -
      root-of-repo
      +
      root-of-repo
       ├── docs-examples-from-docusaurus
       │   └── doc1.md
       │   └── doc2.md
      diff --git a/docs/en/1.0.13/publishing.html b/docs/en/1.0.13/publishing.html
      index e3230e7c09..3ffbae2aff 100644
      --- a/docs/en/1.0.13/publishing.html
      +++ b/docs/en/1.0.13/publishing.html
      @@ -102,7 +102,7 @@
       
       

      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:

      To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate.

      -
      GIT_USER=<GIT_USER> \
      +
      GIT_USER=<GIT_USER> \
         CURRENT_BRANCH=master \
         USE_SSH=true \
         yarn run publish-gh-pages # or `npm run publish-gh-pages`
      @@ -126,7 +126,7 @@
       
    • Create a .circleci folder and create a config.yml under that folder.
    • Copy the text below into .circleci/config.yml.
    • -
      # If you only one circle to run on direct commits to master, you can uncomment this out
      +
      # If you only one circle to run on direct commits to master, you can uncomment this out
       # and uncomment the filters: *filter-only-master down below too
       #
       # aliases:
      @@ -173,7 +173,7 @@
       
       

      Tips & Tricks

      When initially deploying to a gh-pages branch using Circle CI, you may notice that some jobs triggered by commits to the gh-pages 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:

      -
      # Circle CI 2.0 Config File
      +
      # Circle CI 2.0 Config File
       # This config file will prevent tests from being run on the gh-pages branch.
       version: 2
       jobs:
      diff --git a/docs/en/1.0.13/publishing/index.html b/docs/en/1.0.13/publishing/index.html
      index e3230e7c09..3ffbae2aff 100644
      --- a/docs/en/1.0.13/publishing/index.html
      +++ b/docs/en/1.0.13/publishing/index.html
      @@ -102,7 +102,7 @@
       
       

      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:

      To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate.

      -
      GIT_USER=<GIT_USER> \
      +
      GIT_USER=<GIT_USER> \
         CURRENT_BRANCH=master \
         USE_SSH=true \
         yarn run publish-gh-pages # or `npm run publish-gh-pages`
      @@ -126,7 +126,7 @@
       
    • Create a .circleci folder and create a config.yml under that folder.
    • Copy the text below into .circleci/config.yml.
    • -
      # If you only one circle to run on direct commits to master, you can uncomment this out
      +
      # If you only one circle to run on direct commits to master, you can uncomment this out
       # and uncomment the filters: *filter-only-master down below too
       #
       # aliases:
      @@ -173,7 +173,7 @@
       
       

      Tips & Tricks

      When initially deploying to a gh-pages branch using Circle CI, you may notice that some jobs triggered by commits to the gh-pages 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:

      -
      # Circle CI 2.0 Config File
      +
      # Circle CI 2.0 Config File
       # This config file will prevent tests from being run on the gh-pages branch.
       version: 2
       jobs:
      diff --git a/docs/en/1.0.13/search.html b/docs/en/1.0.13/search.html
      index af2fb518d3..7622483c68 100644
      --- a/docs/en/1.0.13/search.html
      +++ b/docs/en/1.0.13/search.html
      @@ -50,7 +50,7 @@
               
    Edit

    Enabling Search

    Docusaurus supports search using Algolia DocSearch. Once you have set up your site, enter your site information to have Algolia crawl your website's documentation pages. Algolia will then send you an API key and index name for your site.

    Enabling the Search Bar

    Enter your search-only API key and index name into siteConfig.js in the algolia section to enable search for your site.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       algolia: {
         apiKey: "my-search-only-api-key-1234",
    @@ -61,7 +61,7 @@
     

    Extra Search Options

    You can also specify extra search options used by Algolia by using an algoliaOptions field in algolia. 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 found here.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       algolia: {
         ...
    @@ -75,7 +75,7 @@
     

    Controlling the Location of the Search Bar

    By default, the search bar will be the rightmost element in the top navigation bar.

    If you want to change the default location, add the searchBar flag in the headerLinks field of siteConfig.js in your desired location. For example, you may want the search bar in between your internal and external links.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       headerLinks: [
         {...}
    diff --git a/docs/en/1.0.13/search/index.html b/docs/en/1.0.13/search/index.html
    index af2fb518d3..7622483c68 100644
    --- a/docs/en/1.0.13/search/index.html
    +++ b/docs/en/1.0.13/search/index.html
    @@ -50,7 +50,7 @@
             
    Edit

    Enabling Search

    Docusaurus supports search using Algolia DocSearch. Once you have set up your site, enter your site information to have Algolia crawl your website's documentation pages. Algolia will then send you an API key and index name for your site.

    Enabling the Search Bar

    Enter your search-only API key and index name into siteConfig.js in the algolia section to enable search for your site.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       algolia: {
         apiKey: "my-search-only-api-key-1234",
    @@ -61,7 +61,7 @@
     

    Extra Search Options

    You can also specify extra search options used by Algolia by using an algoliaOptions field in algolia. 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 found here.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       algolia: {
         ...
    @@ -75,7 +75,7 @@
     

    Controlling the Location of the Search Bar

    By default, the search bar will be the rightmost element in the top navigation bar.

    If you want to change the default location, add the searchBar flag in the headerLinks field of siteConfig.js in your desired location. For example, you may want the search bar in between your internal and external links.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       headerLinks: [
         {...}
    diff --git a/docs/en/1.0.13/site-config.html b/docs/en/1.0.13/site-config.html
    index c53b61c389..dacd321409 100644
    --- a/docs/en/1.0.13/site-config.html
    +++ b/docs/en/1.0.13/site-config.html
    @@ -66,7 +66,7 @@
     

    headerIcon - url for icon used in header navigation bar.

    headerLinks - Links that will be used in the header navigation bar. The label field of each object will be the link text and will also be translated for each language.

    Example Usage:

    -
    headerLinks: [
    +
    headerLinks: [
       // Links to document with id doc1 for current language/version
       { doc: "doc1", label: "Getting Started" },
       // Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language
    @@ -97,9 +97,9 @@
     

    blogSidebarCount - Control the number of blog posts that show up in the sidebar. See the adding a blog docs for more information.

    cname - The CNAME for your website. It will go into a CNAME file when your site it built.

    customDocsPath - By default, Docusaurus expects your documentation to be in a directory called docs. This directory is at the same level as the website directory (i.e., not inside the website directory). You can specify a custom path to your documentation with this field. Note that all of your documentation *.md files must still reside in a flat hierarchy. You cannot have your documents in nested directories.

    -
    customDocsPath: "docs/site"
    +
    customDocsPath: "docs/site"
     
    -
    customDocsPath: "website-docs"
    +
    customDocsPath: "website-docs"
     

    disableHeaderTitle - 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 true.

    disableTitleTagline - An option to disable showing the tagline in the title of main pages. Exclude this field to keep page titles as Title • Tagline. Set to true to make page titles just Title.

    diff --git a/docs/en/1.0.13/site-config/index.html b/docs/en/1.0.13/site-config/index.html index c53b61c389..dacd321409 100644 --- a/docs/en/1.0.13/site-config/index.html +++ b/docs/en/1.0.13/site-config/index.html @@ -66,7 +66,7 @@

    headerIcon - url for icon used in header navigation bar.

    headerLinks - Links that will be used in the header navigation bar. The label field of each object will be the link text and will also be translated for each language.

    Example Usage:

    -
    headerLinks: [
    +
    headerLinks: [
       // Links to document with id doc1 for current language/version
       { doc: "doc1", label: "Getting Started" },
       // Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language
    @@ -97,9 +97,9 @@
     

    blogSidebarCount - Control the number of blog posts that show up in the sidebar. See the adding a blog docs for more information.

    cname - The CNAME for your website. It will go into a CNAME file when your site it built.

    customDocsPath - By default, Docusaurus expects your documentation to be in a directory called docs. This directory is at the same level as the website directory (i.e., not inside the website directory). You can specify a custom path to your documentation with this field. Note that all of your documentation *.md files must still reside in a flat hierarchy. You cannot have your documents in nested directories.

    -
    customDocsPath: "docs/site"
    +
    customDocsPath: "docs/site"
     
    -
    customDocsPath: "website-docs"
    +
    customDocsPath: "website-docs"
     

    disableHeaderTitle - 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 true.

    disableTitleTagline - An option to disable showing the tagline in the title of main pages. Exclude this field to keep page titles as Title • Tagline. Set to true to make page titles just Title.

    diff --git a/docs/en/1.0.13/site-creation.html b/docs/en/1.0.13/site-creation.html index aba7876374..76dd33678f 100644 --- a/docs/en/1.0.13/site-creation.html +++ b/docs/en/1.0.13/site-creation.html @@ -51,7 +51,7 @@

    After installation and preparation, much of the work to create a basic site for your docs is already complete.

    Site Structure

    Your site structure looks like the following:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs
     └── website
     │   └── blog
    diff --git a/docs/en/1.0.13/site-creation/index.html b/docs/en/1.0.13/site-creation/index.html
    index aba7876374..76dd33678f 100644
    --- a/docs/en/1.0.13/site-creation/index.html
    +++ b/docs/en/1.0.13/site-creation/index.html
    @@ -51,7 +51,7 @@
     

    After installation and preparation, much of the work to create a basic site for your docs is already complete.

    Site Structure

    Your site structure looks like the following:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs
     └── website
     │   └── blog
    diff --git a/docs/en/1.0.13/site-preparation.html b/docs/en/1.0.13/site-preparation.html
    index 8f973cbd07..f37b4757b1 100644
    --- a/docs/en/1.0.13/site-preparation.html
    +++ b/docs/en/1.0.13/site-preparation.html
    @@ -50,7 +50,7 @@
             
    Edit

    Site Preparation

    After installing Docusaurus, 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.

    Directory Structure

    As shown after you installed Docusaurus, the initialization script created a directory structure similar to:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs-examples-from-docusaurus
     │   └── doc1.md
     │   └── doc2.md
    diff --git a/docs/en/1.0.13/site-preparation/index.html b/docs/en/1.0.13/site-preparation/index.html
    index 8f973cbd07..f37b4757b1 100644
    --- a/docs/en/1.0.13/site-preparation/index.html
    +++ b/docs/en/1.0.13/site-preparation/index.html
    @@ -50,7 +50,7 @@
             
    Edit

    Site Preparation

    After installing Docusaurus, 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.

    Directory Structure

    As shown after you installed Docusaurus, the initialization script created a directory structure similar to:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs-examples-from-docusaurus
     │   └── doc1.md
     │   └── doc2.md
    diff --git a/docs/en/1.0.13/translation.html b/docs/en/1.0.13/translation.html
    index dbb995f305..6ef6fc07d7 100644
    --- a/docs/en/1.0.13/translation.html
    +++ b/docs/en/1.0.13/translation.html
    @@ -76,7 +76,7 @@ languages.js
     

    Pages allow you to customize layout and specific content of pages like a custom index page or help page.

    Pages with text that you want translated should be placed in website/pages/en folder.

    Wrap strings you want translated in a <translate> tag, and add the following require statement to the top of the file:

    -
    ...
    +
    ...
     const translate = require("../../server/translate.js").translate;
     ...
     <h2>
    @@ -85,7 +85,7 @@ languages.js
     ...
     

    You can also include an optional description attribute to give more context to a translator about how to translate the string:

    -
    <p>
    +
    <p>
       <translate desc="flower, not verb">Rose</translate>
     <p>
     
    @@ -95,7 +95,7 @@ languages.js

    Gathering Strings to Translate

    The strings within localized Pages must be extracted and provided to Crowdin.

    Add the following script to your website/package.json file, if it does not exist already:

    -
    ...
    +
    ...
     "scripts": {
       "write-translations": "docusaurus-write-translations"
     },
    @@ -133,7 +133,7 @@ languages.js
     
     

    The example below can be automatically generated by the Docusaurus cli with the examples script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.

    Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.

    -
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
    +
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
     api_key_env: CROWDIN_DOCUSAURUS_API_KEY
     base_path: "./"
     preserve_hierarchy: true
    @@ -158,7 +158,7 @@ languages.js
     

    Setup the Crowdin Scripts

    You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in /docs as well as translatable strings in website/i18n/en.json. (These strings can be generated by running yarn write-translations.)

    You can add the following to your package.json to manually trigger Crowdin.

    -
    "scripts": {
    +
    "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.js
     

    Automated File Sync Using CircleCI

    You can automate pulling down and uploading translations for your files using the CircleCI web continuous integration service.

    First, update the circle.yml 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 circle.yml file:

    -
    machine:
    +
    machine:
       node:
         version: 6.10.3
       npm:
    @@ -219,7 +219,7 @@ languages.js
     

    If you wish to use Crowdin on your machine locally, you can install the Crowdin CLI tool and run the same commands found in the circle.yaml file. The only difference is that you must set project_identifier and api_key values in the crowdin.yaml file since you will not have Circle environment variables set up.

    Versioned Translations

    If you wish to have translation and versioning for your documentation, add the following section to the end of your crowdin.yaml file:

    -
      -
    +
      -
         source: '/website/versioned_docs/**/*.md'
         translation: '/website/translated_docs/%locale%/**/%original_file_name%'
         languages_mapping: *anchor
    diff --git a/docs/en/1.0.13/translation/index.html b/docs/en/1.0.13/translation/index.html
    index dbb995f305..6ef6fc07d7 100644
    --- a/docs/en/1.0.13/translation/index.html
    +++ b/docs/en/1.0.13/translation/index.html
    @@ -76,7 +76,7 @@ languages.js
     

    Pages allow you to customize layout and specific content of pages like a custom index page or help page.

    Pages with text that you want translated should be placed in website/pages/en folder.

    Wrap strings you want translated in a <translate> tag, and add the following require statement to the top of the file:

    -
    ...
    +
    ...
     const translate = require("../../server/translate.js").translate;
     ...
     <h2>
    @@ -85,7 +85,7 @@ languages.js
     ...
     

    You can also include an optional description attribute to give more context to a translator about how to translate the string:

    -
    <p>
    +
    <p>
       <translate desc="flower, not verb">Rose</translate>
     <p>
     
    @@ -95,7 +95,7 @@ languages.js

    Gathering Strings to Translate

    The strings within localized Pages must be extracted and provided to Crowdin.

    Add the following script to your website/package.json file, if it does not exist already:

    -
    ...
    +
    ...
     "scripts": {
       "write-translations": "docusaurus-write-translations"
     },
    @@ -133,7 +133,7 @@ languages.js
     
     

    The example below can be automatically generated by the Docusaurus cli with the examples script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.

    Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.

    -
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
    +
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
     api_key_env: CROWDIN_DOCUSAURUS_API_KEY
     base_path: "./"
     preserve_hierarchy: true
    @@ -158,7 +158,7 @@ languages.js
     

    Setup the Crowdin Scripts

    You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in /docs as well as translatable strings in website/i18n/en.json. (These strings can be generated by running yarn write-translations.)

    You can add the following to your package.json to manually trigger Crowdin.

    -
    "scripts": {
    +
    "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.js
     

    Automated File Sync Using CircleCI

    You can automate pulling down and uploading translations for your files using the CircleCI web continuous integration service.

    First, update the circle.yml 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 circle.yml file:

    -
    machine:
    +
    machine:
       node:
         version: 6.10.3
       npm:
    @@ -219,7 +219,7 @@ languages.js
     

    If you wish to use Crowdin on your machine locally, you can install the Crowdin CLI tool and run the same commands found in the circle.yaml file. The only difference is that you must set project_identifier and api_key values in the crowdin.yaml file since you will not have Circle environment variables set up.

    Versioned Translations

    If you wish to have translation and versioning for your documentation, add the following section to the end of your crowdin.yaml file:

    -
      -
    +
      -
         source: '/website/versioned_docs/**/*.md'
         translation: '/website/translated_docs/%locale%/**/%original_file_name%'
         languages_mapping: *anchor
    diff --git a/docs/en/1.0.13/versioning.html b/docs/en/1.0.13/versioning.html
    index e53424f9f2..606052d64a 100644
    --- a/docs/en/1.0.13/versioning.html
    +++ b/docs/en/1.0.13/versioning.html
    @@ -50,19 +50,19 @@
             
    Edit

    Versioning

    You can use the version script to cut a new documentation version based on the latest content in the docs folder. That specific set of documentation will then be preserved and accessible even as the documentation in the docs folder changes moving forward.

    How to Create New Versions

    Run the following script to generate a starter versions page listing all the site versions:

    -
    yarn examples versions
    +
    yarn examples versions
     

    This creates the pages/en/versions.js file.

    You can edit this file later on to customize how you display the versions.

    Add the following script to your package.json file if it doesn't already exist:

    -
    ...
    +
    ...
     "scripts": {
       "version": "docusaurus-version"
     },
     ...
     

    Run the script with a command line argument of the version you wish to create. e.g.,

    -
    yarn run version 1.0.0
    +
    yarn run version 1.0.0
     

    This will preserve all documents currently in the docs folder and make them available as documentation for version 1.0.0.

    If, for example, you ran the version script with 1.0.0 as the version number, version 1.0.0 is considered the latest release version for your project. 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.

    @@ -93,14 +93,14 @@

    For example, a document with the original id doc1 exists for the latest version, 1.0.0, and has the same content as the document with the id doc1 in the docs folder. When a new version 2.0.0 is created, the file for doc1 will not be copied into versioned_docs/version-2.0.0/. There will still be a page for docs/2.0.0/doc1.html, but it will use the file from version 1.0.0.

    Renaming Existing Versions

    To rename an existing version number to something else, first make sure the following script is in your package.json file:

    -
    ...
    +
    ...
     "scripts": {
       "rename-version": "docusaurus-rename-version"
     },
     ...
     

    Run the script with command line arguments of first, the current version name, then second, the new version name. e.g.,

    -
    yarn run rename-version 1.0.0 1.0.1
    +
    yarn run rename-version 1.0.0 1.0.1
     

    Versioning and Translations

    If you wish to use versioning and translations features, the crowdin.yaml 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 translated_docs/${language}/version-${version}/. For more information, check out the translations guide.

    diff --git a/docs/en/1.0.13/versioning/index.html b/docs/en/1.0.13/versioning/index.html index e53424f9f2..606052d64a 100644 --- a/docs/en/1.0.13/versioning/index.html +++ b/docs/en/1.0.13/versioning/index.html @@ -50,19 +50,19 @@
    Edit

    Versioning

    You can use the version script to cut a new documentation version based on the latest content in the docs folder. That specific set of documentation will then be preserved and accessible even as the documentation in the docs folder changes moving forward.

    How to Create New Versions

    Run the following script to generate a starter versions page listing all the site versions:

    -
    yarn examples versions
    +
    yarn examples versions
     

    This creates the pages/en/versions.js file.

    You can edit this file later on to customize how you display the versions.

    Add the following script to your package.json file if it doesn't already exist:

    -
    ...
    +
    ...
     "scripts": {
       "version": "docusaurus-version"
     },
     ...
     

    Run the script with a command line argument of the version you wish to create. e.g.,

    -
    yarn run version 1.0.0
    +
    yarn run version 1.0.0
     

    This will preserve all documents currently in the docs folder and make them available as documentation for version 1.0.0.

    If, for example, you ran the version script with 1.0.0 as the version number, version 1.0.0 is considered the latest release version for your project. 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.

    @@ -93,14 +93,14 @@

    For example, a document with the original id doc1 exists for the latest version, 1.0.0, and has the same content as the document with the id doc1 in the docs folder. When a new version 2.0.0 is created, the file for doc1 will not be copied into versioned_docs/version-2.0.0/. There will still be a page for docs/2.0.0/doc1.html, but it will use the file from version 1.0.0.

    Renaming Existing Versions

    To rename an existing version number to something else, first make sure the following script is in your package.json file:

    -
    ...
    +
    ...
     "scripts": {
       "rename-version": "docusaurus-rename-version"
     },
     ...
     

    Run the script with command line arguments of first, the current version name, then second, the new version name. e.g.,

    -
    yarn run rename-version 1.0.0 1.0.1
    +
    yarn run rename-version 1.0.0 1.0.1
     

    Versioning and Translations

    If you wish to use versioning and translations features, the crowdin.yaml 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 translated_docs/${language}/version-${version}/. For more information, check out the translations guide.

    diff --git a/docs/en/1.0.14/api-pages.html b/docs/en/1.0.14/api-pages.html index bdc5462462..d9ae51b496 100644 --- a/docs/en/1.0.14/api-pages.html +++ b/docs/en/1.0.14/api-pages.html @@ -59,7 +59,7 @@

    CompLibrary.MarkdownBlock

    A React component that parses markdown and renders to HTML.

    Example:

    -
    const MarkdownBlock = CompLibrary.MarkdownBlock;
    +
    const MarkdownBlock = CompLibrary.MarkdownBlock;
     
     <MarkdownBlock>
       [Markdown syntax for a link](http://www.example.com)
    @@ -79,7 +79,7 @@
     
     
     

    Example

    -
    <Container
    +
    <Container
       padding={['bottom', 'top']}
       background="light"
       className="myCustomClass">
    @@ -144,19 +144,19 @@
     

    Translating Strings

    When translations are enabled, any pages inside website/pages/en will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the languages.js file. E.g. The url for a French page of website/pages/en/help.js would be found at ${baseUrl}fr/help.html.

    When writing pages that you wish to translate, wrap any strings to be translated inside a <translate> tag. e.g.,

    -
    <p>
    +
    <p>
       <translate>I like translations</translate>
     </p>
     

    You can also provide an optional description attribute to provide context for translators. e.g,

    -
    <a href="/community">
    +
    <a href="/community">
       <translate desc="Footer link to page referring to community GitHub and Slack">
         Community
       </translate>
     </a>
     

    Add the following require statement as well:

    -
    const translate = require('../../server/translate.js').translate;
    +
    const translate = require('../../server/translate.js').translate;
     

    Note that this path is valid for files inside pages/en and should be adjusted accordingly if files are in different locations, as discussed above.

    Using Static Assets

    diff --git a/docs/en/1.0.14/api-pages/index.html b/docs/en/1.0.14/api-pages/index.html index bdc5462462..d9ae51b496 100644 --- a/docs/en/1.0.14/api-pages/index.html +++ b/docs/en/1.0.14/api-pages/index.html @@ -59,7 +59,7 @@

    CompLibrary.MarkdownBlock

    A React component that parses markdown and renders to HTML.

    Example:

    -
    const MarkdownBlock = CompLibrary.MarkdownBlock;
    +
    const MarkdownBlock = CompLibrary.MarkdownBlock;
     
     <MarkdownBlock>
       [Markdown syntax for a link](http://www.example.com)
    @@ -79,7 +79,7 @@
     
     
     

    Example

    -
    <Container
    +
    <Container
       padding={['bottom', 'top']}
       background="light"
       className="myCustomClass">
    @@ -144,19 +144,19 @@
     

    Translating Strings

    When translations are enabled, any pages inside website/pages/en will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the languages.js file. E.g. The url for a French page of website/pages/en/help.js would be found at ${baseUrl}fr/help.html.

    When writing pages that you wish to translate, wrap any strings to be translated inside a <translate> tag. e.g.,

    -
    <p>
    +
    <p>
       <translate>I like translations</translate>
     </p>
     

    You can also provide an optional description attribute to provide context for translators. e.g,

    -
    <a href="/community">
    +
    <a href="/community">
       <translate desc="Footer link to page referring to community GitHub and Slack">
         Community
       </translate>
     </a>
     

    Add the following require statement as well:

    -
    const translate = require('../../server/translate.js').translate;
    +
    const translate = require('../../server/translate.js').translate;
     

    Note that this path is valid for files inside pages/en and should be adjusted accordingly if files are in different locations, as discussed above.

    Using Static Assets

    diff --git a/docs/en/1.0.14/blog.html b/docs/en/1.0.14/blog.html index e16003d473..8808a1343a 100644 --- a/docs/en/1.0.14/blog.html +++ b/docs/en/1.0.14/blog.html @@ -121,7 +121,7 @@

    Now, when Docusaurus generates or builds your site, it will copy the file from static/index.html 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 /blog.

    You can use this template:

    -
    <html lang="en-US">
    +
    <html lang="en-US">
         <head>
             <meta charset="UTF-8">
             <meta http-equiv="refresh" content="0; url=blog/">
    diff --git a/docs/en/1.0.14/blog/index.html b/docs/en/1.0.14/blog/index.html
    index e16003d473..8808a1343a 100644
    --- a/docs/en/1.0.14/blog/index.html
    +++ b/docs/en/1.0.14/blog/index.html
    @@ -121,7 +121,7 @@
     

    Now, when Docusaurus generates or builds your site, it will copy the file from static/index.html 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 /blog.

    You can use this template:

    -
    <html lang="en-US">
    +
    <html lang="en-US">
         <head>
             <meta charset="UTF-8">
             <meta http-equiv="refresh" content="0; url=blog/">
    diff --git a/docs/en/1.0.14/commands.html b/docs/en/1.0.14/commands.html
    index 97eecdcf36..3af4d168f0 100644
    --- a/docs/en/1.0.14/commands.html
    +++ b/docs/en/1.0.14/commands.html
    @@ -100,7 +100,7 @@
     
  • USE_SSH: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.
  • e.g.,

    -
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
    +
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
     

    The following environment variables are set by CircleCI during the build process.

      diff --git a/docs/en/1.0.14/commands/index.html b/docs/en/1.0.14/commands/index.html index 97eecdcf36..3af4d168f0 100644 --- a/docs/en/1.0.14/commands/index.html +++ b/docs/en/1.0.14/commands/index.html @@ -100,7 +100,7 @@
    • USE_SSH: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.

    e.g.,

    -
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
    +
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
     

    The following environment variables are set by CircleCI during the build process.

      diff --git a/docs/en/1.0.14/custom-pages.html b/docs/en/1.0.14/custom-pages.html index a6e8a12678..72f05ee042 100644 --- a/docs/en/1.0.14/custom-pages.html +++ b/docs/en/1.0.14/custom-pages.html @@ -53,7 +53,7 @@

      You can start your local server and go to http://localhost:3000 to see what the example home page looks like. From there, edit the website/pages/en/index.js file and its various components to use the images and text you want for your project.

      Adding Other Custom Pages

      Docusaurus provides some simple example pages in the website/pages/en directory, including index.js, users.js, and help.js. These are good examples to showcase how to create a custom page for Docusaurus.

      -
      root-of-repo
      +
      root-of-repo
       ├── docs
       └── website
       │   └── blog
      @@ -85,7 +85,7 @@
       

      Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.

      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.

      If you do not want a footer for your site, change the render function of core/Footer.js to return null. e.g.,

      -
      const React = require("react");
      +
      const React = require("react");
       
       class Footer extends React.Component {
         render() {
      diff --git a/docs/en/1.0.14/custom-pages/index.html b/docs/en/1.0.14/custom-pages/index.html
      index a6e8a12678..72f05ee042 100644
      --- a/docs/en/1.0.14/custom-pages/index.html
      +++ b/docs/en/1.0.14/custom-pages/index.html
      @@ -53,7 +53,7 @@
       

      You can start your local server and go to http://localhost:3000 to see what the example home page looks like. From there, edit the website/pages/en/index.js file and its various components to use the images and text you want for your project.

      Adding Other Custom Pages

      Docusaurus provides some simple example pages in the website/pages/en directory, including index.js, users.js, and help.js. These are good examples to showcase how to create a custom page for Docusaurus.

      -
      root-of-repo
      +
      root-of-repo
       ├── docs
       └── website
       │   └── blog
      @@ -85,7 +85,7 @@
       

      Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.

      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.

      If you do not want a footer for your site, change the render function of core/Footer.js to return null. e.g.,

      -
      const React = require("react");
      +
      const React = require("react");
       
       class Footer extends React.Component {
         render() {
      diff --git a/docs/en/1.0.14/doc-markdown.html b/docs/en/1.0.14/doc-markdown.html
      index 62118985b4..765339253a 100644
      --- a/docs/en/1.0.14/doc-markdown.html
      +++ b/docs/en/1.0.14/doc-markdown.html
      @@ -55,7 +55,7 @@
       

      hide_title: Whether to hide the title at the top of the doc.

      sidebar_label: The text shown in the document sidebar for this document. If this field is not present, the document's sidebar_label will default to its title.

      For example:

      -
      ---
      +
      ---
       id: doc1
       title: My Document
       sidebar_label: Document
      @@ -63,7 +63,7 @@ title: My Document
       

      Versioned documents have their ids altered to include the version number when they get copied. The new id is version-${version}-${id} where ${version} is the version number of that document and ${id} is the original id. Additionally, versioned documents get an added original_id field with the original document id.

      For example:

      -
      ---
      +
      ---
       id: version-1.0.0-doc1
       title: My Document
       sidebar_label: Document
      @@ -72,7 +72,7 @@ sidebar_label: Document
       

      custom_edit_url: The url for editing this document. If this field is not present, the document's edit url will fallback to editUrl from optional fields of siteConfig.js. See siteConfig.js docs for more information.

      For example:

      -
      ---
      +
      ---
       id: doc-markdown
       title: Markdown Features
       custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
      @@ -85,7 +85,7 @@ title: Markdown Features
       

      authorURL: 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.

      authorFBID: 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.

      For example:

      -
      ---
      +
      ---
       title: My First Blog Post
       author: Frank Li
       authorURL: http://twitter.com/franchementli
      @@ -97,20 +97,20 @@ authorURL: http://twitter.com/franchementli
       

      Linking other Documents

      You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.

      Example:

      -
      [This links to another document](other-document.md)
      +
      [This links to another document](other-document.md)
       

      This markdown will automatically get converted into a link to /docs/other-document.html (or the appropriately translated/versioned link) once it gets rendered.

      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.

      Linking to Images and Other Assets

      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 docs/assets and website/blog/assets, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.

      Example:

      -
      ![alt-text](/docs/assets/doc-image.png)
      +
      ![alt-text](/docs/assets/doc-image.png)
       

      Generating Table of Contents

      You can make an autogenerated list of links, which can be useful as a table of contents for API docs.

      In your markdown file, insert a line with the text <AUTOGENERATED_TABLE_OF_CONTENTS>. Write your documentation using h3 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 <AUTOGENERATED_TABLE_OF_CONTENTS>.

      Example:

      -
      ### `docusaurus.function(a, b)`
      +
      ### `docusaurus.function(a, b)`
       
       Text describing my function
       
      @@ -120,7 +120,7 @@ Text describing my function
       Text describing my function
       

      will lead to a table of contents of the functions:

      -
      - `docusaurus.function(a, b)`
      +
      - `docusaurus.function(a, b)`
       - `docdoc(file)`
       

      and each function will link to their corresponding sections in the page.

      @@ -134,20 +134,20 @@ ReactDOM.render( ```

      ...would be rendered with syntax highlighting like so:

      -
      ReactDOM.render(
      +
      ReactDOM.render(
         <h1>Hello, world!</h1>,
         document.getElementById('root')
       );
       

      Highlighting is provided by Highlight.js using the theme specified in your siteConfig.js file as part of the highlight key:

      -
      highlight: {
      +
      highlight: {
         theme: 'default'
       }
       

      You can find the full list of supported themes in the Highlight.js styles directory.

      Registering additional languages

      While Highlight.js provides support for many popular languages out of the box, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the hljs constant as part of the highlight config key. This in turn allows you to call registerLanguage:

      -
      highlight: {
      +
      highlight: {
         theme: 'default',
         hljs: function(hljs) {
           hljs.registerLanguage('galacticbasic', function(hljs) {
      diff --git a/docs/en/1.0.14/doc-markdown/index.html b/docs/en/1.0.14/doc-markdown/index.html
      index 62118985b4..765339253a 100644
      --- a/docs/en/1.0.14/doc-markdown/index.html
      +++ b/docs/en/1.0.14/doc-markdown/index.html
      @@ -55,7 +55,7 @@
       

      hide_title: Whether to hide the title at the top of the doc.

      sidebar_label: The text shown in the document sidebar for this document. If this field is not present, the document's sidebar_label will default to its title.

      For example:

      -
      ---
      +
      ---
       id: doc1
       title: My Document
       sidebar_label: Document
      @@ -63,7 +63,7 @@ title: My Document
       

      Versioned documents have their ids altered to include the version number when they get copied. The new id is version-${version}-${id} where ${version} is the version number of that document and ${id} is the original id. Additionally, versioned documents get an added original_id field with the original document id.

      For example:

      -
      ---
      +
      ---
       id: version-1.0.0-doc1
       title: My Document
       sidebar_label: Document
      @@ -72,7 +72,7 @@ sidebar_label: Document
       

      custom_edit_url: The url for editing this document. If this field is not present, the document's edit url will fallback to editUrl from optional fields of siteConfig.js. See siteConfig.js docs for more information.

      For example:

      -
      ---
      +
      ---
       id: doc-markdown
       title: Markdown Features
       custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
      @@ -85,7 +85,7 @@ title: Markdown Features
       

      authorURL: 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.

      authorFBID: 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.

      For example:

      -
      ---
      +
      ---
       title: My First Blog Post
       author: Frank Li
       authorURL: http://twitter.com/franchementli
      @@ -97,20 +97,20 @@ authorURL: http://twitter.com/franchementli
       

      Linking other Documents

      You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.

      Example:

      -
      [This links to another document](other-document.md)
      +
      [This links to another document](other-document.md)
       

      This markdown will automatically get converted into a link to /docs/other-document.html (or the appropriately translated/versioned link) once it gets rendered.

      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.

      Linking to Images and Other Assets

      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 docs/assets and website/blog/assets, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.

      Example:

      -
      ![alt-text](/docs/assets/doc-image.png)
      +
      ![alt-text](/docs/assets/doc-image.png)
       

      Generating Table of Contents

      You can make an autogenerated list of links, which can be useful as a table of contents for API docs.

      In your markdown file, insert a line with the text <AUTOGENERATED_TABLE_OF_CONTENTS>. Write your documentation using h3 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 <AUTOGENERATED_TABLE_OF_CONTENTS>.

      Example:

      -
      ### `docusaurus.function(a, b)`
      +
      ### `docusaurus.function(a, b)`
       
       Text describing my function
       
      @@ -120,7 +120,7 @@ Text describing my function
       Text describing my function
       

      will lead to a table of contents of the functions:

      -
      - `docusaurus.function(a, b)`
      +
      - `docusaurus.function(a, b)`
       - `docdoc(file)`
       

      and each function will link to their corresponding sections in the page.

      @@ -134,20 +134,20 @@ ReactDOM.render( ```

      ...would be rendered with syntax highlighting like so:

      -
      ReactDOM.render(
      +
      ReactDOM.render(
         <h1>Hello, world!</h1>,
         document.getElementById('root')
       );
       

      Highlighting is provided by Highlight.js using the theme specified in your siteConfig.js file as part of the highlight key:

      -
      highlight: {
      +
      highlight: {
         theme: 'default'
       }
       

      You can find the full list of supported themes in the Highlight.js styles directory.

      Registering additional languages

      While Highlight.js provides support for many popular languages out of the box, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the hljs constant as part of the highlight config key. This in turn allows you to call registerLanguage:

      -
      highlight: {
      +
      highlight: {
         theme: 'default',
         hljs: function(hljs) {
           hljs.registerLanguage('galacticbasic', function(hljs) {
      diff --git a/docs/en/1.0.14/installation.html b/docs/en/1.0.14/installation.html
      index 280cd39528..bd9975735e 100644
      --- a/docs/en/1.0.14/installation.html
      +++ b/docs/en/1.0.14/installation.html
      @@ -64,7 +64,7 @@
       
       

      Verifying Installation

      Along with previously existing files and directories, your root directory will now contain a structure similar to:

      -
      root-of-repo
      +
      root-of-repo
       ├── docs-examples-from-docusaurus
       │   └── doc1.md
       │   └── doc2.md
      diff --git a/docs/en/1.0.14/installation/index.html b/docs/en/1.0.14/installation/index.html
      index 280cd39528..bd9975735e 100644
      --- a/docs/en/1.0.14/installation/index.html
      +++ b/docs/en/1.0.14/installation/index.html
      @@ -64,7 +64,7 @@
       
       

      Verifying Installation

      Along with previously existing files and directories, your root directory will now contain a structure similar to:

      -
      root-of-repo
      +
      root-of-repo
       ├── docs-examples-from-docusaurus
       │   └── doc1.md
       │   └── doc2.md
      diff --git a/docs/en/1.0.14/publishing.html b/docs/en/1.0.14/publishing.html
      index 354693138c..46557d8298 100644
      --- a/docs/en/1.0.14/publishing.html
      +++ b/docs/en/1.0.14/publishing.html
      @@ -107,7 +107,7 @@
       
       

      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:

      To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate.

      -
      GIT_USER=<GIT_USER> \
      +
      GIT_USER=<GIT_USER> \
         CURRENT_BRANCH=master \
         USE_SSH=true \
         yarn run publish-gh-pages # or `npm run publish-gh-pages`
      @@ -131,7 +131,7 @@
       
    • Create a .circleci folder and create a config.yml under that folder.
    • Copy the text below into .circleci/config.yml.
    • -
      # If you only one circle to run on direct commits to master, you can uncomment this out
      +
      # If you only one circle to run on direct commits to master, you can uncomment this out
       # and uncomment the filters: *filter-only-master down below too
       #
       # aliases:
      @@ -178,7 +178,7 @@
       
       

      Tips & Tricks

      When initially deploying to a gh-pages branch using Circle CI, you may notice that some jobs triggered by commits to the gh-pages 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:

      -
      # Circle CI 2.0 Config File
      +
      # Circle CI 2.0 Config File
       # This config file will prevent tests from being run on the gh-pages branch.
       version: 2
       jobs:
      diff --git a/docs/en/1.0.14/publishing/index.html b/docs/en/1.0.14/publishing/index.html
      index 354693138c..46557d8298 100644
      --- a/docs/en/1.0.14/publishing/index.html
      +++ b/docs/en/1.0.14/publishing/index.html
      @@ -107,7 +107,7 @@
       
       

      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:

      To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate.

      -
      GIT_USER=<GIT_USER> \
      +
      GIT_USER=<GIT_USER> \
         CURRENT_BRANCH=master \
         USE_SSH=true \
         yarn run publish-gh-pages # or `npm run publish-gh-pages`
      @@ -131,7 +131,7 @@
       
    • Create a .circleci folder and create a config.yml under that folder.
    • Copy the text below into .circleci/config.yml.
    • -
      # If you only one circle to run on direct commits to master, you can uncomment this out
      +
      # If you only one circle to run on direct commits to master, you can uncomment this out
       # and uncomment the filters: *filter-only-master down below too
       #
       # aliases:
      @@ -178,7 +178,7 @@
       
       

      Tips & Tricks

      When initially deploying to a gh-pages branch using Circle CI, you may notice that some jobs triggered by commits to the gh-pages 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:

      -
      # Circle CI 2.0 Config File
      +
      # Circle CI 2.0 Config File
       # This config file will prevent tests from being run on the gh-pages branch.
       version: 2
       jobs:
      diff --git a/docs/en/1.0.14/search.html b/docs/en/1.0.14/search.html
      index bfb5c4e28f..0dee166cb5 100644
      --- a/docs/en/1.0.14/search.html
      +++ b/docs/en/1.0.14/search.html
      @@ -50,7 +50,7 @@
               
    Edit

    Enabling Search

    Docusaurus supports search using Algolia DocSearch. Once you have set up your site, enter your site information to have Algolia crawl your website's documentation pages. Algolia will then send you an API key and index name for your site.

    Enabling the Search Bar

    Enter your search-only API key and index name into siteConfig.js in the algolia section to enable search for your site.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       algolia: {
         apiKey: "my-search-only-api-key-1234",
    @@ -61,7 +61,7 @@
     

    Extra Search Options

    You can also specify extra search options used by Algolia by using an algoliaOptions field in algolia. 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 found here.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       algolia: {
         ...
    @@ -75,7 +75,7 @@
     

    Controlling the Location of the Search Bar

    By default, the search bar will be the rightmost element in the top navigation bar.

    If you want to change the default location, add the searchBar flag in the headerLinks field of siteConfig.js in your desired location. For example, you may want the search bar in between your internal and external links.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       headerLinks: [
         {...}
    diff --git a/docs/en/1.0.14/search/index.html b/docs/en/1.0.14/search/index.html
    index bfb5c4e28f..0dee166cb5 100644
    --- a/docs/en/1.0.14/search/index.html
    +++ b/docs/en/1.0.14/search/index.html
    @@ -50,7 +50,7 @@
             
    Edit

    Enabling Search

    Docusaurus supports search using Algolia DocSearch. Once you have set up your site, enter your site information to have Algolia crawl your website's documentation pages. Algolia will then send you an API key and index name for your site.

    Enabling the Search Bar

    Enter your search-only API key and index name into siteConfig.js in the algolia section to enable search for your site.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       algolia: {
         apiKey: "my-search-only-api-key-1234",
    @@ -61,7 +61,7 @@
     

    Extra Search Options

    You can also specify extra search options used by Algolia by using an algoliaOptions field in algolia. 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 found here.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       algolia: {
         ...
    @@ -75,7 +75,7 @@
     

    Controlling the Location of the Search Bar

    By default, the search bar will be the rightmost element in the top navigation bar.

    If you want to change the default location, add the searchBar flag in the headerLinks field of siteConfig.js in your desired location. For example, you may want the search bar in between your internal and external links.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       headerLinks: [
         {...}
    diff --git a/docs/en/1.0.14/site-config.html b/docs/en/1.0.14/site-config.html
    index 3f4ae4aa31..2edec45f1a 100644
    --- a/docs/en/1.0.14/site-config.html
    +++ b/docs/en/1.0.14/site-config.html
    @@ -66,7 +66,7 @@
     

    headerIcon - url for icon used in header navigation bar.

    headerLinks - Links that will be used in the header navigation bar. The label field of each object will be the link text and will also be translated for each language.

    Example Usage:

    -
    headerLinks: [
    +
    headerLinks: [
       // Links to document with id doc1 for current language/version
       { doc: "doc1", label: "Getting Started" },
       // Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language
    @@ -97,9 +97,9 @@
     

    blogSidebarCount - Control the number of blog posts that show up in the sidebar. See the adding a blog docs for more information.

    cname - The CNAME for your website. It will go into a CNAME file when your site it built.

    customDocsPath - By default, Docusaurus expects your documentation to be in a directory called docs. This directory is at the same level as the website directory (i.e., not inside the website directory). You can specify a custom path to your documentation with this field. Note that all of your documentation *.md files must still reside in a flat hierarchy. You cannot have your documents in nested directories.

    -
    customDocsPath: "docs/site"
    +
    customDocsPath: "docs/site"
     
    -
    customDocsPath: "website-docs"
    +
    customDocsPath: "website-docs"
     

    disableHeaderTitle - 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 true.

    disableTitleTagline - An option to disable showing the tagline in the title of main pages. Exclude this field to keep page titles as Title • Tagline. Set to true to make page titles just Title.

    diff --git a/docs/en/1.0.14/site-config/index.html b/docs/en/1.0.14/site-config/index.html index 3f4ae4aa31..2edec45f1a 100644 --- a/docs/en/1.0.14/site-config/index.html +++ b/docs/en/1.0.14/site-config/index.html @@ -66,7 +66,7 @@

    headerIcon - url for icon used in header navigation bar.

    headerLinks - Links that will be used in the header navigation bar. The label field of each object will be the link text and will also be translated for each language.

    Example Usage:

    -
    headerLinks: [
    +
    headerLinks: [
       // Links to document with id doc1 for current language/version
       { doc: "doc1", label: "Getting Started" },
       // Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language
    @@ -97,9 +97,9 @@
     

    blogSidebarCount - Control the number of blog posts that show up in the sidebar. See the adding a blog docs for more information.

    cname - The CNAME for your website. It will go into a CNAME file when your site it built.

    customDocsPath - By default, Docusaurus expects your documentation to be in a directory called docs. This directory is at the same level as the website directory (i.e., not inside the website directory). You can specify a custom path to your documentation with this field. Note that all of your documentation *.md files must still reside in a flat hierarchy. You cannot have your documents in nested directories.

    -
    customDocsPath: "docs/site"
    +
    customDocsPath: "docs/site"
     
    -
    customDocsPath: "website-docs"
    +
    customDocsPath: "website-docs"
     

    disableHeaderTitle - 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 true.

    disableTitleTagline - An option to disable showing the tagline in the title of main pages. Exclude this field to keep page titles as Title • Tagline. Set to true to make page titles just Title.

    diff --git a/docs/en/1.0.14/site-creation.html b/docs/en/1.0.14/site-creation.html index b351971bb5..4f53d478ac 100644 --- a/docs/en/1.0.14/site-creation.html +++ b/docs/en/1.0.14/site-creation.html @@ -51,7 +51,7 @@

    After installation and preparation, much of the work to create a basic site for your docs is already complete.

    Site Structure

    Your site structure looks like the following:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs
     └── website
     │   └── blog
    @@ -104,7 +104,7 @@ yarn run start # custom static index.html page in the website/static folder with the following contents:
     
    -
    <!DOCTYPE HTML>
    +
    <!DOCTYPE HTML>
     <html lang="en-US">
         <head>
             <meta charset="UTF-8">
    diff --git a/docs/en/1.0.14/site-creation/index.html b/docs/en/1.0.14/site-creation/index.html
    index b351971bb5..4f53d478ac 100644
    --- a/docs/en/1.0.14/site-creation/index.html
    +++ b/docs/en/1.0.14/site-creation/index.html
    @@ -51,7 +51,7 @@
     

    After installation and preparation, much of the work to create a basic site for your docs is already complete.

    Site Structure

    Your site structure looks like the following:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs
     └── website
     │   └── blog
    @@ -104,7 +104,7 @@ yarn run start # custom static index.html page in the website/static folder with the following contents:
     
    -
    <!DOCTYPE HTML>
    +
    <!DOCTYPE HTML>
     <html lang="en-US">
         <head>
             <meta charset="UTF-8">
    diff --git a/docs/en/1.0.14/site-preparation.html b/docs/en/1.0.14/site-preparation.html
    index fd833d50ae..b9c950309d 100644
    --- a/docs/en/1.0.14/site-preparation.html
    +++ b/docs/en/1.0.14/site-preparation.html
    @@ -50,7 +50,7 @@
             
    Edit

    Site Preparation

    After installing Docusaurus, 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.

    Directory Structure

    As shown after you installed Docusaurus, the initialization script created a directory structure similar to:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs-examples-from-docusaurus
     │   └── doc1.md
     │   └── doc2.md
    diff --git a/docs/en/1.0.14/site-preparation/index.html b/docs/en/1.0.14/site-preparation/index.html
    index fd833d50ae..b9c950309d 100644
    --- a/docs/en/1.0.14/site-preparation/index.html
    +++ b/docs/en/1.0.14/site-preparation/index.html
    @@ -50,7 +50,7 @@
             
    Edit

    Site Preparation

    After installing Docusaurus, 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.

    Directory Structure

    As shown after you installed Docusaurus, the initialization script created a directory structure similar to:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs-examples-from-docusaurus
     │   └── doc1.md
     │   └── doc2.md
    diff --git a/docs/en/1.0.14/translation.html b/docs/en/1.0.14/translation.html
    index 1dbe4fc008..38edaab420 100644
    --- a/docs/en/1.0.14/translation.html
    +++ b/docs/en/1.0.14/translation.html
    @@ -76,7 +76,7 @@ languages.js
     

    Pages allow you to customize layout and specific content of pages like a custom index page or help page.

    Pages with text that you want translated should be placed in website/pages/en folder.

    Wrap strings you want translated in a <translate> tag, and add the following require statement to the top of the file:

    -
    ...
    +
    ...
     const translate = require("../../server/translate.js").translate;
     ...
     <h2>
    @@ -85,7 +85,7 @@ languages.js
     ...
     

    You can also include an optional description attribute to give more context to a translator about how to translate the string:

    -
    <p>
    +
    <p>
       <translate desc="flower, not verb">Rose</translate>
     <p>
     
    @@ -95,7 +95,7 @@ languages.js

    Gathering Strings to Translate

    The strings within localized Pages must be extracted and provided to Crowdin.

    Add the following script to your website/package.json file, if it does not exist already:

    -
    ...
    +
    ...
     "scripts": {
       "write-translations": "docusaurus-write-translations"
     },
    @@ -133,7 +133,7 @@ languages.js
     
     

    The example below can be automatically generated by the Docusaurus cli with the examples script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.

    Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.

    -
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
    +
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
     api_key_env: CROWDIN_DOCUSAURUS_API_KEY
     base_path: "./"
     preserve_hierarchy: true
    @@ -158,7 +158,7 @@ languages.js
     

    Setup the Crowdin Scripts

    You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in /docs as well as translatable strings in website/i18n/en.json. (These strings can be generated by running yarn write-translations.)

    You can add the following to your package.json to manually trigger Crowdin.

    -
    "scripts": {
    +
    "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.js
     

    Automated File Sync Using CircleCI

    You can automate pulling down and uploading translations for your files using the CircleCI web continuous integration service.

    First, update the circle.yml 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 circle.yml file:

    -
    machine:
    +
    machine:
       node:
         version: 6.10.3
       npm:
    @@ -219,7 +219,7 @@ languages.js
     

    If you wish to use Crowdin on your machine locally, you can install the Crowdin CLI tool and run the same commands found in the circle.yaml file. The only difference is that you must set project_identifier and api_key values in the crowdin.yaml file since you will not have Circle environment variables set up.

    Versioned Translations

    If you wish to have translation and versioning for your documentation, add the following section to the end of your crowdin.yaml file:

    -
      -
    +
      -
         source: '/website/versioned_docs/**/*.md'
         translation: '/website/translated_docs/%locale%/**/%original_file_name%'
         languages_mapping: *anchor
    diff --git a/docs/en/1.0.14/translation/index.html b/docs/en/1.0.14/translation/index.html
    index 1dbe4fc008..38edaab420 100644
    --- a/docs/en/1.0.14/translation/index.html
    +++ b/docs/en/1.0.14/translation/index.html
    @@ -76,7 +76,7 @@ languages.js
     

    Pages allow you to customize layout and specific content of pages like a custom index page or help page.

    Pages with text that you want translated should be placed in website/pages/en folder.

    Wrap strings you want translated in a <translate> tag, and add the following require statement to the top of the file:

    -
    ...
    +
    ...
     const translate = require("../../server/translate.js").translate;
     ...
     <h2>
    @@ -85,7 +85,7 @@ languages.js
     ...
     

    You can also include an optional description attribute to give more context to a translator about how to translate the string:

    -
    <p>
    +
    <p>
       <translate desc="flower, not verb">Rose</translate>
     <p>
     
    @@ -95,7 +95,7 @@ languages.js

    Gathering Strings to Translate

    The strings within localized Pages must be extracted and provided to Crowdin.

    Add the following script to your website/package.json file, if it does not exist already:

    -
    ...
    +
    ...
     "scripts": {
       "write-translations": "docusaurus-write-translations"
     },
    @@ -133,7 +133,7 @@ languages.js
     
     

    The example below can be automatically generated by the Docusaurus cli with the examples script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.

    Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.

    -
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
    +
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
     api_key_env: CROWDIN_DOCUSAURUS_API_KEY
     base_path: "./"
     preserve_hierarchy: true
    @@ -158,7 +158,7 @@ languages.js
     

    Setup the Crowdin Scripts

    You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in /docs as well as translatable strings in website/i18n/en.json. (These strings can be generated by running yarn write-translations.)

    You can add the following to your package.json to manually trigger Crowdin.

    -
    "scripts": {
    +
    "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.js
     

    Automated File Sync Using CircleCI

    You can automate pulling down and uploading translations for your files using the CircleCI web continuous integration service.

    First, update the circle.yml 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 circle.yml file:

    -
    machine:
    +
    machine:
       node:
         version: 6.10.3
       npm:
    @@ -219,7 +219,7 @@ languages.js
     

    If you wish to use Crowdin on your machine locally, you can install the Crowdin CLI tool and run the same commands found in the circle.yaml file. The only difference is that you must set project_identifier and api_key values in the crowdin.yaml file since you will not have Circle environment variables set up.

    Versioned Translations

    If you wish to have translation and versioning for your documentation, add the following section to the end of your crowdin.yaml file:

    -
      -
    +
      -
         source: '/website/versioned_docs/**/*.md'
         translation: '/website/translated_docs/%locale%/**/%original_file_name%'
         languages_mapping: *anchor
    diff --git a/docs/en/1.0.14/versioning.html b/docs/en/1.0.14/versioning.html
    index d1d4dc041b..e463b6a184 100644
    --- a/docs/en/1.0.14/versioning.html
    +++ b/docs/en/1.0.14/versioning.html
    @@ -50,19 +50,19 @@
             
    Edit

    Versioning

    You can use the version script to cut a new documentation version based on the latest content in the docs folder. That specific set of documentation will then be preserved and accessible even as the documentation in the docs folder changes moving forward.

    How to Create New Versions

    Run the following script to generate a starter versions page listing all the site versions:

    -
    yarn examples versions
    +
    yarn examples versions
     

    This creates the pages/en/versions.js file.

    You can edit this file later on to customize how you display the versions.

    Add the following script to your package.json file if it doesn't already exist:

    -
    ...
    +
    ...
     "scripts": {
       "version": "docusaurus-version"
     },
     ...
     

    Run the script with a command line argument of the version you wish to create. e.g.,

    -
    yarn run version 1.0.0
    +
    yarn run version 1.0.0
     

    This will preserve all documents currently in the docs folder and make them available as documentation for version 1.0.0.

    If, for example, you ran the version script with 1.0.0 as the version number, version 1.0.0 is considered the latest release version for your project. 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.

    @@ -93,14 +93,14 @@

    For example, a document with the original id doc1 exists for the latest version, 1.0.0, and has the same content as the document with the id doc1 in the docs folder. When a new version 2.0.0 is created, the file for doc1 will not be copied into versioned_docs/version-2.0.0/. There will still be a page for docs/2.0.0/doc1.html, but it will use the file from version 1.0.0.

    Renaming Existing Versions

    To rename an existing version number to something else, first make sure the following script is in your package.json file:

    -
    ...
    +
    ...
     "scripts": {
       "rename-version": "docusaurus-rename-version"
     },
     ...
     

    Run the script with command line arguments of first, the current version name, then second, the new version name. e.g.,

    -
    yarn run rename-version 1.0.0 1.0.1
    +
    yarn run rename-version 1.0.0 1.0.1
     

    Versioning and Translations

    If you wish to use versioning and translations features, the crowdin.yaml 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 translated_docs/${language}/version-${version}/. For more information, check out the translations guide.

    diff --git a/docs/en/1.0.14/versioning/index.html b/docs/en/1.0.14/versioning/index.html index d1d4dc041b..e463b6a184 100644 --- a/docs/en/1.0.14/versioning/index.html +++ b/docs/en/1.0.14/versioning/index.html @@ -50,19 +50,19 @@
    Edit

    Versioning

    You can use the version script to cut a new documentation version based on the latest content in the docs folder. That specific set of documentation will then be preserved and accessible even as the documentation in the docs folder changes moving forward.

    How to Create New Versions

    Run the following script to generate a starter versions page listing all the site versions:

    -
    yarn examples versions
    +
    yarn examples versions
     

    This creates the pages/en/versions.js file.

    You can edit this file later on to customize how you display the versions.

    Add the following script to your package.json file if it doesn't already exist:

    -
    ...
    +
    ...
     "scripts": {
       "version": "docusaurus-version"
     },
     ...
     

    Run the script with a command line argument of the version you wish to create. e.g.,

    -
    yarn run version 1.0.0
    +
    yarn run version 1.0.0
     

    This will preserve all documents currently in the docs folder and make them available as documentation for version 1.0.0.

    If, for example, you ran the version script with 1.0.0 as the version number, version 1.0.0 is considered the latest release version for your project. 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.

    @@ -93,14 +93,14 @@

    For example, a document with the original id doc1 exists for the latest version, 1.0.0, and has the same content as the document with the id doc1 in the docs folder. When a new version 2.0.0 is created, the file for doc1 will not be copied into versioned_docs/version-2.0.0/. There will still be a page for docs/2.0.0/doc1.html, but it will use the file from version 1.0.0.

    Renaming Existing Versions

    To rename an existing version number to something else, first make sure the following script is in your package.json file:

    -
    ...
    +
    ...
     "scripts": {
       "rename-version": "docusaurus-rename-version"
     },
     ...
     

    Run the script with command line arguments of first, the current version name, then second, the new version name. e.g.,

    -
    yarn run rename-version 1.0.0 1.0.1
    +
    yarn run rename-version 1.0.0 1.0.1
     

    Versioning and Translations

    If you wish to use versioning and translations features, the crowdin.yaml 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 translated_docs/${language}/version-${version}/. For more information, check out the translations guide.

    diff --git a/docs/en/1.0.15/api-pages.html b/docs/en/1.0.15/api-pages.html index 2f61e9b660..17dba360c7 100644 --- a/docs/en/1.0.15/api-pages.html +++ b/docs/en/1.0.15/api-pages.html @@ -59,7 +59,7 @@

    CompLibrary.MarkdownBlock

    A React component that parses markdown and renders to HTML.

    Example:

    -
    const MarkdownBlock = CompLibrary.MarkdownBlock;
    +
    const MarkdownBlock = CompLibrary.MarkdownBlock;
     
     <MarkdownBlock>
       [Markdown syntax for a link](http://www.example.com)
    @@ -79,7 +79,7 @@
     
     
     

    Example

    -
    <Container
    +
    <Container
       padding={['bottom', 'top']}
       background="light"
       className="myCustomClass">
    @@ -115,7 +115,7 @@
     
     
     

    Example

    -
    <GridBlock
    +
    <GridBlock
       align="center"
       layout="threeColumn"
       className="myCustomClass"
    @@ -144,19 +144,19 @@
     

    Translating Strings

    When translations are enabled, any pages inside website/pages/en will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the languages.js file. E.g. The url for a French page of website/pages/en/help.js would be found at ${baseUrl}fr/help.html.

    When writing pages that you wish to translate, wrap any strings to be translated inside a <translate> tag. e.g.,

    -
    <p>
    +
    <p>
       <translate>I like translations</translate>
     </p>
     

    You can also provide an optional description attribute to provide context for translators. e.g,

    -
    <a href="/community">
    +
    <a href="/community">
       <translate desc="Footer link to page referring to community GitHub and Slack">
         Community
       </translate>
     </a>
     

    Add the following require statement as well:

    -
    const translate = require('../../server/translate.js').translate;
    +
    const translate = require('../../server/translate.js').translate;
     

    Note that this path is valid for files inside pages/en and should be adjusted accordingly if files are in different locations, as discussed above.

    Using Static Assets

    diff --git a/docs/en/1.0.15/api-pages/index.html b/docs/en/1.0.15/api-pages/index.html index 2f61e9b660..17dba360c7 100644 --- a/docs/en/1.0.15/api-pages/index.html +++ b/docs/en/1.0.15/api-pages/index.html @@ -59,7 +59,7 @@

    CompLibrary.MarkdownBlock

    A React component that parses markdown and renders to HTML.

    Example:

    -
    const MarkdownBlock = CompLibrary.MarkdownBlock;
    +
    const MarkdownBlock = CompLibrary.MarkdownBlock;
     
     <MarkdownBlock>
       [Markdown syntax for a link](http://www.example.com)
    @@ -79,7 +79,7 @@
     
     
     

    Example

    -
    <Container
    +
    <Container
       padding={['bottom', 'top']}
       background="light"
       className="myCustomClass">
    @@ -115,7 +115,7 @@
     
     
     

    Example

    -
    <GridBlock
    +
    <GridBlock
       align="center"
       layout="threeColumn"
       className="myCustomClass"
    @@ -144,19 +144,19 @@
     

    Translating Strings

    When translations are enabled, any pages inside website/pages/en will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the languages.js file. E.g. The url for a French page of website/pages/en/help.js would be found at ${baseUrl}fr/help.html.

    When writing pages that you wish to translate, wrap any strings to be translated inside a <translate> tag. e.g.,

    -
    <p>
    +
    <p>
       <translate>I like translations</translate>
     </p>
     

    You can also provide an optional description attribute to provide context for translators. e.g,

    -
    <a href="/community">
    +
    <a href="/community">
       <translate desc="Footer link to page referring to community GitHub and Slack">
         Community
       </translate>
     </a>
     

    Add the following require statement as well:

    -
    const translate = require('../../server/translate.js').translate;
    +
    const translate = require('../../server/translate.js').translate;
     

    Note that this path is valid for files inside pages/en and should be adjusted accordingly if files are in different locations, as discussed above.

    Using Static Assets

    diff --git a/docs/en/1.0.15/blog.html b/docs/en/1.0.15/blog.html index 9141cf1141..37124d1711 100644 --- a/docs/en/1.0.15/blog.html +++ b/docs/en/1.0.15/blog.html @@ -50,7 +50,7 @@
    Edit

    Adding a Blog

    Initial Setup

    To setup your site's blog, start by creating a blog folder within your repo's website directory.

    Then, add a header link to your blog within siteConfig.js:

    -
    headerLinks: [
    +
    headerLinks: [
         ...
         { blog: true, label: 'Blog' },
         ...
    @@ -59,7 +59,7 @@
     

    Adding Posts

    To publish in the blog, create a file within the blog folder with a formatted name of YYYY-MM-DD-My-Blog-Post-Title.md. The post date is extracted from the file name.

    For example, at website/blog/2017-08-18-Introducing-Docusaurus.md:

    -
    ---
    +
    ---
     author: Frank Li
     authorURL: https://twitter.com/foobarbaz
     authorFBID: 503283835
    @@ -79,7 +79,7 @@
     
     

    Summary Truncation

    Use the <!--truncate--> marker in your blog post to represent what will be shown as the summary when viewing all blog published blog posts. Anything above <!--truncate--> will be part of the summary. For example:

    -
    ---
    +
    ---
     title: Truncation Example
     ---
     
    @@ -100,7 +100,7 @@
     

    You can configure a specific amount of blog posts to show by adding a blogSidebarCount setting to your siteConfig.js.

    The available options are an integer representing the number of posts you wish to show or a string with the value 'ALL'.

    Example:

    -
    blogSidebarCount: 'ALL'
    +
    blogSidebarCount: 'ALL'
     

    RSS Feed

    Docusaurus provides a simple RSS feed for your blog posts. Both RSS and Atom feed formats are supported. This data is automatically to your website page's HTML tag.

    @@ -121,7 +121,7 @@

    Now, when Docusaurus generates or builds your site, it will copy the file from static/index.html 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 /blog.

    You can use this template:

    -
    <!DOCTYPE HTML>
    +
    <!DOCTYPE HTML>
     <html lang="en-US">
       <head>
         <meta charset="UTF-8">
    diff --git a/docs/en/1.0.15/blog/index.html b/docs/en/1.0.15/blog/index.html
    index 9141cf1141..37124d1711 100644
    --- a/docs/en/1.0.15/blog/index.html
    +++ b/docs/en/1.0.15/blog/index.html
    @@ -50,7 +50,7 @@
             
    Edit

    Adding a Blog

    Initial Setup

    To setup your site's blog, start by creating a blog folder within your repo's website directory.

    Then, add a header link to your blog within siteConfig.js:

    -
    headerLinks: [
    +
    headerLinks: [
         ...
         { blog: true, label: 'Blog' },
         ...
    @@ -59,7 +59,7 @@
     

    Adding Posts

    To publish in the blog, create a file within the blog folder with a formatted name of YYYY-MM-DD-My-Blog-Post-Title.md. The post date is extracted from the file name.

    For example, at website/blog/2017-08-18-Introducing-Docusaurus.md:

    -
    ---
    +
    ---
     author: Frank Li
     authorURL: https://twitter.com/foobarbaz
     authorFBID: 503283835
    @@ -79,7 +79,7 @@
     
     

    Summary Truncation

    Use the <!--truncate--> marker in your blog post to represent what will be shown as the summary when viewing all blog published blog posts. Anything above <!--truncate--> will be part of the summary. For example:

    -
    ---
    +
    ---
     title: Truncation Example
     ---
     
    @@ -100,7 +100,7 @@
     

    You can configure a specific amount of blog posts to show by adding a blogSidebarCount setting to your siteConfig.js.

    The available options are an integer representing the number of posts you wish to show or a string with the value 'ALL'.

    Example:

    -
    blogSidebarCount: 'ALL'
    +
    blogSidebarCount: 'ALL'
     

    RSS Feed

    Docusaurus provides a simple RSS feed for your blog posts. Both RSS and Atom feed formats are supported. This data is automatically to your website page's HTML tag.

    @@ -121,7 +121,7 @@

    Now, when Docusaurus generates or builds your site, it will copy the file from static/index.html 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 /blog.

    You can use this template:

    -
    <!DOCTYPE HTML>
    +
    <!DOCTYPE HTML>
     <html lang="en-US">
       <head>
         <meta charset="UTF-8">
    diff --git a/docs/en/1.0.15/commands.html b/docs/en/1.0.15/commands.html
    index ad3baeacbd..ec70a80342 100644
    --- a/docs/en/1.0.15/commands.html
    +++ b/docs/en/1.0.15/commands.html
    @@ -54,18 +54,18 @@
     
     

    Running from the command line

    The scripts can be run using either Yarn or npm. If you've already gone through our Getting Started guide, you may already be familiar with the start command. It's the command that tells Docusaurus to run the docusaurus-start script which generates the site and starts up a server, and it's usually invoked like so:

    -
    yarn run start
    +
    yarn run start
     

    The same script can be invoked using npm:

    -
    npm run start
    +
    npm run start
     

    To run a particular script, just replace the start command in the examples above with the command associated with your script.

    Using arguments

    Some commands support optional arguments. For example, to start a server on port 8080, you can specify the --port argument when running start:

    -
    yarn run start --port 8080
    +
    yarn run start --port 8080
     

    If you run Docusaurus using npm, you can still use the command line arguments by inserting a -- between npm run <command> and the command arguments:

    -
    npm run start -- --port 8080
    +
    npm run start -- --port 8080
     

    Configuration

    These scripts are set up under the "scripts" key in your website/package.json file as part of the installation process. If you need help setting them up again, please refer to the Installation guide.

    @@ -100,7 +100,7 @@
  • USE_SSH: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.
  • e.g.,

    -
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
    +
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
     

    The following environment variables are set by CircleCI during the build process.

      diff --git a/docs/en/1.0.15/commands/index.html b/docs/en/1.0.15/commands/index.html index ad3baeacbd..ec70a80342 100644 --- a/docs/en/1.0.15/commands/index.html +++ b/docs/en/1.0.15/commands/index.html @@ -54,18 +54,18 @@

    Running from the command line

    The scripts can be run using either Yarn or npm. If you've already gone through our Getting Started guide, you may already be familiar with the start command. It's the command that tells Docusaurus to run the docusaurus-start script which generates the site and starts up a server, and it's usually invoked like so:

    -
    yarn run start
    +
    yarn run start
     

    The same script can be invoked using npm:

    -
    npm run start
    +
    npm run start
     

    To run a particular script, just replace the start command in the examples above with the command associated with your script.

    Using arguments

    Some commands support optional arguments. For example, to start a server on port 8080, you can specify the --port argument when running start:

    -
    yarn run start --port 8080
    +
    yarn run start --port 8080
     

    If you run Docusaurus using npm, you can still use the command line arguments by inserting a -- between npm run <command> and the command arguments:

    -
    npm run start -- --port 8080
    +
    npm run start -- --port 8080
     

    Configuration

    These scripts are set up under the "scripts" key in your website/package.json file as part of the installation process. If you need help setting them up again, please refer to the Installation guide.

    @@ -100,7 +100,7 @@
  • USE_SSH: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.
  • e.g.,

    -
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
    +
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
     

    The following environment variables are set by CircleCI during the build process.

      diff --git a/docs/en/1.0.15/custom-pages.html b/docs/en/1.0.15/custom-pages.html index e33bf50850..4ee3d50f27 100644 --- a/docs/en/1.0.15/custom-pages.html +++ b/docs/en/1.0.15/custom-pages.html @@ -53,7 +53,7 @@

      You can start your local server and go to http://localhost:3000 to see what the example home page looks like. From there, edit the website/pages/en/index.js file and its various components to use the images and text you want for your project.

      Adding Other Custom Pages

      Docusaurus provides some simple example pages in the website/pages/en directory, including index.js, users.js, and help.js. These are good examples to showcase how to create a custom page for Docusaurus.

      -
      root-of-repo
      +
      root-of-repo
       ├── docs
       ├── website
       │   ├── blog
      @@ -85,7 +85,7 @@
       

      Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.

      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.

      If you do not want a footer for your site, change the render function of core/Footer.js to return null. e.g.,

      -
      const React = require('react');
      +
      const React = require('react');
       
       class Footer extends React.Component {
         render() {
      diff --git a/docs/en/1.0.15/custom-pages/index.html b/docs/en/1.0.15/custom-pages/index.html
      index e33bf50850..4ee3d50f27 100644
      --- a/docs/en/1.0.15/custom-pages/index.html
      +++ b/docs/en/1.0.15/custom-pages/index.html
      @@ -53,7 +53,7 @@
       

      You can start your local server and go to http://localhost:3000 to see what the example home page looks like. From there, edit the website/pages/en/index.js file and its various components to use the images and text you want for your project.

      Adding Other Custom Pages

      Docusaurus provides some simple example pages in the website/pages/en directory, including index.js, users.js, and help.js. These are good examples to showcase how to create a custom page for Docusaurus.

      -
      root-of-repo
      +
      root-of-repo
       ├── docs
       ├── website
       │   ├── blog
      @@ -85,7 +85,7 @@
       

      Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.

      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.

      If you do not want a footer for your site, change the render function of core/Footer.js to return null. e.g.,

      -
      const React = require('react');
      +
      const React = require('react');
       
       class Footer extends React.Component {
         render() {
      diff --git a/docs/en/1.0.15/doc-markdown.html b/docs/en/1.0.15/doc-markdown.html
      index 8e946950be..d498f39d99 100644
      --- a/docs/en/1.0.15/doc-markdown.html
      +++ b/docs/en/1.0.15/doc-markdown.html
      @@ -55,7 +55,7 @@
       

      hide_title: Whether to hide the title at the top of the doc.

      sidebar_label: The text shown in the document sidebar for this document. If this field is not present, the document's sidebar_label will default to its title.

      For example:

      -
      ---
      +
      ---
       id: doc1
       title: My Document
       sidebar_label: Document
      @@ -63,7 +63,7 @@
       

      Versioned documents have their ids altered to include the version number when they get copied. The new id is version-${version}-${id} where ${version} is the version number of that document and ${id} is the original id. Additionally, versioned documents get an added original_id field with the original document id.

      For example:

      -
      ---
      +
      ---
       id: version-1.0.0-doc1
       title: My Document
       sidebar_label: Document
      @@ -72,7 +72,7 @@
       

      custom_edit_url: The url for editing this document. If this field is not present, the document's edit url will fallback to editUrl from optional fields of siteConfig.js. See siteConfig.js docs for more information.

      For example:

      -
      ---
      +
      ---
       id: doc-markdown
       title: Markdown Features
       custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
      @@ -85,7 +85,7 @@
       

      authorURL: 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.

      authorFBID: 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.

      For example:

      -
      ---
      +
      ---
       title: My First Blog Post
       author: Frank Li
       authorURL: http://twitter.com/franchementli
      @@ -97,20 +97,20 @@
       

      Linking other Documents

      You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.

      Example:

      -
      [This links to another document](other-document.md)
      +
      [This links to another document](other-document.md)
       

      This markdown will automatically get converted into a link to /docs/other-document.html (or the appropriately translated/versioned link) once it gets rendered.

      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.

      Linking to Images and Other Assets

      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 docs/assets and website/blog/assets, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.

      Example:

      -
      ![alt-text](/docs/assets/doc-image.png)
      +
      ![alt-text](/docs/assets/doc-image.png)
       

      Generating Table of Contents

      You can make an autogenerated list of links, which can be useful as a table of contents for API docs.

      In your markdown file, insert a line with the text <AUTOGENERATED_TABLE_OF_CONTENTS>. Write your documentation using h3 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 <AUTOGENERATED_TABLE_OF_CONTENTS>.

      Example:

      -
      ### `docusaurus.function(a, b)`
      +
      ### `docusaurus.function(a, b)`
       
       Text describing my function
       
      @@ -119,7 +119,7 @@ Text describing my function
       Text describing my function
       

      will lead to a table of contents of the functions:

      -
      - `docusaurus.function(a, b)`
      +
      - `docusaurus.function(a, b)`
       - `docdoc(file)`
       

      and each function will link to their corresponding sections in the page.

      @@ -133,13 +133,13 @@ ReactDOM.render( ```

      ...would be rendered with syntax highlighting like so:

      -
      ReactDOM.render(
      +
      ReactDOM.render(
         <h1>Hello, world!</h1>,
         document.getElementById('root')
       );
       

      Highlighting is provided by Highlight.js using the theme specified in your siteConfig.js file as part of the highlight key:

      -
      {
      +
      {
         ...
         highlight: {
           theme: 'default'
      @@ -150,7 +150,7 @@ ReactDOM.render(
       

      You can find the full list of supported themes in the Highlight.js styles directory.

      Registering additional languages

      While Highlight.js provides support for many popular languages out of the box, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the hljs constant as part of the highlight config key. This in turn allows you to call registerLanguage:

      -
      {
      +
      {
         ...
         highlight: {
           theme: 'default',
      diff --git a/docs/en/1.0.15/doc-markdown/index.html b/docs/en/1.0.15/doc-markdown/index.html
      index 8e946950be..d498f39d99 100644
      --- a/docs/en/1.0.15/doc-markdown/index.html
      +++ b/docs/en/1.0.15/doc-markdown/index.html
      @@ -55,7 +55,7 @@
       

      hide_title: Whether to hide the title at the top of the doc.

      sidebar_label: The text shown in the document sidebar for this document. If this field is not present, the document's sidebar_label will default to its title.

      For example:

      -
      ---
      +
      ---
       id: doc1
       title: My Document
       sidebar_label: Document
      @@ -63,7 +63,7 @@
       

      Versioned documents have their ids altered to include the version number when they get copied. The new id is version-${version}-${id} where ${version} is the version number of that document and ${id} is the original id. Additionally, versioned documents get an added original_id field with the original document id.

      For example:

      -
      ---
      +
      ---
       id: version-1.0.0-doc1
       title: My Document
       sidebar_label: Document
      @@ -72,7 +72,7 @@
       

      custom_edit_url: The url for editing this document. If this field is not present, the document's edit url will fallback to editUrl from optional fields of siteConfig.js. See siteConfig.js docs for more information.

      For example:

      -
      ---
      +
      ---
       id: doc-markdown
       title: Markdown Features
       custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
      @@ -85,7 +85,7 @@
       

      authorURL: 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.

      authorFBID: 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.

      For example:

      -
      ---
      +
      ---
       title: My First Blog Post
       author: Frank Li
       authorURL: http://twitter.com/franchementli
      @@ -97,20 +97,20 @@
       

      Linking other Documents

      You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.

      Example:

      -
      [This links to another document](other-document.md)
      +
      [This links to another document](other-document.md)
       

      This markdown will automatically get converted into a link to /docs/other-document.html (or the appropriately translated/versioned link) once it gets rendered.

      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.

      Linking to Images and Other Assets

      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 docs/assets and website/blog/assets, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.

      Example:

      -
      ![alt-text](/docs/assets/doc-image.png)
      +
      ![alt-text](/docs/assets/doc-image.png)
       

      Generating Table of Contents

      You can make an autogenerated list of links, which can be useful as a table of contents for API docs.

      In your markdown file, insert a line with the text <AUTOGENERATED_TABLE_OF_CONTENTS>. Write your documentation using h3 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 <AUTOGENERATED_TABLE_OF_CONTENTS>.

      Example:

      -
      ### `docusaurus.function(a, b)`
      +
      ### `docusaurus.function(a, b)`
       
       Text describing my function
       
      @@ -119,7 +119,7 @@ Text describing my function
       Text describing my function
       

      will lead to a table of contents of the functions:

      -
      - `docusaurus.function(a, b)`
      +
      - `docusaurus.function(a, b)`
       - `docdoc(file)`
       

      and each function will link to their corresponding sections in the page.

      @@ -133,13 +133,13 @@ ReactDOM.render( ```

      ...would be rendered with syntax highlighting like so:

      -
      ReactDOM.render(
      +
      ReactDOM.render(
         <h1>Hello, world!</h1>,
         document.getElementById('root')
       );
       

      Highlighting is provided by Highlight.js using the theme specified in your siteConfig.js file as part of the highlight key:

      -
      {
      +
      {
         ...
         highlight: {
           theme: 'default'
      @@ -150,7 +150,7 @@ ReactDOM.render(
       

      You can find the full list of supported themes in the Highlight.js styles directory.

      Registering additional languages

      While Highlight.js provides support for many popular languages out of the box, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the hljs constant as part of the highlight config key. This in turn allows you to call registerLanguage:

      -
      {
      +
      {
         ...
         highlight: {
           theme: 'default',
      diff --git a/docs/en/1.0.15/installation.html b/docs/en/1.0.15/installation.html
      index d6ab9f8f40..0f74f98797 100644
      --- a/docs/en/1.0.15/installation.html
      +++ b/docs/en/1.0.15/installation.html
      @@ -62,7 +62,7 @@
       

      After Docusaurus is installed, moving forward, you can check your current version of Docusaurus by going into the website directory and typing yarn outdated docusaurus or npm outdated docusaurus. You can update to the latest version of Docusaurus by typing yarn upgrade docusaurus --latest or npm update docusaurus.

      Verifying Installation

      Along with previously existing files and directories, your root directory will now contain a structure similar to:

      -
      root-of-repo
      +
      root-of-repo
       ├── docs-examples-from-docusaurus
       │   ├── doc1.md
       │   ├── doc2.md
      diff --git a/docs/en/1.0.15/installation/index.html b/docs/en/1.0.15/installation/index.html
      index d6ab9f8f40..0f74f98797 100644
      --- a/docs/en/1.0.15/installation/index.html
      +++ b/docs/en/1.0.15/installation/index.html
      @@ -62,7 +62,7 @@
       

      After Docusaurus is installed, moving forward, you can check your current version of Docusaurus by going into the website directory and typing yarn outdated docusaurus or npm outdated docusaurus. You can update to the latest version of Docusaurus by typing yarn upgrade docusaurus --latest or npm update docusaurus.

      Verifying Installation

      Along with previously existing files and directories, your root directory will now contain a structure similar to:

      -
      root-of-repo
      +
      root-of-repo
       ├── docs-examples-from-docusaurus
       │   ├── doc1.md
       │   ├── doc2.md
      diff --git a/docs/en/1.0.15/navigation.html b/docs/en/1.0.15/navigation.html
      index 2e42e91805..2f9014c034 100644
      --- a/docs/en/1.0.15/navigation.html
      +++ b/docs/en/1.0.15/navigation.html
      @@ -50,7 +50,7 @@
               
    Edit

    Navigation and Sidebars

    Referencing Site Documents

    If you want to reference another document in your docs folder (or the location you set via the optional customDocsPath path site configuration option), then you just use the name of the document you want to reference.

    For example, if you are in doc2.md and you want to reference doc1.md:

    -
    I am referencing a [document](doc1.md).
    +
    I am referencing a [document](doc1.md).
     

    Docusaurus currently does not support documents in nested folders; only in a flat folder structure. We are looking into adding support for nested folders.

    @@ -59,7 +59,7 @@

    New markdown files within docs will show up as pages on the website. Links to those documents are created first by using the id in the header of each document. If there is no id field, then the name of the file will serve as the link name.

    For example, creating an empty file such as docs/getting-started.md will enable the new page URL as /docs/getting-started.html.

    Suppose you add this to your document:

    -
    ---
    +
    ---
     id: intro
     title: Getting Started
     ---
    @@ -80,7 +80,7 @@
     

    Until you add your document to website/sidebars.json, they will only be accessible via a direct URL. The doc will not show up in any sidebar.

    Within sidebars.json, add the id you used in the document header to existing sidebar/category. In the below case, docs is the name of the sidebar and Getting Started is a category within the sidebar.

    -
    {
    +
    {
       "docs": {
         "Getting Started": [
           "getting-started"
    @@ -91,7 +91,7 @@
     }
     

    Or you can create a new category within the sidebar:

    -
    {
    +
    {
       "docs": {
         "My New Sidebar Category": [
           "getting-started"
    @@ -103,7 +103,7 @@
     

    Adding New Sidebars

    You can also put a document in a new sidebar. In the following example, we are creating an examples-sidebar sidebar within sidebars.json that has a category called My Example Category containing a document with an id of my-examples.

    -
    {
    +
    {
       "examples-sidebar": {
         "My Example Category": [
           "my-examples"
    @@ -118,7 +118,7 @@
     

    To expose sidebars, you will add clickable labels to the site navigation bar at the top of the website. You can add documents, pages and external links.

    Adding Documents

    After creating a new sidebar for the site by adding it to sidebars.json, you can expose the new sidebar from the top navigation bar by editing the headerLinks field of siteConfig.js.

    -
    {
    +
    {
       headerLinks: [
         ...
         { doc: 'my-examples', label: 'Examples' },
    @@ -130,7 +130,7 @@
     

    A label called Examples will be added to the site navigation bar and when you click on it at the top of your site, the examples-sidebar will be shown and the default document will be my-examples.

    Adding Custom Pages

    To add custom pages to the site navigation bar, entries can be added to the headerLinks of siteConfig.js. For example, if we have a page within website/pages/help.js, we can link to it by adding the following:

    -
    {
    +
    {
       headerLinks: [
         ...
         { page: 'help', label: 'Help' },
    @@ -142,7 +142,7 @@
     

    A label called Help will be added to the site navigation bar and when you click on it at the top of your site, the content from the help.js page will be shown.

    Adding External Links

    Custom links can be added to the site navigation bar with the following entry in siteConfig.js:

    -
    {
    +
    {
       headerLinks: [
         ...
         { href: 'https://github.com/facebook/Docusaurus', label: 'GitHub' },
    @@ -159,7 +159,7 @@
     

    You have limited control where the search and languages dropdown elements are shown in the site navigation bar at the top of your website.

    Search

    If search is enabled on your site, your search bar will appear to the right of your links. If you want to put the search bar between links in the header, add a search entry in the headerLinks config array:

    -
    {
    +
    {
       headerLinks: [
         { doc: 'foo', label: 'Foo' },
         { search: true },
    @@ -170,7 +170,7 @@
     

    Languages Dropdown

    If translations is enabled on your site, the language dropdown will appear to the right of your links (and to the left of the search bar, if search is enabled). If you want to put the language selection drop down between links in the header, add a languages entry in the headerLinks config array:

    -
    {
    +
    {
       headerLinks: [
         { doc: 'foo', label: 'Foo' },
         { languages: true },
    @@ -192,7 +192,7 @@
     

    These are two separate class names so you can have the active styles applied to either exact matches only or a bit more broadly for docs that belong together. If you don't want to make this distinction you can add both classes to the same CSS rule.

    Secondary On-Page Navigation

    We support secondary on-page navigation so you can more easily see the topics associated with a given document. To enable this feature, you need to add the onPageNav site configuration option to your siteConfig.js.

    -
    {
    +
    {
       onPageNav: 'separate',
       ...
     }
    diff --git a/docs/en/1.0.15/navigation/index.html b/docs/en/1.0.15/navigation/index.html
    index 2e42e91805..2f9014c034 100644
    --- a/docs/en/1.0.15/navigation/index.html
    +++ b/docs/en/1.0.15/navigation/index.html
    @@ -50,7 +50,7 @@
             
    Edit

    Navigation and Sidebars

    Referencing Site Documents

    If you want to reference another document in your docs folder (or the location you set via the optional customDocsPath path site configuration option), then you just use the name of the document you want to reference.

    For example, if you are in doc2.md and you want to reference doc1.md:

    -
    I am referencing a [document](doc1.md).
    +
    I am referencing a [document](doc1.md).
     

    Docusaurus currently does not support documents in nested folders; only in a flat folder structure. We are looking into adding support for nested folders.

    @@ -59,7 +59,7 @@

    New markdown files within docs will show up as pages on the website. Links to those documents are created first by using the id in the header of each document. If there is no id field, then the name of the file will serve as the link name.

    For example, creating an empty file such as docs/getting-started.md will enable the new page URL as /docs/getting-started.html.

    Suppose you add this to your document:

    -
    ---
    +
    ---
     id: intro
     title: Getting Started
     ---
    @@ -80,7 +80,7 @@
     

    Until you add your document to website/sidebars.json, they will only be accessible via a direct URL. The doc will not show up in any sidebar.

    Within sidebars.json, add the id you used in the document header to existing sidebar/category. In the below case, docs is the name of the sidebar and Getting Started is a category within the sidebar.

    -
    {
    +
    {
       "docs": {
         "Getting Started": [
           "getting-started"
    @@ -91,7 +91,7 @@
     }
     

    Or you can create a new category within the sidebar:

    -
    {
    +
    {
       "docs": {
         "My New Sidebar Category": [
           "getting-started"
    @@ -103,7 +103,7 @@
     

    Adding New Sidebars

    You can also put a document in a new sidebar. In the following example, we are creating an examples-sidebar sidebar within sidebars.json that has a category called My Example Category containing a document with an id of my-examples.

    -
    {
    +
    {
       "examples-sidebar": {
         "My Example Category": [
           "my-examples"
    @@ -118,7 +118,7 @@
     

    To expose sidebars, you will add clickable labels to the site navigation bar at the top of the website. You can add documents, pages and external links.

    Adding Documents

    After creating a new sidebar for the site by adding it to sidebars.json, you can expose the new sidebar from the top navigation bar by editing the headerLinks field of siteConfig.js.

    -
    {
    +
    {
       headerLinks: [
         ...
         { doc: 'my-examples', label: 'Examples' },
    @@ -130,7 +130,7 @@
     

    A label called Examples will be added to the site navigation bar and when you click on it at the top of your site, the examples-sidebar will be shown and the default document will be my-examples.

    Adding Custom Pages

    To add custom pages to the site navigation bar, entries can be added to the headerLinks of siteConfig.js. For example, if we have a page within website/pages/help.js, we can link to it by adding the following:

    -
    {
    +
    {
       headerLinks: [
         ...
         { page: 'help', label: 'Help' },
    @@ -142,7 +142,7 @@
     

    A label called Help will be added to the site navigation bar and when you click on it at the top of your site, the content from the help.js page will be shown.

    Adding External Links

    Custom links can be added to the site navigation bar with the following entry in siteConfig.js:

    -
    {
    +
    {
       headerLinks: [
         ...
         { href: 'https://github.com/facebook/Docusaurus', label: 'GitHub' },
    @@ -159,7 +159,7 @@
     

    You have limited control where the search and languages dropdown elements are shown in the site navigation bar at the top of your website.

    Search

    If search is enabled on your site, your search bar will appear to the right of your links. If you want to put the search bar between links in the header, add a search entry in the headerLinks config array:

    -
    {
    +
    {
       headerLinks: [
         { doc: 'foo', label: 'Foo' },
         { search: true },
    @@ -170,7 +170,7 @@
     

    Languages Dropdown

    If translations is enabled on your site, the language dropdown will appear to the right of your links (and to the left of the search bar, if search is enabled). If you want to put the language selection drop down between links in the header, add a languages entry in the headerLinks config array:

    -
    {
    +
    {
       headerLinks: [
         { doc: 'foo', label: 'Foo' },
         { languages: true },
    @@ -192,7 +192,7 @@
     

    These are two separate class names so you can have the active styles applied to either exact matches only or a bit more broadly for docs that belong together. If you don't want to make this distinction you can add both classes to the same CSS rule.

    Secondary On-Page Navigation

    We support secondary on-page navigation so you can more easily see the topics associated with a given document. To enable this feature, you need to add the onPageNav site configuration option to your siteConfig.js.

    -
    {
    +
    {
       onPageNav: 'separate',
       ...
     }
    diff --git a/docs/en/1.0.15/publishing.html b/docs/en/1.0.15/publishing.html
    index 8b0fffdf42..56a6c93a56 100644
    --- a/docs/en/1.0.15/publishing.html
    +++ b/docs/en/1.0.15/publishing.html
    @@ -50,7 +50,7 @@
             
    Edit

    Publishing your site

    You should now have a site up and running locally. Once you have customized it to your liking, it's time to publish it. Docusaurus generates a static HTML website that is ready to be served by your favorite web server or online hosting solution.

    Building Static HTML Pages

    To create a static build of your website, run the following script from the website directory:

    -
    yarn run build # or `npm run build`
    +
    yarn run build # or `npm run build`
     

    This will generate a build folder inside the website directory containing the .html files from all of your docs and other pages included in pages.

    Hosting Static HTML Pages

    @@ -110,7 +110,7 @@

    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:

    To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate. If you run into issues related to SSH keys, visit Github's authentication documentation.

    -
    GIT_USER=<GIT_USER> \
    +
    GIT_USER=<GIT_USER> \
       CURRENT_BRANCH=master \
       USE_SSH=true \
       yarn run publish-gh-pages # or `npm run publish-gh-pages`
    @@ -134,7 +134,7 @@
     
  • Create a .circleci folder and create a config.yml under that folder.
  • Copy the text below into .circleci/config.yml.
  • -
    # If you only one circle to run on direct commits to master, you can uncomment this out
    +
    # If you only one circle to run on direct commits to master, you can uncomment this out
     # and uncomment the filters: *filter-only-master down below too
     #
     # aliases:
    @@ -181,7 +181,7 @@
     
     

    Tips & Tricks

    When initially deploying to a gh-pages branch using Circle CI, you may notice that some jobs triggered by commits to the gh-pages 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:

    -
    # Circle CI 2.0 Config File
    +
    # Circle CI 2.0 Config File
     # This config file will prevent tests from being run on the gh-pages branch.
     version: 2
     jobs:
    diff --git a/docs/en/1.0.15/publishing/index.html b/docs/en/1.0.15/publishing/index.html
    index 8b0fffdf42..56a6c93a56 100644
    --- a/docs/en/1.0.15/publishing/index.html
    +++ b/docs/en/1.0.15/publishing/index.html
    @@ -50,7 +50,7 @@
             
    Edit

    Publishing your site

    You should now have a site up and running locally. Once you have customized it to your liking, it's time to publish it. Docusaurus generates a static HTML website that is ready to be served by your favorite web server or online hosting solution.

    Building Static HTML Pages

    To create a static build of your website, run the following script from the website directory:

    -
    yarn run build # or `npm run build`
    +
    yarn run build # or `npm run build`
     

    This will generate a build folder inside the website directory containing the .html files from all of your docs and other pages included in pages.

    Hosting Static HTML Pages

    @@ -110,7 +110,7 @@

    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:

    To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate. If you run into issues related to SSH keys, visit Github's authentication documentation.

    -
    GIT_USER=<GIT_USER> \
    +
    GIT_USER=<GIT_USER> \
       CURRENT_BRANCH=master \
       USE_SSH=true \
       yarn run publish-gh-pages # or `npm run publish-gh-pages`
    @@ -134,7 +134,7 @@
     
  • Create a .circleci folder and create a config.yml under that folder.
  • Copy the text below into .circleci/config.yml.
  • -
    # If you only one circle to run on direct commits to master, you can uncomment this out
    +
    # If you only one circle to run on direct commits to master, you can uncomment this out
     # and uncomment the filters: *filter-only-master down below too
     #
     # aliases:
    @@ -181,7 +181,7 @@
     
     

    Tips & Tricks

    When initially deploying to a gh-pages branch using Circle CI, you may notice that some jobs triggered by commits to the gh-pages 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:

    -
    # Circle CI 2.0 Config File
    +
    # Circle CI 2.0 Config File
     # This config file will prevent tests from being run on the gh-pages branch.
     version: 2
     jobs:
    diff --git a/docs/en/1.0.15/search.html b/docs/en/1.0.15/search.html
    index bad5c94ae7..1cf463a7cb 100644
    --- a/docs/en/1.0.15/search.html
    +++ b/docs/en/1.0.15/search.html
    @@ -51,7 +51,7 @@
     

    DocSearch works by crawling the content of your website every 24 hours and putting all the content in an Algolia index. This content is then queried directly from your front-end using the Algolia API. Note that your website need to be publicly available for this to work (ie. not behind a firewall). This service is free.

    Enabling the Search Bar

    Enter your API key and index name (sent by Algolia) into siteConfig.js in the algolia section to enable search for your site.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       algolia: {
         apiKey: 'my-api-key',
    @@ -65,7 +65,7 @@
     

    Controlling the Location of the Search Bar

    By default, the search bar will be the rightmost element in the top navigation bar.

    If you want to change the default location, add the searchBar flag in the headerLinks field of siteConfig.js in your desired location. For example, you may want the search bar between your internal and external links.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       headerLinks: [
         {...}
    diff --git a/docs/en/1.0.15/search/index.html b/docs/en/1.0.15/search/index.html
    index bad5c94ae7..1cf463a7cb 100644
    --- a/docs/en/1.0.15/search/index.html
    +++ b/docs/en/1.0.15/search/index.html
    @@ -51,7 +51,7 @@
     

    DocSearch works by crawling the content of your website every 24 hours and putting all the content in an Algolia index. This content is then queried directly from your front-end using the Algolia API. Note that your website need to be publicly available for this to work (ie. not behind a firewall). This service is free.

    Enabling the Search Bar

    Enter your API key and index name (sent by Algolia) into siteConfig.js in the algolia section to enable search for your site.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       algolia: {
         apiKey: 'my-api-key',
    @@ -65,7 +65,7 @@
     

    Controlling the Location of the Search Bar

    By default, the search bar will be the rightmost element in the top navigation bar.

    If you want to change the default location, add the searchBar flag in the headerLinks field of siteConfig.js in your desired location. For example, you may want the search bar between your internal and external links.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       headerLinks: [
         {...}
    diff --git a/docs/en/1.0.15/site-config.html b/docs/en/1.0.15/site-config.html
    index 796e1a63ac..9919297f01 100644
    --- a/docs/en/1.0.15/site-config.html
    +++ b/docs/en/1.0.15/site-config.html
    @@ -66,7 +66,7 @@
     

    headerIcon - url for icon used in header navigation bar.

    headerLinks - Links that will be used in the header navigation bar. The label field of each object will be the link text and will also be translated for each language.

    Example Usage:

    -
    headerLinks: [
    +
    headerLinks: [
       // Links to document with id doc1 for current language/version
       { doc: "doc1", label: "Getting Started" },
       // Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language
    @@ -97,9 +97,9 @@
     

    blogSidebarCount - Control the number of blog posts that show up in the sidebar. See the adding a blog docs for more information.

    cname - The CNAME for your website. It will go into a CNAME file when your site it built.

    customDocsPath - By default, Docusaurus expects your documentation to be in a directory called docs. This directory is at the same level as the website directory (i.e., not inside the website directory). You can specify a custom path to your documentation with this field. Note that all of your documentation *.md files must still reside in a flat hierarchy. You cannot have your documents in nested directories.

    -
    customDocsPath: 'docs/site'
    +
    customDocsPath: 'docs/site'
     
    -
    customDocsPath: 'website-docs'
    +
    customDocsPath: 'website-docs'
     

    defaultVersionShown - The default version for the site to be shown. If this is not set, the latest version will be shown.

    disableHeaderTitle - 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 true.

    @@ -109,7 +109,7 @@

    facebookPixelId - Facebook Pixel ID to track page views.

    fonts - Font-family css configuration for the site. If a font family is specified in siteConfig.js as $myFont, then adding a myFont key to an array in fonts will allow you to configure the font. Items appearing earlier in the array will take priority of later elements, so ordering of the fonts matter.

    In the below example, we have two sets of font configurations, myFont and myOtherFont. Times New Roman is the preferred font in myFont. -apple-system is the preferred in myOtherFont.

    -
    fonts: {
    +
    fonts: {
       myFont: [
         'Times New Roman',
         'Serif'
    @@ -121,7 +121,7 @@
     },
     

    The above fonts would be represented in your CSS file(s) as variables $myFont and $myOtherFont.

    -
    h1 {
    +
    h1 {
       font-family: $myFont;
     }
     
    @@ -153,7 +153,7 @@

    wrapPagesHTML - Boolean flag to indicate whether html files in /pages should be wrapped with Docusaurus site styles, header and footer. This feature is experimental and relies on the files being html fragments instead of complete pages. It inserts the contents of your html file with no extra processing. Defaults to false.

    Users can also add their own custom fields if they wish to provide some data across different files.

    Example siteConfig.js with many available fields

    -
    const users = [
    +
    const users = [
       {
         caption: 'User1',
         image: '/test-site/img/docusaurus.svg',
    diff --git a/docs/en/1.0.15/site-config/index.html b/docs/en/1.0.15/site-config/index.html
    index 796e1a63ac..9919297f01 100644
    --- a/docs/en/1.0.15/site-config/index.html
    +++ b/docs/en/1.0.15/site-config/index.html
    @@ -66,7 +66,7 @@
     

    headerIcon - url for icon used in header navigation bar.

    headerLinks - Links that will be used in the header navigation bar. The label field of each object will be the link text and will also be translated for each language.

    Example Usage:

    -
    headerLinks: [
    +
    headerLinks: [
       // Links to document with id doc1 for current language/version
       { doc: "doc1", label: "Getting Started" },
       // Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language
    @@ -97,9 +97,9 @@
     

    blogSidebarCount - Control the number of blog posts that show up in the sidebar. See the adding a blog docs for more information.

    cname - The CNAME for your website. It will go into a CNAME file when your site it built.

    customDocsPath - By default, Docusaurus expects your documentation to be in a directory called docs. This directory is at the same level as the website directory (i.e., not inside the website directory). You can specify a custom path to your documentation with this field. Note that all of your documentation *.md files must still reside in a flat hierarchy. You cannot have your documents in nested directories.

    -
    customDocsPath: 'docs/site'
    +
    customDocsPath: 'docs/site'
     
    -
    customDocsPath: 'website-docs'
    +
    customDocsPath: 'website-docs'
     

    defaultVersionShown - The default version for the site to be shown. If this is not set, the latest version will be shown.

    disableHeaderTitle - 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 true.

    @@ -109,7 +109,7 @@

    facebookPixelId - Facebook Pixel ID to track page views.

    fonts - Font-family css configuration for the site. If a font family is specified in siteConfig.js as $myFont, then adding a myFont key to an array in fonts will allow you to configure the font. Items appearing earlier in the array will take priority of later elements, so ordering of the fonts matter.

    In the below example, we have two sets of font configurations, myFont and myOtherFont. Times New Roman is the preferred font in myFont. -apple-system is the preferred in myOtherFont.

    -
    fonts: {
    +
    fonts: {
       myFont: [
         'Times New Roman',
         'Serif'
    @@ -121,7 +121,7 @@
     },
     

    The above fonts would be represented in your CSS file(s) as variables $myFont and $myOtherFont.

    -
    h1 {
    +
    h1 {
       font-family: $myFont;
     }
     
    @@ -153,7 +153,7 @@

    wrapPagesHTML - Boolean flag to indicate whether html files in /pages should be wrapped with Docusaurus site styles, header and footer. This feature is experimental and relies on the files being html fragments instead of complete pages. It inserts the contents of your html file with no extra processing. Defaults to false.

    Users can also add their own custom fields if they wish to provide some data across different files.

    Example siteConfig.js with many available fields

    -
    const users = [
    +
    const users = [
       {
         caption: 'User1',
         image: '/test-site/img/docusaurus.svg',
    diff --git a/docs/en/1.0.15/site-creation.html b/docs/en/1.0.15/site-creation.html
    index fb82d621cf..9cb5aceb88 100644
    --- a/docs/en/1.0.15/site-creation.html
    +++ b/docs/en/1.0.15/site-creation.html
    @@ -51,7 +51,7 @@
     

    After installation and preparation, much of the work to create a basic site for your docs is already complete.

    Site Structure

    Your site structure looks like the following:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs
     ├── website
     │   ├── blog
    @@ -75,7 +75,7 @@
     

    To create a fully functional site, you only need to do a few steps:

    1. Add your documentation to the /docs folder as .md files, ensuring you have the proper header in each file. The simplest header would be the following, where id is the link name (e.g., docs/intro.html) and the title, is, of course, the title of the browser page.

      -
      ---
      +
      ---
       id: intro
       title: Getting Started
       ---
      @@ -93,7 +93,7 @@
       
    2. Place assets, such as images, in the website/static/ folder.
    3. Run the site to see the results of your changes.
    -
    cd website
    +
    cd website
     yarn run start # or `npm run start`
     # Navigate to http://localhost:3000
     
    @@ -104,7 +104,7 @@ yarn run start # or `npm run start`
  • Remove the index.js file from the website/pages directory, if it exists.
  • Add a custom static index.html page in the website/static folder with the following contents:
  • -
    <!DOCTYPE HTML>
    +
    <!DOCTYPE HTML>
     <html lang="en-US">
       <head>
         <meta charset="UTF-8">
    diff --git a/docs/en/1.0.15/site-creation/index.html b/docs/en/1.0.15/site-creation/index.html
    index fb82d621cf..9cb5aceb88 100644
    --- a/docs/en/1.0.15/site-creation/index.html
    +++ b/docs/en/1.0.15/site-creation/index.html
    @@ -51,7 +51,7 @@
     

    After installation and preparation, much of the work to create a basic site for your docs is already complete.

    Site Structure

    Your site structure looks like the following:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs
     ├── website
     │   ├── blog
    @@ -75,7 +75,7 @@
     

    To create a fully functional site, you only need to do a few steps:

    1. Add your documentation to the /docs folder as .md files, ensuring you have the proper header in each file. The simplest header would be the following, where id is the link name (e.g., docs/intro.html) and the title, is, of course, the title of the browser page.

      -
      ---
      +
      ---
       id: intro
       title: Getting Started
       ---
      @@ -93,7 +93,7 @@
       
    2. Place assets, such as images, in the website/static/ folder.
    3. Run the site to see the results of your changes.
    -
    cd website
    +
    cd website
     yarn run start # or `npm run start`
     # Navigate to http://localhost:3000
     
    @@ -104,7 +104,7 @@ yarn run start # or `npm run start`
  • Remove the index.js file from the website/pages directory, if it exists.
  • Add a custom static index.html page in the website/static folder with the following contents:
  • -
    <!DOCTYPE HTML>
    +
    <!DOCTYPE HTML>
     <html lang="en-US">
       <head>
         <meta charset="UTF-8">
    diff --git a/docs/en/1.0.15/site-preparation.html b/docs/en/1.0.15/site-preparation.html
    index e797caff02..b9ee733c40 100644
    --- a/docs/en/1.0.15/site-preparation.html
    +++ b/docs/en/1.0.15/site-preparation.html
    @@ -50,7 +50,7 @@
             
    Edit

    Site Preparation

    After installing Docusaurus, 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.

    Directory Structure

    As shown after you installed Docusaurus, the initialization script created a directory structure similar to:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs-examples-from-docusaurus
     │   ├── doc1.md
     │   ├── doc2.md
    diff --git a/docs/en/1.0.15/site-preparation/index.html b/docs/en/1.0.15/site-preparation/index.html
    index e797caff02..b9ee733c40 100644
    --- a/docs/en/1.0.15/site-preparation/index.html
    +++ b/docs/en/1.0.15/site-preparation/index.html
    @@ -50,7 +50,7 @@
             
    Edit

    Site Preparation

    After installing Docusaurus, 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.

    Directory Structure

    As shown after you installed Docusaurus, the initialization script created a directory structure similar to:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs-examples-from-docusaurus
     │   ├── doc1.md
     │   ├── doc2.md
    diff --git a/docs/en/1.0.15/translation.html b/docs/en/1.0.15/translation.html
    index 0494fc0d79..d9d9d2d326 100644
    --- a/docs/en/1.0.15/translation.html
    +++ b/docs/en/1.0.15/translation.html
    @@ -50,13 +50,13 @@
             
    Edit

    Translations & Localization

    Docusaurus allows for easy translation functionality using Crowdin. Documentation files written in English are uploaded to Crowdin for translation by users within a community. Top-level pages written with English strings can be translated by wrapping any strings you want to translate in a <translate> tag. Other titles and labels will also be found and properly translated.

    Docusaurus Translation Configurations

    To generate example files for translations with Docusaurus, run the examples script with the command line argument translations:

    -
    npm run examples translations
    +
    npm run examples translations
     

    or

    -
    yarn examples translations
    +
    yarn examples translations
     

    This will create the following files:

    -
    pages/en/help-with-translations.js
    +
    pages/en/help-with-translations.js
     languages.js
     ../crowdin.yaml
     
    @@ -76,7 +76,7 @@ languages.js

    Pages allow you to customize layout and specific content of pages like a custom index page or help page.

    Pages with text that you want translated should be placed in website/pages/en folder.

    Wrap strings you want translated in a <translate> tag, and add the following require statement to the top of the file:

    -
    ...
    +
    ...
     const translate = require('../../server/translate.js').translate;
     ...
     <h2>
    @@ -85,7 +85,7 @@ languages.js
     ...
     

    You can also include an optional description attribute to give more context to a translator about how to translate the string:

    -
    <p>
    +
    <p>
       <translate desc="flower, not verb">Rose</translate>
     <p>
     
    @@ -95,7 +95,7 @@ languages.js

    Gathering Strings to Translate

    The strings within localized Pages must be extracted and provided to Crowdin.

    Add the following script to your website/package.json file, if it does not exist already:

    -
    {
    +
    {
       ...
       "scripts": {
         "write-translations": "docusaurus-write-translations"
    @@ -135,7 +135,7 @@ languages.js
     
     

    The example below can be automatically generated by the Docusaurus cli with the examples script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.

    Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.

    -
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
    +
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
     api_key_env: CROWDIN_DOCUSAURUS_API_KEY
     base_path: "./"
     preserve_hierarchy: true
    @@ -160,14 +160,14 @@ languages.js
     

    Setup the Crowdin Scripts

    You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in /docs as well as translatable strings in website/i18n/en.json. (These strings can be generated by running yarn write-translations.)

    You can add the following to your package.json to manually trigger Crowdin.

    -
    "scripts": {
    +
    "scripts": {
       "crowdin-upload": "crowdin --config ../crowdin.yaml upload sources --auto-update -b master",
       "crowdin-download": "crowdin --config ../crowdin.yaml download -b master"
     },
     

    Manual File Sync

    You will always want to upload your markdown files and translatable strings first and the download the translations section. So run the commands in this order:

    -
    CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-upload
    +
    CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-upload
     CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-download
     
    @@ -185,7 +185,7 @@ CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY

    Automated File Sync Using CircleCI

    You can automate pulling down and uploading translations for your files using the CircleCI web continuous integration service.

    First, update the circle.yml 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 circle.yml file:

    -
    machine:
    +
    machine:
       node:
         version: 6.10.3
       npm:
    @@ -221,7 +221,7 @@ CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY
     

    If you wish to use Crowdin on your machine locally, you can install the Crowdin CLI tool and run the same commands found in the circle.yaml file. The only difference is that you must set project_identifier and api_key values in the crowdin.yaml file since you will not have Circle environment variables set up.

    Versioned Translations

    If you wish to have translation and versioning for your documentation, add the following section to the end of your crowdin.yaml file:

    -
      -
    +
      -
         source: '/website/versioned_docs/**/*.md'
         translation: '/website/translated_docs/%locale%/**/%original_file_name%'
         languages_mapping: *anchor
    diff --git a/docs/en/1.0.15/translation/index.html b/docs/en/1.0.15/translation/index.html
    index 0494fc0d79..d9d9d2d326 100644
    --- a/docs/en/1.0.15/translation/index.html
    +++ b/docs/en/1.0.15/translation/index.html
    @@ -50,13 +50,13 @@
             
    Edit

    Translations & Localization

    Docusaurus allows for easy translation functionality using Crowdin. Documentation files written in English are uploaded to Crowdin for translation by users within a community. Top-level pages written with English strings can be translated by wrapping any strings you want to translate in a <translate> tag. Other titles and labels will also be found and properly translated.

    Docusaurus Translation Configurations

    To generate example files for translations with Docusaurus, run the examples script with the command line argument translations:

    -
    npm run examples translations
    +
    npm run examples translations
     

    or

    -
    yarn examples translations
    +
    yarn examples translations
     

    This will create the following files:

    -
    pages/en/help-with-translations.js
    +
    pages/en/help-with-translations.js
     languages.js
     ../crowdin.yaml
     
    @@ -76,7 +76,7 @@ languages.js

    Pages allow you to customize layout and specific content of pages like a custom index page or help page.

    Pages with text that you want translated should be placed in website/pages/en folder.

    Wrap strings you want translated in a <translate> tag, and add the following require statement to the top of the file:

    -
    ...
    +
    ...
     const translate = require('../../server/translate.js').translate;
     ...
     <h2>
    @@ -85,7 +85,7 @@ languages.js
     ...
     

    You can also include an optional description attribute to give more context to a translator about how to translate the string:

    -
    <p>
    +
    <p>
       <translate desc="flower, not verb">Rose</translate>
     <p>
     
    @@ -95,7 +95,7 @@ languages.js

    Gathering Strings to Translate

    The strings within localized Pages must be extracted and provided to Crowdin.

    Add the following script to your website/package.json file, if it does not exist already:

    -
    {
    +
    {
       ...
       "scripts": {
         "write-translations": "docusaurus-write-translations"
    @@ -135,7 +135,7 @@ languages.js
     
     

    The example below can be automatically generated by the Docusaurus cli with the examples script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.

    Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.

    -
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
    +
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
     api_key_env: CROWDIN_DOCUSAURUS_API_KEY
     base_path: "./"
     preserve_hierarchy: true
    @@ -160,14 +160,14 @@ languages.js
     

    Setup the Crowdin Scripts

    You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in /docs as well as translatable strings in website/i18n/en.json. (These strings can be generated by running yarn write-translations.)

    You can add the following to your package.json to manually trigger Crowdin.

    -
    "scripts": {
    +
    "scripts": {
       "crowdin-upload": "crowdin --config ../crowdin.yaml upload sources --auto-update -b master",
       "crowdin-download": "crowdin --config ../crowdin.yaml download -b master"
     },
     

    Manual File Sync

    You will always want to upload your markdown files and translatable strings first and the download the translations section. So run the commands in this order:

    -
    CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-upload
    +
    CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-upload
     CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-download
     
    @@ -185,7 +185,7 @@ CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY

    Automated File Sync Using CircleCI

    You can automate pulling down and uploading translations for your files using the CircleCI web continuous integration service.

    First, update the circle.yml 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 circle.yml file:

    -
    machine:
    +
    machine:
       node:
         version: 6.10.3
       npm:
    @@ -221,7 +221,7 @@ CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY
     

    If you wish to use Crowdin on your machine locally, you can install the Crowdin CLI tool and run the same commands found in the circle.yaml file. The only difference is that you must set project_identifier and api_key values in the crowdin.yaml file since you will not have Circle environment variables set up.

    Versioned Translations

    If you wish to have translation and versioning for your documentation, add the following section to the end of your crowdin.yaml file:

    -
      -
    +
      -
         source: '/website/versioned_docs/**/*.md'
         translation: '/website/translated_docs/%locale%/**/%original_file_name%'
         languages_mapping: *anchor
    diff --git a/docs/en/1.0.15/versioning.html b/docs/en/1.0.15/versioning.html
    index 12f13ba67b..302a252372 100644
    --- a/docs/en/1.0.15/versioning.html
    +++ b/docs/en/1.0.15/versioning.html
    @@ -50,19 +50,19 @@
             
    Edit

    Versioning

    You can use the version script to cut a new documentation version based on the latest content in the docs folder. That specific set of documentation will then be preserved and accessible even as the documentation in the docs folder changes moving forward.

    How to Create New Versions

    Run the following script to generate a starter versions page listing all the site versions:

    -
    yarn examples versions
    +
    yarn examples versions
     

    This creates the pages/en/versions.js file.

    You can edit this file later on to customize how you display the versions.

    Add the following script to your package.json file if it doesn't already exist:

    -
    ...
    +
    ...
     "scripts": {
       "version": "docusaurus-version"
     },
     ...
     

    Run the script with a command line argument of the version you wish to create. e.g.,

    -
    yarn run version 1.0.0
    +
    yarn run version 1.0.0
     

    This will preserve all documents currently in the docs folder and make them available as documentation for version 1.0.0.

    If, for example, you ran the version script with 1.0.0 as the version number, version 1.0.0 is considered the latest release version for your project. 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.

    @@ -93,14 +93,14 @@

    For example, a document with the original id doc1 exists for the latest version, 1.0.0, and has the same content as the document with the id doc1 in the docs folder. When a new version 2.0.0 is created, the file for doc1 will not be copied into versioned_docs/version-2.0.0/. There will still be a page for docs/2.0.0/doc1.html, but it will use the file from version 1.0.0.

    Renaming Existing Versions

    To rename an existing version number to something else, first make sure the following script is in your package.json file:

    -
    ...
    +
    ...
     "scripts": {
       "rename-version": "docusaurus-rename-version"
     },
     ...
     

    Run the script with command line arguments of first, the current version name, then second, the new version name. e.g.,

    -
    yarn run rename-version 1.0.0 1.0.1
    +
    yarn run rename-version 1.0.0 1.0.1
     

    Versioning and Translations

    If you wish to use versioning and translations features, the crowdin.yaml 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 translated_docs/${language}/version-${version}/. For more information, check out the translations guide.

    diff --git a/docs/en/1.0.15/versioning/index.html b/docs/en/1.0.15/versioning/index.html index 12f13ba67b..302a252372 100644 --- a/docs/en/1.0.15/versioning/index.html +++ b/docs/en/1.0.15/versioning/index.html @@ -50,19 +50,19 @@
    Edit

    Versioning

    You can use the version script to cut a new documentation version based on the latest content in the docs folder. That specific set of documentation will then be preserved and accessible even as the documentation in the docs folder changes moving forward.

    How to Create New Versions

    Run the following script to generate a starter versions page listing all the site versions:

    -
    yarn examples versions
    +
    yarn examples versions
     

    This creates the pages/en/versions.js file.

    You can edit this file later on to customize how you display the versions.

    Add the following script to your package.json file if it doesn't already exist:

    -
    ...
    +
    ...
     "scripts": {
       "version": "docusaurus-version"
     },
     ...
     

    Run the script with a command line argument of the version you wish to create. e.g.,

    -
    yarn run version 1.0.0
    +
    yarn run version 1.0.0
     

    This will preserve all documents currently in the docs folder and make them available as documentation for version 1.0.0.

    If, for example, you ran the version script with 1.0.0 as the version number, version 1.0.0 is considered the latest release version for your project. 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.

    @@ -93,14 +93,14 @@

    For example, a document with the original id doc1 exists for the latest version, 1.0.0, and has the same content as the document with the id doc1 in the docs folder. When a new version 2.0.0 is created, the file for doc1 will not be copied into versioned_docs/version-2.0.0/. There will still be a page for docs/2.0.0/doc1.html, but it will use the file from version 1.0.0.

    Renaming Existing Versions

    To rename an existing version number to something else, first make sure the following script is in your package.json file:

    -
    ...
    +
    ...
     "scripts": {
       "rename-version": "docusaurus-rename-version"
     },
     ...
     

    Run the script with command line arguments of first, the current version name, then second, the new version name. e.g.,

    -
    yarn run rename-version 1.0.0 1.0.1
    +
    yarn run rename-version 1.0.0 1.0.1
     

    Versioning and Translations

    If you wish to use versioning and translations features, the crowdin.yaml 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 translated_docs/${language}/version-${version}/. For more information, check out the translations guide.

    diff --git a/docs/en/1.1.0/api-pages.html b/docs/en/1.1.0/api-pages.html index 7850519467..2cb48ec3a1 100644 --- a/docs/en/1.1.0/api-pages.html +++ b/docs/en/1.1.0/api-pages.html @@ -59,7 +59,7 @@

    CompLibrary.MarkdownBlock

    A React component that parses markdown and renders to HTML.

    Example:

    -
    const MarkdownBlock = CompLibrary.MarkdownBlock;
    +
    const MarkdownBlock = CompLibrary.MarkdownBlock;
     
     <MarkdownBlock>
       [Markdown syntax for a link](http://www.example.com)
    @@ -79,7 +79,7 @@
     
     
     

    Example

    -
    <Container
    +
    <Container
       padding={['bottom', 'top']}
       background="light"
       className="myCustomClass">
    @@ -115,7 +115,7 @@
     
     
     

    Example

    -
    <GridBlock
    +
    <GridBlock
       align="center"
       layout="threeColumn"
       className="myCustomClass"
    @@ -144,19 +144,19 @@
     

    Translating Strings

    When translations are enabled, any pages inside website/pages/en will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the languages.js file. E.g. The url for a French page of website/pages/en/help.js would be found at ${baseUrl}fr/help.html.

    When writing pages that you wish to translate, wrap any strings to be translated inside a <translate> tag. e.g.,

    -
    <p>
    +
    <p>
       <translate>I like translations</translate>
     </p>
     

    You can also provide an optional description attribute to provide context for translators. e.g,

    -
    <a href="/community">
    +
    <a href="/community">
       <translate desc="Footer link to page referring to community GitHub and Slack">
         Community
       </translate>
     </a>
     

    Add the following require statement as well:

    -
    const translate = require('../../server/translate.js').translate;
    +
    const translate = require('../../server/translate.js').translate;
     

    Note that this path is valid for files inside pages/en and should be adjusted accordingly if files are in different locations, as discussed above.

    Using Static Assets

    diff --git a/docs/en/1.1.0/api-pages/index.html b/docs/en/1.1.0/api-pages/index.html index 7850519467..2cb48ec3a1 100644 --- a/docs/en/1.1.0/api-pages/index.html +++ b/docs/en/1.1.0/api-pages/index.html @@ -59,7 +59,7 @@

    CompLibrary.MarkdownBlock

    A React component that parses markdown and renders to HTML.

    Example:

    -
    const MarkdownBlock = CompLibrary.MarkdownBlock;
    +
    const MarkdownBlock = CompLibrary.MarkdownBlock;
     
     <MarkdownBlock>
       [Markdown syntax for a link](http://www.example.com)
    @@ -79,7 +79,7 @@
     
     
     

    Example

    -
    <Container
    +
    <Container
       padding={['bottom', 'top']}
       background="light"
       className="myCustomClass">
    @@ -115,7 +115,7 @@
     
     
     

    Example

    -
    <GridBlock
    +
    <GridBlock
       align="center"
       layout="threeColumn"
       className="myCustomClass"
    @@ -144,19 +144,19 @@
     

    Translating Strings

    When translations are enabled, any pages inside website/pages/en will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the languages.js file. E.g. The url for a French page of website/pages/en/help.js would be found at ${baseUrl}fr/help.html.

    When writing pages that you wish to translate, wrap any strings to be translated inside a <translate> tag. e.g.,

    -
    <p>
    +
    <p>
       <translate>I like translations</translate>
     </p>
     

    You can also provide an optional description attribute to provide context for translators. e.g,

    -
    <a href="/community">
    +
    <a href="/community">
       <translate desc="Footer link to page referring to community GitHub and Slack">
         Community
       </translate>
     </a>
     

    Add the following require statement as well:

    -
    const translate = require('../../server/translate.js').translate;
    +
    const translate = require('../../server/translate.js').translate;
     

    Note that this path is valid for files inside pages/en and should be adjusted accordingly if files are in different locations, as discussed above.

    Using Static Assets

    diff --git a/docs/en/1.1.0/blog.html b/docs/en/1.1.0/blog.html index 77153f0540..2a03efb248 100644 --- a/docs/en/1.1.0/blog.html +++ b/docs/en/1.1.0/blog.html @@ -50,7 +50,7 @@
    Edit

    Adding a Blog

    Initial Setup

    To setup your site's blog, start by creating a blog folder within your repo's website directory.

    Then, add a header link to your blog within siteConfig.js:

    -
    headerLinks: [
    +
    headerLinks: [
         ...
         { blog: true, label: 'Blog' },
         ...
    @@ -59,7 +59,7 @@
     

    Adding Posts

    To publish in the blog, create a file within the blog folder with a formatted name of YYYY-MM-DD-My-Blog-Post-Title.md. The post date is extracted from the file name.

    For example, at website/blog/2017-08-18-Introducing-Docusaurus.md:

    -
    ---
    +
    ---
     author: Frank Li
     authorURL: https://twitter.com/foobarbaz
     authorFBID: 503283835
    @@ -79,7 +79,7 @@
     
     

    Summary Truncation

    Use the <!--truncate--> marker in your blog post to represent what will be shown as the summary when viewing all blog published blog posts. Anything above <!--truncate--> will be part of the summary. For example:

    -
    ---
    +
    ---
     title: Truncation Example
     ---
     
    @@ -100,7 +100,7 @@
     

    You can configure a specific amount of blog posts to show by adding a blogSidebarCount setting to your siteConfig.js.

    The available options are an integer representing the number of posts you wish to show or a string with the value 'ALL'.

    Example:

    -
    blogSidebarCount: 'ALL'
    +
    blogSidebarCount: 'ALL'
     

    RSS Feed

    Docusaurus provides a simple RSS feed for your blog posts. Both RSS and Atom feed formats are supported. This data is automatically to your website page's HTML tag.

    @@ -121,7 +121,7 @@

    Now, when Docusaurus generates or builds your site, it will copy the file from static/index.html 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 /blog.

    You can use this template:

    -
    <!DOCTYPE HTML>
    +
    <!DOCTYPE HTML>
     <html lang="en-US">
       <head>
         <meta charset="UTF-8">
    diff --git a/docs/en/1.1.0/blog/index.html b/docs/en/1.1.0/blog/index.html
    index 77153f0540..2a03efb248 100644
    --- a/docs/en/1.1.0/blog/index.html
    +++ b/docs/en/1.1.0/blog/index.html
    @@ -50,7 +50,7 @@
             
    Edit

    Adding a Blog

    Initial Setup

    To setup your site's blog, start by creating a blog folder within your repo's website directory.

    Then, add a header link to your blog within siteConfig.js:

    -
    headerLinks: [
    +
    headerLinks: [
         ...
         { blog: true, label: 'Blog' },
         ...
    @@ -59,7 +59,7 @@
     

    Adding Posts

    To publish in the blog, create a file within the blog folder with a formatted name of YYYY-MM-DD-My-Blog-Post-Title.md. The post date is extracted from the file name.

    For example, at website/blog/2017-08-18-Introducing-Docusaurus.md:

    -
    ---
    +
    ---
     author: Frank Li
     authorURL: https://twitter.com/foobarbaz
     authorFBID: 503283835
    @@ -79,7 +79,7 @@
     
     

    Summary Truncation

    Use the <!--truncate--> marker in your blog post to represent what will be shown as the summary when viewing all blog published blog posts. Anything above <!--truncate--> will be part of the summary. For example:

    -
    ---
    +
    ---
     title: Truncation Example
     ---
     
    @@ -100,7 +100,7 @@
     

    You can configure a specific amount of blog posts to show by adding a blogSidebarCount setting to your siteConfig.js.

    The available options are an integer representing the number of posts you wish to show or a string with the value 'ALL'.

    Example:

    -
    blogSidebarCount: 'ALL'
    +
    blogSidebarCount: 'ALL'
     

    RSS Feed

    Docusaurus provides a simple RSS feed for your blog posts. Both RSS and Atom feed formats are supported. This data is automatically to your website page's HTML tag.

    @@ -121,7 +121,7 @@

    Now, when Docusaurus generates or builds your site, it will copy the file from static/index.html 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 /blog.

    You can use this template:

    -
    <!DOCTYPE HTML>
    +
    <!DOCTYPE HTML>
     <html lang="en-US">
       <head>
         <meta charset="UTF-8">
    diff --git a/docs/en/1.1.0/commands.html b/docs/en/1.1.0/commands.html
    index 904a644d1c..5aad02d7fe 100644
    --- a/docs/en/1.1.0/commands.html
    +++ b/docs/en/1.1.0/commands.html
    @@ -54,18 +54,18 @@
     
     

    Running from the command line

    The scripts can be run using either Yarn or npm. If you've already gone through our Getting Started guide, you may already be familiar with the start command. It's the command that tells Docusaurus to run the docusaurus-start script which generates the site and starts up a server, and it's usually invoked like so:

    -
    yarn run start
    +
    yarn run start
     

    The same script can be invoked using npm:

    -
    npm run start
    +
    npm run start
     

    To run a particular script, just replace the start command in the examples above with the command associated with your script.

    Using arguments

    Some commands support optional arguments. For example, to start a server on port 8080, you can specify the --port argument when running start:

    -
    yarn run start --port 8080
    +
    yarn run start --port 8080
     

    If you run Docusaurus using npm, you can still use the command line arguments by inserting a -- between npm run <command> and the command arguments:

    -
    npm run start -- --port 8080
    +
    npm run start -- --port 8080
     

    Configuration

    These scripts are set up under the "scripts" key in your website/package.json file as part of the installation process. If you need help setting them up again, please refer to the Installation guide.

    @@ -106,7 +106,7 @@

    Example

    -
    docusaurus-examples <feature>
    +
    docusaurus-examples <feature>
     

    When no feature is specified, sets up a minimally configured example website in your project. This command is covered in depth in the Site Preparation guide.


    @@ -119,7 +119,7 @@
  • USE_SSH: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.
  • Example

    -
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
    +
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
     

    The following environment variables are set by CircleCI during the build process.

      @@ -146,7 +146,7 @@

      Example

      -
      docusaurus-rename-version <currentVersion> <newVersion>
      +
      docusaurus-rename-version <currentVersion> <newVersion>
       

      See the Versioning guide to learn more.


      diff --git a/docs/en/1.1.0/commands/index.html b/docs/en/1.1.0/commands/index.html index 904a644d1c..5aad02d7fe 100644 --- a/docs/en/1.1.0/commands/index.html +++ b/docs/en/1.1.0/commands/index.html @@ -54,18 +54,18 @@

    Running from the command line

    The scripts can be run using either Yarn or npm. If you've already gone through our Getting Started guide, you may already be familiar with the start command. It's the command that tells Docusaurus to run the docusaurus-start script which generates the site and starts up a server, and it's usually invoked like so:

    -
    yarn run start
    +
    yarn run start
     

    The same script can be invoked using npm:

    -
    npm run start
    +
    npm run start
     

    To run a particular script, just replace the start command in the examples above with the command associated with your script.

    Using arguments

    Some commands support optional arguments. For example, to start a server on port 8080, you can specify the --port argument when running start:

    -
    yarn run start --port 8080
    +
    yarn run start --port 8080
     

    If you run Docusaurus using npm, you can still use the command line arguments by inserting a -- between npm run <command> and the command arguments:

    -
    npm run start -- --port 8080
    +
    npm run start -- --port 8080
     

    Configuration

    These scripts are set up under the "scripts" key in your website/package.json file as part of the installation process. If you need help setting them up again, please refer to the Installation guide.

    @@ -106,7 +106,7 @@

    Example

    -
    docusaurus-examples <feature>
    +
    docusaurus-examples <feature>
     

    When no feature is specified, sets up a minimally configured example website in your project. This command is covered in depth in the Site Preparation guide.


    @@ -119,7 +119,7 @@
  • USE_SSH: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.
  • Example

    -
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
    +
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
     

    The following environment variables are set by CircleCI during the build process.

      @@ -146,7 +146,7 @@

      Example

      -
      docusaurus-rename-version <currentVersion> <newVersion>
      +
      docusaurus-rename-version <currentVersion> <newVersion>
       

      See the Versioning guide to learn more.


      diff --git a/docs/en/1.1.0/custom-pages.html b/docs/en/1.1.0/custom-pages.html index 65ee6553b0..27949bdd12 100644 --- a/docs/en/1.1.0/custom-pages.html +++ b/docs/en/1.1.0/custom-pages.html @@ -53,7 +53,7 @@

      You can start your local server and go to http://localhost:3000 to see what the example home page looks like. From there, edit the website/pages/en/index.js file and its various components to use the images and text you want for your project.

      Adding Other Custom Pages

      Docusaurus provides some simple example pages in the website/pages/en directory, including index.js, users.js, and help.js. These are good examples to showcase how to create a custom page for Docusaurus.

      -
      root-of-repo
      +
      root-of-repo
       ├── docs
       ├── website
       │   ├── blog
      @@ -85,7 +85,7 @@
       

      Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.

      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.

      If you do not want a footer for your site, change the render function of core/Footer.js to return null. e.g.,

      -
      const React = require('react');
      +
      const React = require('react');
       
       class Footer extends React.Component {
         render() {
      diff --git a/docs/en/1.1.0/custom-pages/index.html b/docs/en/1.1.0/custom-pages/index.html
      index 65ee6553b0..27949bdd12 100644
      --- a/docs/en/1.1.0/custom-pages/index.html
      +++ b/docs/en/1.1.0/custom-pages/index.html
      @@ -53,7 +53,7 @@
       

      You can start your local server and go to http://localhost:3000 to see what the example home page looks like. From there, edit the website/pages/en/index.js file and its various components to use the images and text you want for your project.

      Adding Other Custom Pages

      Docusaurus provides some simple example pages in the website/pages/en directory, including index.js, users.js, and help.js. These are good examples to showcase how to create a custom page for Docusaurus.

      -
      root-of-repo
      +
      root-of-repo
       ├── docs
       ├── website
       │   ├── blog
      @@ -85,7 +85,7 @@
       

      Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.

      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.

      If you do not want a footer for your site, change the render function of core/Footer.js to return null. e.g.,

      -
      const React = require('react');
      +
      const React = require('react');
       
       class Footer extends React.Component {
         render() {
      diff --git a/docs/en/1.1.0/doc-markdown.html b/docs/en/1.1.0/doc-markdown.html
      index 17abac2460..8c996c1482 100644
      --- a/docs/en/1.1.0/doc-markdown.html
      +++ b/docs/en/1.1.0/doc-markdown.html
      @@ -55,7 +55,7 @@
       

      hide_title: Whether to hide the title at the top of the doc.

      sidebar_label: The text shown in the document sidebar for this document. If this field is not present, the document's sidebar_label will default to its title.

      For example:

      -
      ---
      +
      ---
       id: doc1
       title: My Document
       sidebar_label: Document
      @@ -63,7 +63,7 @@
       

      Versioned documents have their ids altered to include the version number when they get copied. The new id is version-${version}-${id} where ${version} is the version number of that document and ${id} is the original id. Additionally, versioned documents get an added original_id field with the original document id.

      For example:

      -
      ---
      +
      ---
       id: version-1.0.0-doc1
       title: My Document
       sidebar_label: Document
      @@ -72,7 +72,7 @@
       

      custom_edit_url: The url for editing this document. If this field is not present, the document's edit url will fallback to editUrl from optional fields of siteConfig.js. See siteConfig.js docs for more information.

      For example:

      -
      ---
      +
      ---
       id: doc-markdown
       title: Markdown Features
       custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
      @@ -85,7 +85,7 @@
       

      authorURL: 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.

      authorFBID: 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.

      For example:

      -
      ---
      +
      ---
       title: My First Blog Post
       author: Frank Li
       authorURL: http://twitter.com/franchementli
      @@ -97,20 +97,20 @@
       

      Linking other Documents

      You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.

      Example:

      -
      [This links to another document](other-document.md)
      +
      [This links to another document](other-document.md)
       

      This markdown will automatically get converted into a link to /docs/other-document.html (or the appropriately translated/versioned link) once it gets rendered.

      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.

      Linking to Images and Other Assets

      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 docs/assets and website/blog/assets, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.

      Example:

      -
      ![alt-text](/docs/assets/doc-image.png)
      +
      ![alt-text](/docs/assets/doc-image.png)
       

      Generating Table of Contents

      You can make an autogenerated list of links, which can be useful as a table of contents for API docs.

      In your markdown file, insert a line with the text <AUTOGENERATED_TABLE_OF_CONTENTS>. Write your documentation using h3 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 <AUTOGENERATED_TABLE_OF_CONTENTS>.

      Example:

      -
      ### `docusaurus.function(a, b)`
      +
      ### `docusaurus.function(a, b)`
       
       Text describing my function
       
      @@ -119,7 +119,7 @@ Text describing my function
       Text describing my function
       

      will lead to a table of contents of the functions:

      -
      - `docusaurus.function(a, b)`
      +
      - `docusaurus.function(a, b)`
       - `docdoc(file)`
       

      and each function will link to their corresponding sections in the page.

      @@ -133,13 +133,13 @@ ReactDOM.render( ```

      ...would be rendered with syntax highlighting like so:

      -
      ReactDOM.render(
      +
      ReactDOM.render(
         <h1>Hello, world!</h1>,
         document.getElementById('root')
       );
       

      Highlighting is provided by Highlight.js using the theme specified in your siteConfig.js file as part of the highlight key:

      -
      {
      +
      {
         ...
         highlight: {
           theme: 'default'
      @@ -150,7 +150,7 @@ ReactDOM.render(
       

      You can find the full list of supported themes in the Highlight.js styles directory.

      Registering additional languages

      While Highlight.js provides support for many popular languages out of the box, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the hljs constant as part of the highlight config key. This in turn allows you to call registerLanguage:

      -
      {
      +
      {
         ...
         highlight: {
           theme: 'default',
      diff --git a/docs/en/1.1.0/doc-markdown/index.html b/docs/en/1.1.0/doc-markdown/index.html
      index 17abac2460..8c996c1482 100644
      --- a/docs/en/1.1.0/doc-markdown/index.html
      +++ b/docs/en/1.1.0/doc-markdown/index.html
      @@ -55,7 +55,7 @@
       

      hide_title: Whether to hide the title at the top of the doc.

      sidebar_label: The text shown in the document sidebar for this document. If this field is not present, the document's sidebar_label will default to its title.

      For example:

      -
      ---
      +
      ---
       id: doc1
       title: My Document
       sidebar_label: Document
      @@ -63,7 +63,7 @@
       

      Versioned documents have their ids altered to include the version number when they get copied. The new id is version-${version}-${id} where ${version} is the version number of that document and ${id} is the original id. Additionally, versioned documents get an added original_id field with the original document id.

      For example:

      -
      ---
      +
      ---
       id: version-1.0.0-doc1
       title: My Document
       sidebar_label: Document
      @@ -72,7 +72,7 @@
       

      custom_edit_url: The url for editing this document. If this field is not present, the document's edit url will fallback to editUrl from optional fields of siteConfig.js. See siteConfig.js docs for more information.

      For example:

      -
      ---
      +
      ---
       id: doc-markdown
       title: Markdown Features
       custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
      @@ -85,7 +85,7 @@
       

      authorURL: 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.

      authorFBID: 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.

      For example:

      -
      ---
      +
      ---
       title: My First Blog Post
       author: Frank Li
       authorURL: http://twitter.com/franchementli
      @@ -97,20 +97,20 @@
       

      Linking other Documents

      You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.

      Example:

      -
      [This links to another document](other-document.md)
      +
      [This links to another document](other-document.md)
       

      This markdown will automatically get converted into a link to /docs/other-document.html (or the appropriately translated/versioned link) once it gets rendered.

      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.

      Linking to Images and Other Assets

      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 docs/assets and website/blog/assets, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.

      Example:

      -
      ![alt-text](/docs/assets/doc-image.png)
      +
      ![alt-text](/docs/assets/doc-image.png)
       

      Generating Table of Contents

      You can make an autogenerated list of links, which can be useful as a table of contents for API docs.

      In your markdown file, insert a line with the text <AUTOGENERATED_TABLE_OF_CONTENTS>. Write your documentation using h3 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 <AUTOGENERATED_TABLE_OF_CONTENTS>.

      Example:

      -
      ### `docusaurus.function(a, b)`
      +
      ### `docusaurus.function(a, b)`
       
       Text describing my function
       
      @@ -119,7 +119,7 @@ Text describing my function
       Text describing my function
       

      will lead to a table of contents of the functions:

      -
      - `docusaurus.function(a, b)`
      +
      - `docusaurus.function(a, b)`
       - `docdoc(file)`
       

      and each function will link to their corresponding sections in the page.

      @@ -133,13 +133,13 @@ ReactDOM.render( ```

      ...would be rendered with syntax highlighting like so:

      -
      ReactDOM.render(
      +
      ReactDOM.render(
         <h1>Hello, world!</h1>,
         document.getElementById('root')
       );
       

      Highlighting is provided by Highlight.js using the theme specified in your siteConfig.js file as part of the highlight key:

      -
      {
      +
      {
         ...
         highlight: {
           theme: 'default'
      @@ -150,7 +150,7 @@ ReactDOM.render(
       

      You can find the full list of supported themes in the Highlight.js styles directory.

      Registering additional languages

      While Highlight.js provides support for many popular languages out of the box, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the hljs constant as part of the highlight config key. This in turn allows you to call registerLanguage:

      -
      {
      +
      {
         ...
         highlight: {
           theme: 'default',
      diff --git a/docs/en/1.1.0/installation.html b/docs/en/1.1.0/installation.html
      index 39a40332c8..2d7d78c04b 100644
      --- a/docs/en/1.1.0/installation.html
      +++ b/docs/en/1.1.0/installation.html
      @@ -62,7 +62,7 @@
       

      After Docusaurus is installed, moving forward, you can check your current version of Docusaurus by going into the website directory and typing yarn outdated docusaurus or npm outdated docusaurus. You can update to the latest version of Docusaurus by typing yarn upgrade docusaurus --latest or npm update docusaurus.

      Verifying Installation

      Along with previously existing files and directories, your root directory will now contain a structure similar to:

      -
      root-of-repo
      +
      root-of-repo
       ├── docs-examples-from-docusaurus
       │   ├── doc1.md
       │   ├── doc2.md
      diff --git a/docs/en/1.1.0/installation/index.html b/docs/en/1.1.0/installation/index.html
      index 39a40332c8..2d7d78c04b 100644
      --- a/docs/en/1.1.0/installation/index.html
      +++ b/docs/en/1.1.0/installation/index.html
      @@ -62,7 +62,7 @@
       

      After Docusaurus is installed, moving forward, you can check your current version of Docusaurus by going into the website directory and typing yarn outdated docusaurus or npm outdated docusaurus. You can update to the latest version of Docusaurus by typing yarn upgrade docusaurus --latest or npm update docusaurus.

      Verifying Installation

      Along with previously existing files and directories, your root directory will now contain a structure similar to:

      -
      root-of-repo
      +
      root-of-repo
       ├── docs-examples-from-docusaurus
       │   ├── doc1.md
       │   ├── doc2.md
      diff --git a/docs/en/1.1.0/navigation.html b/docs/en/1.1.0/navigation.html
      index 451c59e808..e7f15e1fb7 100644
      --- a/docs/en/1.1.0/navigation.html
      +++ b/docs/en/1.1.0/navigation.html
      @@ -50,7 +50,7 @@
               
    Edit

    Navigation and Sidebars

    Referencing Site Documents

    If you want to reference another document in your docs folder (or the location you set via the optional customDocsPath path site configuration option), then you just use the name of the document you want to reference.

    For example, if you are in doc2.md and you want to reference doc1.md:

    -
    I am referencing a [document](doc1.md).
    +
    I am referencing a [document](doc1.md).
     

    Docusaurus currently does not support documents in nested folders; only in a flat folder structure. We are looking into adding support for nested folders.

    @@ -59,7 +59,7 @@

    New markdown files within docs will show up as pages on the website. Links to those documents are created first by using the id in the header of each document. If there is no id field, then the name of the file will serve as the link name.

    For example, creating an empty file such as docs/getting-started.md will enable the new page URL as /docs/getting-started.html.

    Suppose you add this to your document:

    -
    ---
    +
    ---
     id: intro
     title: Getting Started
     ---
    @@ -80,7 +80,7 @@
     

    Until you add your document to website/sidebars.json, they will only be accessible via a direct URL. The doc will not show up in any sidebar.

    Within sidebars.json, add the id you used in the document header to existing sidebar/category. In the below case, docs is the name of the sidebar and Getting Started is a category within the sidebar.

    -
    {
    +
    {
       "docs": {
         "Getting Started": [
           "getting-started"
    @@ -91,7 +91,7 @@
     }
     

    Or you can create a new category within the sidebar:

    -
    {
    +
    {
       "docs": {
         "My New Sidebar Category": [
           "getting-started"
    @@ -103,7 +103,7 @@
     

    Adding New Sidebars

    You can also put a document in a new sidebar. In the following example, we are creating an examples-sidebar sidebar within sidebars.json that has a category called My Example Category containing a document with an id of my-examples.

    -
    {
    +
    {
       "examples-sidebar": {
         "My Example Category": [
           "my-examples"
    @@ -118,7 +118,7 @@
     

    To expose sidebars, you will add clickable labels to the site navigation bar at the top of the website. You can add documents, pages and external links.

    Adding Documents

    After creating a new sidebar for the site by adding it to sidebars.json, you can expose the new sidebar from the top navigation bar by editing the headerLinks field of siteConfig.js.

    -
    {
    +
    {
       headerLinks: [
         ...
         { doc: 'my-examples', label: 'Examples' },
    @@ -130,7 +130,7 @@
     

    A label called Examples will be added to the site navigation bar and when you click on it at the top of your site, the examples-sidebar will be shown and the default document will be my-examples.

    Adding Custom Pages

    To add custom pages to the site navigation bar, entries can be added to the headerLinks of siteConfig.js. For example, if we have a page within website/pages/help.js, we can link to it by adding the following:

    -
    {
    +
    {
       headerLinks: [
         ...
         { page: 'help', label: 'Help' },
    @@ -142,7 +142,7 @@
     

    A label called Help will be added to the site navigation bar and when you click on it at the top of your site, the content from the help.js page will be shown.

    Adding External Links

    Custom links can be added to the site navigation bar with the following entry in siteConfig.js:

    -
    {
    +
    {
       headerLinks: [
         ...
         { href: 'https://github.com/facebook/Docusaurus', label: 'GitHub' },
    @@ -159,7 +159,7 @@
     

    You have limited control where the search and languages dropdown elements are shown in the site navigation bar at the top of your website.

    Search

    If search is enabled on your site, your search bar will appear to the right of your links. If you want to put the search bar between links in the header, add a search entry in the headerLinks config array:

    -
    {
    +
    {
       headerLinks: [
         { doc: 'foo', label: 'Foo' },
         { search: true },
    @@ -170,7 +170,7 @@
     

    Languages Dropdown

    If translations is enabled on your site, the language dropdown will appear to the right of your links (and to the left of the search bar, if search is enabled). If you want to put the language selection drop down between links in the header, add a languages entry in the headerLinks config array:

    -
    {
    +
    {
       headerLinks: [
         { doc: 'foo', label: 'Foo' },
         { languages: true },
    @@ -192,7 +192,7 @@
     

    These are two separate class names so you can have the active styles applied to either exact matches only or a bit more broadly for docs that belong together. If you don't want to make this distinction you can add both classes to the same CSS rule.

    Secondary On-Page Navigation

    We support secondary on-page navigation so you can more easily see the topics associated with a given document. To enable this feature, you need to add the onPageNav site configuration option to your siteConfig.js.

    -
    {
    +
    {
       onPageNav: 'separate',
       ...
     }
    diff --git a/docs/en/1.1.0/navigation/index.html b/docs/en/1.1.0/navigation/index.html
    index 451c59e808..e7f15e1fb7 100644
    --- a/docs/en/1.1.0/navigation/index.html
    +++ b/docs/en/1.1.0/navigation/index.html
    @@ -50,7 +50,7 @@
             
    Edit

    Navigation and Sidebars

    Referencing Site Documents

    If you want to reference another document in your docs folder (or the location you set via the optional customDocsPath path site configuration option), then you just use the name of the document you want to reference.

    For example, if you are in doc2.md and you want to reference doc1.md:

    -
    I am referencing a [document](doc1.md).
    +
    I am referencing a [document](doc1.md).
     

    Docusaurus currently does not support documents in nested folders; only in a flat folder structure. We are looking into adding support for nested folders.

    @@ -59,7 +59,7 @@

    New markdown files within docs will show up as pages on the website. Links to those documents are created first by using the id in the header of each document. If there is no id field, then the name of the file will serve as the link name.

    For example, creating an empty file such as docs/getting-started.md will enable the new page URL as /docs/getting-started.html.

    Suppose you add this to your document:

    -
    ---
    +
    ---
     id: intro
     title: Getting Started
     ---
    @@ -80,7 +80,7 @@
     

    Until you add your document to website/sidebars.json, they will only be accessible via a direct URL. The doc will not show up in any sidebar.

    Within sidebars.json, add the id you used in the document header to existing sidebar/category. In the below case, docs is the name of the sidebar and Getting Started is a category within the sidebar.

    -
    {
    +
    {
       "docs": {
         "Getting Started": [
           "getting-started"
    @@ -91,7 +91,7 @@
     }
     

    Or you can create a new category within the sidebar:

    -
    {
    +
    {
       "docs": {
         "My New Sidebar Category": [
           "getting-started"
    @@ -103,7 +103,7 @@
     

    Adding New Sidebars

    You can also put a document in a new sidebar. In the following example, we are creating an examples-sidebar sidebar within sidebars.json that has a category called My Example Category containing a document with an id of my-examples.

    -
    {
    +
    {
       "examples-sidebar": {
         "My Example Category": [
           "my-examples"
    @@ -118,7 +118,7 @@
     

    To expose sidebars, you will add clickable labels to the site navigation bar at the top of the website. You can add documents, pages and external links.

    Adding Documents

    After creating a new sidebar for the site by adding it to sidebars.json, you can expose the new sidebar from the top navigation bar by editing the headerLinks field of siteConfig.js.

    -
    {
    +
    {
       headerLinks: [
         ...
         { doc: 'my-examples', label: 'Examples' },
    @@ -130,7 +130,7 @@
     

    A label called Examples will be added to the site navigation bar and when you click on it at the top of your site, the examples-sidebar will be shown and the default document will be my-examples.

    Adding Custom Pages

    To add custom pages to the site navigation bar, entries can be added to the headerLinks of siteConfig.js. For example, if we have a page within website/pages/help.js, we can link to it by adding the following:

    -
    {
    +
    {
       headerLinks: [
         ...
         { page: 'help', label: 'Help' },
    @@ -142,7 +142,7 @@
     

    A label called Help will be added to the site navigation bar and when you click on it at the top of your site, the content from the help.js page will be shown.

    Adding External Links

    Custom links can be added to the site navigation bar with the following entry in siteConfig.js:

    -
    {
    +
    {
       headerLinks: [
         ...
         { href: 'https://github.com/facebook/Docusaurus', label: 'GitHub' },
    @@ -159,7 +159,7 @@
     

    You have limited control where the search and languages dropdown elements are shown in the site navigation bar at the top of your website.

    Search

    If search is enabled on your site, your search bar will appear to the right of your links. If you want to put the search bar between links in the header, add a search entry in the headerLinks config array:

    -
    {
    +
    {
       headerLinks: [
         { doc: 'foo', label: 'Foo' },
         { search: true },
    @@ -170,7 +170,7 @@
     

    Languages Dropdown

    If translations is enabled on your site, the language dropdown will appear to the right of your links (and to the left of the search bar, if search is enabled). If you want to put the language selection drop down between links in the header, add a languages entry in the headerLinks config array:

    -
    {
    +
    {
       headerLinks: [
         { doc: 'foo', label: 'Foo' },
         { languages: true },
    @@ -192,7 +192,7 @@
     

    These are two separate class names so you can have the active styles applied to either exact matches only or a bit more broadly for docs that belong together. If you don't want to make this distinction you can add both classes to the same CSS rule.

    Secondary On-Page Navigation

    We support secondary on-page navigation so you can more easily see the topics associated with a given document. To enable this feature, you need to add the onPageNav site configuration option to your siteConfig.js.

    -
    {
    +
    {
       onPageNav: 'separate',
       ...
     }
    diff --git a/docs/en/1.1.0/publishing.html b/docs/en/1.1.0/publishing.html
    index 843dfd17bf..93aebc6fe1 100644
    --- a/docs/en/1.1.0/publishing.html
    +++ b/docs/en/1.1.0/publishing.html
    @@ -50,7 +50,7 @@
             
    Edit

    Publishing your site

    You should now have a site up and running locally. Once you have customized it to your liking, it's time to publish it. Docusaurus generates a static HTML website that is ready to be served by your favorite web server or online hosting solution.

    Building Static HTML Pages

    To create a static build of your website, run the following script from the website directory:

    -
    yarn run build # or `npm run build`
    +
    yarn run build # or `npm run build`
     

    This will generate a build folder inside the website directory containing the .html files from all of your docs and other pages included in pages.

    Hosting Static HTML Pages

    @@ -110,7 +110,7 @@

    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:

    To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate. If you run into issues related to SSH keys, visit Github's authentication documentation.

    -
    GIT_USER=<GIT_USER> \
    +
    GIT_USER=<GIT_USER> \
       CURRENT_BRANCH=master \
       USE_SSH=true \
       yarn run publish-gh-pages # or `npm run publish-gh-pages`
    @@ -134,7 +134,7 @@
     
  • Create a .circleci folder and create a config.yml under that folder.
  • Copy the text below into .circleci/config.yml.
  • -
    # If you only want circle to run on direct commits to master, you can uncomment this out
    +
    # If you only want circle to run on direct commits to master, you can uncomment this out
     # and uncomment the filters: *filter-only-master down below too
     #
     # aliases:
    @@ -181,7 +181,7 @@
     
     

    Tips & Tricks

    When initially deploying to a gh-pages branch using Circle CI, you may notice that some jobs triggered by commits to the gh-pages 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:

    -
    # Circle CI 2.0 Config File
    +
    # Circle CI 2.0 Config File
     # This config file will prevent tests from being run on the gh-pages branch.
     version: 2
     jobs:
    diff --git a/docs/en/1.1.0/publishing/index.html b/docs/en/1.1.0/publishing/index.html
    index 843dfd17bf..93aebc6fe1 100644
    --- a/docs/en/1.1.0/publishing/index.html
    +++ b/docs/en/1.1.0/publishing/index.html
    @@ -50,7 +50,7 @@
             
    Edit

    Publishing your site

    You should now have a site up and running locally. Once you have customized it to your liking, it's time to publish it. Docusaurus generates a static HTML website that is ready to be served by your favorite web server or online hosting solution.

    Building Static HTML Pages

    To create a static build of your website, run the following script from the website directory:

    -
    yarn run build # or `npm run build`
    +
    yarn run build # or `npm run build`
     

    This will generate a build folder inside the website directory containing the .html files from all of your docs and other pages included in pages.

    Hosting Static HTML Pages

    @@ -110,7 +110,7 @@

    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:

    To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate. If you run into issues related to SSH keys, visit Github's authentication documentation.

    -
    GIT_USER=<GIT_USER> \
    +
    GIT_USER=<GIT_USER> \
       CURRENT_BRANCH=master \
       USE_SSH=true \
       yarn run publish-gh-pages # or `npm run publish-gh-pages`
    @@ -134,7 +134,7 @@
     
  • Create a .circleci folder and create a config.yml under that folder.
  • Copy the text below into .circleci/config.yml.
  • -
    # If you only want circle to run on direct commits to master, you can uncomment this out
    +
    # If you only want circle to run on direct commits to master, you can uncomment this out
     # and uncomment the filters: *filter-only-master down below too
     #
     # aliases:
    @@ -181,7 +181,7 @@
     
     

    Tips & Tricks

    When initially deploying to a gh-pages branch using Circle CI, you may notice that some jobs triggered by commits to the gh-pages 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:

    -
    # Circle CI 2.0 Config File
    +
    # Circle CI 2.0 Config File
     # This config file will prevent tests from being run on the gh-pages branch.
     version: 2
     jobs:
    diff --git a/docs/en/1.1.0/search.html b/docs/en/1.1.0/search.html
    index 4572d3f986..5d1e80fc7b 100644
    --- a/docs/en/1.1.0/search.html
    +++ b/docs/en/1.1.0/search.html
    @@ -51,7 +51,7 @@
     

    DocSearch works by crawling the content of your website every 24 hours and putting all the content in an Algolia index. This content is then queried directly from your front-end using the Algolia API. Note that your website need to be publicly available for this to work (ie. not behind a firewall). This service is free.

    Enabling the Search Bar

    Enter your API key and index name (sent by Algolia) into siteConfig.js in the algolia section to enable search for your site.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       algolia: {
         apiKey: 'my-api-key',
    @@ -65,7 +65,7 @@
     

    Controlling the Location of the Search Bar

    By default, the search bar will be the rightmost element in the top navigation bar.

    If you want to change the default location, add the searchBar flag in the headerLinks field of siteConfig.js in your desired location. For example, you may want the search bar between your internal and external links.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       headerLinks: [
         {...}
    diff --git a/docs/en/1.1.0/search/index.html b/docs/en/1.1.0/search/index.html
    index 4572d3f986..5d1e80fc7b 100644
    --- a/docs/en/1.1.0/search/index.html
    +++ b/docs/en/1.1.0/search/index.html
    @@ -51,7 +51,7 @@
     

    DocSearch works by crawling the content of your website every 24 hours and putting all the content in an Algolia index. This content is then queried directly from your front-end using the Algolia API. Note that your website need to be publicly available for this to work (ie. not behind a firewall). This service is free.

    Enabling the Search Bar

    Enter your API key and index name (sent by Algolia) into siteConfig.js in the algolia section to enable search for your site.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       algolia: {
         apiKey: 'my-api-key',
    @@ -65,7 +65,7 @@
     

    Controlling the Location of the Search Bar

    By default, the search bar will be the rightmost element in the top navigation bar.

    If you want to change the default location, add the searchBar flag in the headerLinks field of siteConfig.js in your desired location. For example, you may want the search bar between your internal and external links.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       headerLinks: [
         {...}
    diff --git a/docs/en/1.1.0/site-config.html b/docs/en/1.1.0/site-config.html
    index 1500248bc8..48c8c1fbbc 100644
    --- a/docs/en/1.1.0/site-config.html
    +++ b/docs/en/1.1.0/site-config.html
    @@ -66,7 +66,7 @@
     

    headerIcon - url for icon used in header navigation bar.

    headerLinks - Links that will be used in the header navigation bar. The label field of each object will be the link text and will also be translated for each language.

    Example Usage:

    -
    headerLinks: [
    +
    headerLinks: [
       // Links to document with id doc1 for current language/version
       { doc: "doc1", label: "Getting Started" },
       // Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language
    @@ -97,9 +97,9 @@
     

    blogSidebarCount - Control the number of blog posts that show up in the sidebar. See the adding a blog docs for more information.

    cname - The CNAME for your website. It will go into a CNAME file when your site it built.

    customDocsPath - By default, Docusaurus expects your documentation to be in a directory called docs. This directory is at the same level as the website directory (i.e., not inside the website directory). You can specify a custom path to your documentation with this field. Note that all of your documentation *.md files must still reside in a flat hierarchy. You cannot have your documents in nested directories.

    -
    customDocsPath: 'docs/site';
    +
    customDocsPath: 'docs/site';
     
    -
    customDocsPath: 'website-docs';
    +
    customDocsPath: 'website-docs';
     

    defaultVersionShown - The default version for the site to be shown. If this is not set, the latest version will be shown.

    disableHeaderTitle - 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 true.

    @@ -110,7 +110,7 @@

    facebookPixelId - Facebook Pixel ID to track page views.

    fonts - Font-family css configuration for the site. If a font family is specified in siteConfig.js as $myFont, then adding a myFont key to an array in fonts will allow you to configure the font. Items appearing earlier in the array will take priority of later elements, so ordering of the fonts matter.

    In the below example, we have two sets of font configurations, myFont and myOtherFont. Times New Roman is the preferred font in myFont. -apple-system is the preferred in myOtherFont.

    -
    fonts: {
    +
    fonts: {
       myFont: [
         'Times New Roman',
         'Serif'
    @@ -122,7 +122,7 @@
     },
     

    The above fonts would be represented in your CSS file(s) as variables $myFont and $myOtherFont.

    -
    h1 {
    +
    h1 {
       font-family: $myFont;
     }
     
    @@ -155,7 +155,7 @@

    wrapPagesHTML - Boolean flag to indicate whether html files in /pages should be wrapped with Docusaurus site styles, header and footer. This feature is experimental and relies on the files being html fragments instead of complete pages. It inserts the contents of your html file with no extra processing. Defaults to false.

    Users can also add their own custom fields if they wish to provide some data across different files.

    Example siteConfig.js with many available fields

    -
    const users = [
    +
    const users = [
       {
         caption: 'User1',
         image: '/test-site/img/docusaurus.svg',
    diff --git a/docs/en/1.1.0/site-config/index.html b/docs/en/1.1.0/site-config/index.html
    index 1500248bc8..48c8c1fbbc 100644
    --- a/docs/en/1.1.0/site-config/index.html
    +++ b/docs/en/1.1.0/site-config/index.html
    @@ -66,7 +66,7 @@
     

    headerIcon - url for icon used in header navigation bar.

    headerLinks - Links that will be used in the header navigation bar. The label field of each object will be the link text and will also be translated for each language.

    Example Usage:

    -
    headerLinks: [
    +
    headerLinks: [
       // Links to document with id doc1 for current language/version
       { doc: "doc1", label: "Getting Started" },
       // Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language
    @@ -97,9 +97,9 @@
     

    blogSidebarCount - Control the number of blog posts that show up in the sidebar. See the adding a blog docs for more information.

    cname - The CNAME for your website. It will go into a CNAME file when your site it built.

    customDocsPath - By default, Docusaurus expects your documentation to be in a directory called docs. This directory is at the same level as the website directory (i.e., not inside the website directory). You can specify a custom path to your documentation with this field. Note that all of your documentation *.md files must still reside in a flat hierarchy. You cannot have your documents in nested directories.

    -
    customDocsPath: 'docs/site';
    +
    customDocsPath: 'docs/site';
     
    -
    customDocsPath: 'website-docs';
    +
    customDocsPath: 'website-docs';
     

    defaultVersionShown - The default version for the site to be shown. If this is not set, the latest version will be shown.

    disableHeaderTitle - 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 true.

    @@ -110,7 +110,7 @@

    facebookPixelId - Facebook Pixel ID to track page views.

    fonts - Font-family css configuration for the site. If a font family is specified in siteConfig.js as $myFont, then adding a myFont key to an array in fonts will allow you to configure the font. Items appearing earlier in the array will take priority of later elements, so ordering of the fonts matter.

    In the below example, we have two sets of font configurations, myFont and myOtherFont. Times New Roman is the preferred font in myFont. -apple-system is the preferred in myOtherFont.

    -
    fonts: {
    +
    fonts: {
       myFont: [
         'Times New Roman',
         'Serif'
    @@ -122,7 +122,7 @@
     },
     

    The above fonts would be represented in your CSS file(s) as variables $myFont and $myOtherFont.

    -
    h1 {
    +
    h1 {
       font-family: $myFont;
     }
     
    @@ -155,7 +155,7 @@

    wrapPagesHTML - Boolean flag to indicate whether html files in /pages should be wrapped with Docusaurus site styles, header and footer. This feature is experimental and relies on the files being html fragments instead of complete pages. It inserts the contents of your html file with no extra processing. Defaults to false.

    Users can also add their own custom fields if they wish to provide some data across different files.

    Example siteConfig.js with many available fields

    -
    const users = [
    +
    const users = [
       {
         caption: 'User1',
         image: '/test-site/img/docusaurus.svg',
    diff --git a/docs/en/1.1.0/site-creation.html b/docs/en/1.1.0/site-creation.html
    index c3d07ee8ff..f4951feec5 100644
    --- a/docs/en/1.1.0/site-creation.html
    +++ b/docs/en/1.1.0/site-creation.html
    @@ -51,7 +51,7 @@
     

    After installation and preparation, much of the work to create a basic site for your docs is already complete.

    Site Structure

    Your site structure looks like the following:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs
     ├── website
     │   ├── blog
    @@ -75,7 +75,7 @@
     

    To create a fully functional site, you only need to do a few steps:

    1. Add your documentation to the /docs folder as .md files, ensuring you have the proper header in each file. The simplest header would be the following, where id is the link name (e.g., docs/intro.html) and the title, is, of course, the title of the browser page.

      -
      ---
      +
      ---
       id: intro
       title: Getting Started
       ---
      @@ -93,7 +93,7 @@
       
    2. Place assets, such as images, in the website/static/ folder.
    3. Run the site to see the results of your changes.
    -
    cd website
    +
    cd website
     yarn run start # or `npm run start`
     # Navigate to http://localhost:3000
     
    @@ -104,7 +104,7 @@ yarn run start # or `npm run start`
  • Remove the index.js file from the website/pages directory, if it exists.
  • Add a custom static index.html page in the website/static folder with the following contents:
  • -
    <!DOCTYPE HTML>
    +
    <!DOCTYPE HTML>
     <html lang="en-US">
       <head>
         <meta charset="UTF-8">
    diff --git a/docs/en/1.1.0/site-creation/index.html b/docs/en/1.1.0/site-creation/index.html
    index c3d07ee8ff..f4951feec5 100644
    --- a/docs/en/1.1.0/site-creation/index.html
    +++ b/docs/en/1.1.0/site-creation/index.html
    @@ -51,7 +51,7 @@
     

    After installation and preparation, much of the work to create a basic site for your docs is already complete.

    Site Structure

    Your site structure looks like the following:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs
     ├── website
     │   ├── blog
    @@ -75,7 +75,7 @@
     

    To create a fully functional site, you only need to do a few steps:

    1. Add your documentation to the /docs folder as .md files, ensuring you have the proper header in each file. The simplest header would be the following, where id is the link name (e.g., docs/intro.html) and the title, is, of course, the title of the browser page.

      -
      ---
      +
      ---
       id: intro
       title: Getting Started
       ---
      @@ -93,7 +93,7 @@
       
    2. Place assets, such as images, in the website/static/ folder.
    3. Run the site to see the results of your changes.
    -
    cd website
    +
    cd website
     yarn run start # or `npm run start`
     # Navigate to http://localhost:3000
     
    @@ -104,7 +104,7 @@ yarn run start # or `npm run start`
  • Remove the index.js file from the website/pages directory, if it exists.
  • Add a custom static index.html page in the website/static folder with the following contents:
  • -
    <!DOCTYPE HTML>
    +
    <!DOCTYPE HTML>
     <html lang="en-US">
       <head>
         <meta charset="UTF-8">
    diff --git a/docs/en/1.1.0/site-preparation.html b/docs/en/1.1.0/site-preparation.html
    index b1a77a20b0..1151eb275a 100644
    --- a/docs/en/1.1.0/site-preparation.html
    +++ b/docs/en/1.1.0/site-preparation.html
    @@ -50,7 +50,7 @@
             
    Edit

    Site Preparation

    After installing Docusaurus, 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.

    Directory Structure

    As shown after you installed Docusaurus, the initialization script created a directory structure similar to:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs-examples-from-docusaurus
     │   ├── doc1.md
     │   ├── doc2.md
    diff --git a/docs/en/1.1.0/site-preparation/index.html b/docs/en/1.1.0/site-preparation/index.html
    index b1a77a20b0..1151eb275a 100644
    --- a/docs/en/1.1.0/site-preparation/index.html
    +++ b/docs/en/1.1.0/site-preparation/index.html
    @@ -50,7 +50,7 @@
             
    Edit

    Site Preparation

    After installing Docusaurus, 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.

    Directory Structure

    As shown after you installed Docusaurus, the initialization script created a directory structure similar to:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs-examples-from-docusaurus
     │   ├── doc1.md
     │   ├── doc2.md
    diff --git a/docs/en/1.1.0/translation.html b/docs/en/1.1.0/translation.html
    index 4c7cceb212..add261bd5f 100644
    --- a/docs/en/1.1.0/translation.html
    +++ b/docs/en/1.1.0/translation.html
    @@ -50,13 +50,13 @@
             
    Edit

    Translations & Localization

    Docusaurus allows for easy translation functionality using Crowdin. Documentation files written in English are uploaded to Crowdin for translation by users within a community. Top-level pages written with English strings can be translated by wrapping any strings you want to translate in a <translate> tag. Other titles and labels will also be found and properly translated.

    Docusaurus Translation Configurations

    To generate example files for translations with Docusaurus, run the examples script with the command line argument translations:

    -
    npm run examples translations
    +
    npm run examples translations
     

    or

    -
    yarn examples translations
    +
    yarn examples translations
     

    This will create the following files:

    -
    pages/en/help-with-translations.js
    +
    pages/en/help-with-translations.js
     languages.js
     ../crowdin.yaml
     
    @@ -76,7 +76,7 @@ languages.js

    Pages allow you to customize layout and specific content of pages like a custom index page or help page.

    Pages with text that you want translated should be placed in website/pages/en folder.

    Wrap strings you want translated in a <translate> tag, and add the following require statement to the top of the file:

    -
    ...
    +
    ...
     const translate = require('../../server/translate.js').translate;
     ...
     <h2>
    @@ -85,7 +85,7 @@ languages.js
     ...
     

    You can also include an optional description attribute to give more context to a translator about how to translate the string:

    -
    <p>
    +
    <p>
       <translate desc="flower, not verb">Rose</translate>
     <p>
     
    @@ -95,7 +95,7 @@ languages.js

    Gathering Strings to Translate

    The strings within localized Pages must be extracted and provided to Crowdin.

    Add the following script to your website/package.json file, if it does not exist already:

    -
    {
    +
    {
       ...
       "scripts": {
         "write-translations": "docusaurus-write-translations"
    @@ -135,7 +135,7 @@ languages.js
     
     

    The example below can be automatically generated by the Docusaurus cli with the examples script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.

    Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.

    -
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
    +
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
     api_key_env: CROWDIN_DOCUSAURUS_API_KEY
     base_path: "./"
     preserve_hierarchy: true
    @@ -160,14 +160,14 @@ languages.js
     

    Setup the Crowdin Scripts

    You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in /docs as well as translatable strings in website/i18n/en.json. (These strings can be generated by running yarn write-translations.)

    You can add the following to your package.json to manually trigger Crowdin.

    -
    "scripts": {
    +
    "scripts": {
       "crowdin-upload": "crowdin --config ../crowdin.yaml upload sources --auto-update -b master",
       "crowdin-download": "crowdin --config ../crowdin.yaml download -b master"
     },
     

    Manual File Sync

    You will always want to upload your markdown files and translatable strings first and the download the translations section. So run the commands in this order:

    -
    CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-upload
    +
    CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-upload
     CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-download
     
    @@ -185,7 +185,7 @@ CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY

    Automated File Sync Using CircleCI

    You can automate pulling down and uploading translations for your files using the CircleCI web continuous integration service.

    First, update the circle.yml 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 circle.yml file:

    -
    machine:
    +
    machine:
       node:
         version: 6.10.3
       npm:
    @@ -221,7 +221,7 @@ CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY
     

    If you wish to use Crowdin on your machine locally, you can install the Crowdin CLI tool and run the same commands found in the circle.yaml file. The only difference is that you must set project_identifier and api_key values in the crowdin.yaml file since you will not have Circle environment variables set up.

    Versioned Translations

    If you wish to have translation and versioning for your documentation, add the following section to the end of your crowdin.yaml file:

    -
      -
    +
      -
         source: '/website/versioned_docs/**/*.md'
         translation: '/website/translated_docs/%locale%/**/%original_file_name%'
         languages_mapping: *anchor
    diff --git a/docs/en/1.1.0/translation/index.html b/docs/en/1.1.0/translation/index.html
    index 4c7cceb212..add261bd5f 100644
    --- a/docs/en/1.1.0/translation/index.html
    +++ b/docs/en/1.1.0/translation/index.html
    @@ -50,13 +50,13 @@
             
    Edit

    Translations & Localization

    Docusaurus allows for easy translation functionality using Crowdin. Documentation files written in English are uploaded to Crowdin for translation by users within a community. Top-level pages written with English strings can be translated by wrapping any strings you want to translate in a <translate> tag. Other titles and labels will also be found and properly translated.

    Docusaurus Translation Configurations

    To generate example files for translations with Docusaurus, run the examples script with the command line argument translations:

    -
    npm run examples translations
    +
    npm run examples translations
     

    or

    -
    yarn examples translations
    +
    yarn examples translations
     

    This will create the following files:

    -
    pages/en/help-with-translations.js
    +
    pages/en/help-with-translations.js
     languages.js
     ../crowdin.yaml
     
    @@ -76,7 +76,7 @@ languages.js

    Pages allow you to customize layout and specific content of pages like a custom index page or help page.

    Pages with text that you want translated should be placed in website/pages/en folder.

    Wrap strings you want translated in a <translate> tag, and add the following require statement to the top of the file:

    -
    ...
    +
    ...
     const translate = require('../../server/translate.js').translate;
     ...
     <h2>
    @@ -85,7 +85,7 @@ languages.js
     ...
     

    You can also include an optional description attribute to give more context to a translator about how to translate the string:

    -
    <p>
    +
    <p>
       <translate desc="flower, not verb">Rose</translate>
     <p>
     
    @@ -95,7 +95,7 @@ languages.js

    Gathering Strings to Translate

    The strings within localized Pages must be extracted and provided to Crowdin.

    Add the following script to your website/package.json file, if it does not exist already:

    -
    {
    +
    {
       ...
       "scripts": {
         "write-translations": "docusaurus-write-translations"
    @@ -135,7 +135,7 @@ languages.js
     
     

    The example below can be automatically generated by the Docusaurus cli with the examples script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.

    Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.

    -
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
    +
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
     api_key_env: CROWDIN_DOCUSAURUS_API_KEY
     base_path: "./"
     preserve_hierarchy: true
    @@ -160,14 +160,14 @@ languages.js
     

    Setup the Crowdin Scripts

    You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in /docs as well as translatable strings in website/i18n/en.json. (These strings can be generated by running yarn write-translations.)

    You can add the following to your package.json to manually trigger Crowdin.

    -
    "scripts": {
    +
    "scripts": {
       "crowdin-upload": "crowdin --config ../crowdin.yaml upload sources --auto-update -b master",
       "crowdin-download": "crowdin --config ../crowdin.yaml download -b master"
     },
     

    Manual File Sync

    You will always want to upload your markdown files and translatable strings first and the download the translations section. So run the commands in this order:

    -
    CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-upload
    +
    CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-upload
     CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-download
     
    @@ -185,7 +185,7 @@ CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY

    Automated File Sync Using CircleCI

    You can automate pulling down and uploading translations for your files using the CircleCI web continuous integration service.

    First, update the circle.yml 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 circle.yml file:

    -
    machine:
    +
    machine:
       node:
         version: 6.10.3
       npm:
    @@ -221,7 +221,7 @@ CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY
     

    If you wish to use Crowdin on your machine locally, you can install the Crowdin CLI tool and run the same commands found in the circle.yaml file. The only difference is that you must set project_identifier and api_key values in the crowdin.yaml file since you will not have Circle environment variables set up.

    Versioned Translations

    If you wish to have translation and versioning for your documentation, add the following section to the end of your crowdin.yaml file:

    -
      -
    +
      -
         source: '/website/versioned_docs/**/*.md'
         translation: '/website/translated_docs/%locale%/**/%original_file_name%'
         languages_mapping: *anchor
    diff --git a/docs/en/1.1.0/versioning.html b/docs/en/1.1.0/versioning.html
    index 69dc496766..72efd1f659 100644
    --- a/docs/en/1.1.0/versioning.html
    +++ b/docs/en/1.1.0/versioning.html
    @@ -50,19 +50,19 @@
             
    Edit

    Versioning

    You can use the version script to cut a new documentation version based on the latest content in the docs folder. That specific set of documentation will then be preserved and accessible even as the documentation in the docs folder changes moving forward.

    How to Create New Versions

    Run the following script to generate a starter versions page listing all the site versions:

    -
    yarn examples versions
    +
    yarn examples versions
     

    This creates the pages/en/versions.js file.

    You can edit this file later on to customize how you display the versions.

    Add the following script to your package.json file if it doesn't already exist:

    -
    ...
    +
    ...
     "scripts": {
       "version": "docusaurus-version"
     },
     ...
     

    Run the script with a command line argument of the version you wish to create. e.g.,

    -
    yarn run version 1.0.0
    +
    yarn run version 1.0.0
     

    This will preserve all documents currently in the docs folder and make them available as documentation for version 1.0.0.

    If, for example, you ran the version script with 1.0.0 as the version number, version 1.0.0 is considered the latest release version for your project. 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.

    @@ -93,14 +93,14 @@

    For example, a document with the original id doc1 exists for the latest version, 1.0.0, and has the same content as the document with the id doc1 in the docs folder. When a new version 2.0.0 is created, the file for doc1 will not be copied into versioned_docs/version-2.0.0/. There will still be a page for docs/2.0.0/doc1.html, but it will use the file from version 1.0.0.

    Renaming Existing Versions

    To rename an existing version number to something else, first make sure the following script is in your package.json file:

    -
    ...
    +
    ...
     "scripts": {
       "rename-version": "docusaurus-rename-version"
     },
     ...
     

    Run the script with command line arguments of first, the current version name, then second, the new version name. e.g.,

    -
    yarn run rename-version 1.0.0 1.0.1
    +
    yarn run rename-version 1.0.0 1.0.1
     

    Versioning and Translations

    If you wish to use versioning and translations features, the crowdin.yaml 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 translated_docs/${language}/version-${version}/. For more information, check out the translations guide.

    diff --git a/docs/en/1.1.0/versioning/index.html b/docs/en/1.1.0/versioning/index.html index 69dc496766..72efd1f659 100644 --- a/docs/en/1.1.0/versioning/index.html +++ b/docs/en/1.1.0/versioning/index.html @@ -50,19 +50,19 @@
    Edit

    Versioning

    You can use the version script to cut a new documentation version based on the latest content in the docs folder. That specific set of documentation will then be preserved and accessible even as the documentation in the docs folder changes moving forward.

    How to Create New Versions

    Run the following script to generate a starter versions page listing all the site versions:

    -
    yarn examples versions
    +
    yarn examples versions
     

    This creates the pages/en/versions.js file.

    You can edit this file later on to customize how you display the versions.

    Add the following script to your package.json file if it doesn't already exist:

    -
    ...
    +
    ...
     "scripts": {
       "version": "docusaurus-version"
     },
     ...
     

    Run the script with a command line argument of the version you wish to create. e.g.,

    -
    yarn run version 1.0.0
    +
    yarn run version 1.0.0
     

    This will preserve all documents currently in the docs folder and make them available as documentation for version 1.0.0.

    If, for example, you ran the version script with 1.0.0 as the version number, version 1.0.0 is considered the latest release version for your project. 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.

    @@ -93,14 +93,14 @@

    For example, a document with the original id doc1 exists for the latest version, 1.0.0, and has the same content as the document with the id doc1 in the docs folder. When a new version 2.0.0 is created, the file for doc1 will not be copied into versioned_docs/version-2.0.0/. There will still be a page for docs/2.0.0/doc1.html, but it will use the file from version 1.0.0.

    Renaming Existing Versions

    To rename an existing version number to something else, first make sure the following script is in your package.json file:

    -
    ...
    +
    ...
     "scripts": {
       "rename-version": "docusaurus-rename-version"
     },
     ...
     

    Run the script with command line arguments of first, the current version name, then second, the new version name. e.g.,

    -
    yarn run rename-version 1.0.0 1.0.1
    +
    yarn run rename-version 1.0.0 1.0.1
     

    Versioning and Translations

    If you wish to use versioning and translations features, the crowdin.yaml 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 translated_docs/${language}/version-${version}/. For more information, check out the translations guide.

    diff --git a/docs/en/1.1.1/api-pages.html b/docs/en/1.1.1/api-pages.html index c62c6c876f..b735f6d561 100644 --- a/docs/en/1.1.1/api-pages.html +++ b/docs/en/1.1.1/api-pages.html @@ -59,7 +59,7 @@

    CompLibrary.MarkdownBlock

    A React component that parses markdown and renders to HTML.

    Example:

    -
    const MarkdownBlock = CompLibrary.MarkdownBlock;
    +
    const MarkdownBlock = CompLibrary.MarkdownBlock;
     
     <MarkdownBlock>
       [Markdown syntax for a link](http://www.example.com)
    @@ -79,7 +79,7 @@
     
     
     

    Example

    -
    <Container
    +
    <Container
       padding={['bottom', 'top']}
       background="light"
       className="myCustomClass">
    @@ -115,7 +115,7 @@
     
     
     

    Example

    -
    <GridBlock
    +
    <GridBlock
       align="center"
       layout="threeColumn"
       className="myCustomClass"
    @@ -144,19 +144,19 @@
     

    Translating Strings

    When translations are enabled, any pages inside website/pages/en will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the languages.js file. E.g. The url for a French page of website/pages/en/help.js would be found at ${baseUrl}fr/help.html.

    When writing pages that you wish to translate, wrap any strings to be translated inside a <translate> tag. e.g.,

    -
    <p>
    +
    <p>
       <translate>I like translations</translate>
     </p>
     

    You can also provide an optional description attribute to provide context for translators. e.g,

    -
    <a href="/community">
    +
    <a href="/community">
       <translate desc="Footer link to page referring to community GitHub and Slack">
         Community
       </translate>
     </a>
     

    Add the following require statement as well:

    -
    const translate = require('../../server/translate.js').translate;
    +
    const translate = require('../../server/translate.js').translate;
     

    Note that this path is valid for files inside pages/en and should be adjusted accordingly if files are in different locations, as discussed above.

    Using Static Assets

    diff --git a/docs/en/1.1.1/api-pages/index.html b/docs/en/1.1.1/api-pages/index.html index c62c6c876f..b735f6d561 100644 --- a/docs/en/1.1.1/api-pages/index.html +++ b/docs/en/1.1.1/api-pages/index.html @@ -59,7 +59,7 @@

    CompLibrary.MarkdownBlock

    A React component that parses markdown and renders to HTML.

    Example:

    -
    const MarkdownBlock = CompLibrary.MarkdownBlock;
    +
    const MarkdownBlock = CompLibrary.MarkdownBlock;
     
     <MarkdownBlock>
       [Markdown syntax for a link](http://www.example.com)
    @@ -79,7 +79,7 @@
     
     
     

    Example

    -
    <Container
    +
    <Container
       padding={['bottom', 'top']}
       background="light"
       className="myCustomClass">
    @@ -115,7 +115,7 @@
     
     
     

    Example

    -
    <GridBlock
    +
    <GridBlock
       align="center"
       layout="threeColumn"
       className="myCustomClass"
    @@ -144,19 +144,19 @@
     

    Translating Strings

    When translations are enabled, any pages inside website/pages/en will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the languages.js file. E.g. The url for a French page of website/pages/en/help.js would be found at ${baseUrl}fr/help.html.

    When writing pages that you wish to translate, wrap any strings to be translated inside a <translate> tag. e.g.,

    -
    <p>
    +
    <p>
       <translate>I like translations</translate>
     </p>
     

    You can also provide an optional description attribute to provide context for translators. e.g,

    -
    <a href="/community">
    +
    <a href="/community">
       <translate desc="Footer link to page referring to community GitHub and Slack">
         Community
       </translate>
     </a>
     

    Add the following require statement as well:

    -
    const translate = require('../../server/translate.js').translate;
    +
    const translate = require('../../server/translate.js').translate;
     

    Note that this path is valid for files inside pages/en and should be adjusted accordingly if files are in different locations, as discussed above.

    Using Static Assets

    diff --git a/docs/en/1.1.1/blog.html b/docs/en/1.1.1/blog.html index 22996d4169..c388f9deba 100644 --- a/docs/en/1.1.1/blog.html +++ b/docs/en/1.1.1/blog.html @@ -50,7 +50,7 @@
    Edit

    Adding a Blog

    Initial Setup

    To setup your site's blog, start by creating a blog folder within your repo's website directory.

    Then, add a header link to your blog within siteConfig.js:

    -
    headerLinks: [
    +
    headerLinks: [
         ...
         { blog: true, label: 'Blog' },
         ...
    @@ -59,7 +59,7 @@
     

    Adding Posts

    To publish in the blog, create a file within the blog folder with a formatted name of YYYY-MM-DD-My-Blog-Post-Title.md. The post date is extracted from the file name.

    For example, at website/blog/2017-08-18-Introducing-Docusaurus.md:

    -
    ---
    +
    ---
     author: Frank Li
     authorURL: https://twitter.com/foobarbaz
     authorFBID: 503283835
    @@ -79,7 +79,7 @@
     
     

    Summary Truncation

    Use the <!--truncate--> marker in your blog post to represent what will be shown as the summary when viewing all blog published blog posts. Anything above <!--truncate--> will be part of the summary. For example:

    -
    ---
    +
    ---
     title: Truncation Example
     ---
     
    @@ -100,7 +100,7 @@
     

    You can configure a specific amount of blog posts to show by adding a blogSidebarCount setting to your siteConfig.js.

    The available options are an integer representing the number of posts you wish to show or a string with the value 'ALL'.

    Example:

    -
    blogSidebarCount: 'ALL'
    +
    blogSidebarCount: 'ALL'
     

    RSS Feed

    Docusaurus provides a simple RSS feed for your blog posts. Both RSS and Atom feed formats are supported. This data is automatically to your website page's HTML tag.

    @@ -121,7 +121,7 @@

    Now, when Docusaurus generates or builds your site, it will copy the file from static/index.html 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 /blog.

    You can use this template:

    -
    <!DOCTYPE HTML>
    +
    <!DOCTYPE HTML>
     <html lang="en-US">
       <head>
         <meta charset="UTF-8">
    diff --git a/docs/en/1.1.1/blog/index.html b/docs/en/1.1.1/blog/index.html
    index 22996d4169..c388f9deba 100644
    --- a/docs/en/1.1.1/blog/index.html
    +++ b/docs/en/1.1.1/blog/index.html
    @@ -50,7 +50,7 @@
             
    Edit

    Adding a Blog

    Initial Setup

    To setup your site's blog, start by creating a blog folder within your repo's website directory.

    Then, add a header link to your blog within siteConfig.js:

    -
    headerLinks: [
    +
    headerLinks: [
         ...
         { blog: true, label: 'Blog' },
         ...
    @@ -59,7 +59,7 @@
     

    Adding Posts

    To publish in the blog, create a file within the blog folder with a formatted name of YYYY-MM-DD-My-Blog-Post-Title.md. The post date is extracted from the file name.

    For example, at website/blog/2017-08-18-Introducing-Docusaurus.md:

    -
    ---
    +
    ---
     author: Frank Li
     authorURL: https://twitter.com/foobarbaz
     authorFBID: 503283835
    @@ -79,7 +79,7 @@
     
     

    Summary Truncation

    Use the <!--truncate--> marker in your blog post to represent what will be shown as the summary when viewing all blog published blog posts. Anything above <!--truncate--> will be part of the summary. For example:

    -
    ---
    +
    ---
     title: Truncation Example
     ---
     
    @@ -100,7 +100,7 @@
     

    You can configure a specific amount of blog posts to show by adding a blogSidebarCount setting to your siteConfig.js.

    The available options are an integer representing the number of posts you wish to show or a string with the value 'ALL'.

    Example:

    -
    blogSidebarCount: 'ALL'
    +
    blogSidebarCount: 'ALL'
     

    RSS Feed

    Docusaurus provides a simple RSS feed for your blog posts. Both RSS and Atom feed formats are supported. This data is automatically to your website page's HTML tag.

    @@ -121,7 +121,7 @@

    Now, when Docusaurus generates or builds your site, it will copy the file from static/index.html 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 /blog.

    You can use this template:

    -
    <!DOCTYPE HTML>
    +
    <!DOCTYPE HTML>
     <html lang="en-US">
       <head>
         <meta charset="UTF-8">
    diff --git a/docs/en/1.1.1/commands.html b/docs/en/1.1.1/commands.html
    index 7fe7e384af..40fa08ede5 100644
    --- a/docs/en/1.1.1/commands.html
    +++ b/docs/en/1.1.1/commands.html
    @@ -54,18 +54,18 @@
     
     

    Running from the command line

    The scripts can be run using either Yarn or npm. If you've already gone through our Getting Started guide, you may already be familiar with the start command. It's the command that tells Docusaurus to run the docusaurus-start script which generates the site and starts up a server, and it's usually invoked like so:

    -
    yarn run start
    +
    yarn run start
     

    The same script can be invoked using npm:

    -
    npm run start
    +
    npm run start
     

    To run a particular script, just replace the start command in the examples above with the command associated with your script.

    Using arguments

    Some commands support optional arguments. For example, to start a server on port 8080, you can specify the --port argument when running start:

    -
    yarn run start --port 8080
    +
    yarn run start --port 8080
     

    If you run Docusaurus using npm, you can still use the command line arguments by inserting a -- between npm run <command> and the command arguments:

    -
    npm run start -- --port 8080
    +
    npm run start -- --port 8080
     

    Configuration

    These scripts are set up under the "scripts" key in your website/package.json file as part of the installation process. If you need help setting them up again, please refer to the Installation guide.

    @@ -106,7 +106,7 @@

    Example

    -
    docusaurus-examples <feature>
    +
    docusaurus-examples <feature>
     

    When no feature is specified, sets up a minimally configured example website in your project. This command is covered in depth in the Site Preparation guide.


    @@ -119,7 +119,7 @@
  • USE_SSH: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.
  • Example

    -
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
    +
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
     

    The following environment variables are set by CircleCI during the build process.

      @@ -146,7 +146,7 @@

      Example

      -
      docusaurus-rename-version <currentVersion> <newVersion>
      +
      docusaurus-rename-version <currentVersion> <newVersion>
       

      See the Versioning guide to learn more.


      diff --git a/docs/en/1.1.1/commands/index.html b/docs/en/1.1.1/commands/index.html index 7fe7e384af..40fa08ede5 100644 --- a/docs/en/1.1.1/commands/index.html +++ b/docs/en/1.1.1/commands/index.html @@ -54,18 +54,18 @@

    Running from the command line

    The scripts can be run using either Yarn or npm. If you've already gone through our Getting Started guide, you may already be familiar with the start command. It's the command that tells Docusaurus to run the docusaurus-start script which generates the site and starts up a server, and it's usually invoked like so:

    -
    yarn run start
    +
    yarn run start
     

    The same script can be invoked using npm:

    -
    npm run start
    +
    npm run start
     

    To run a particular script, just replace the start command in the examples above with the command associated with your script.

    Using arguments

    Some commands support optional arguments. For example, to start a server on port 8080, you can specify the --port argument when running start:

    -
    yarn run start --port 8080
    +
    yarn run start --port 8080
     

    If you run Docusaurus using npm, you can still use the command line arguments by inserting a -- between npm run <command> and the command arguments:

    -
    npm run start -- --port 8080
    +
    npm run start -- --port 8080
     

    Configuration

    These scripts are set up under the "scripts" key in your website/package.json file as part of the installation process. If you need help setting them up again, please refer to the Installation guide.

    @@ -106,7 +106,7 @@

    Example

    -
    docusaurus-examples <feature>
    +
    docusaurus-examples <feature>
     

    When no feature is specified, sets up a minimally configured example website in your project. This command is covered in depth in the Site Preparation guide.


    @@ -119,7 +119,7 @@
  • USE_SSH: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.
  • Example

    -
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
    +
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
     

    The following environment variables are set by CircleCI during the build process.

      @@ -146,7 +146,7 @@

      Example

      -
      docusaurus-rename-version <currentVersion> <newVersion>
      +
      docusaurus-rename-version <currentVersion> <newVersion>
       

      See the Versioning guide to learn more.


      diff --git a/docs/en/1.1.1/custom-pages.html b/docs/en/1.1.1/custom-pages.html index 3dda67d7d5..3998b40688 100644 --- a/docs/en/1.1.1/custom-pages.html +++ b/docs/en/1.1.1/custom-pages.html @@ -53,7 +53,7 @@

      You can start your local server and go to http://localhost:3000 to see what the example home page looks like. From there, edit the website/pages/en/index.js file and its various components to use the images and text you want for your project.

      Adding Other Custom Pages

      Docusaurus provides some simple example pages in the website/pages/en directory, including index.js, users.js, and help.js. These are good examples to showcase how to create a custom page for Docusaurus.

      -
      root-of-repo
      +
      root-of-repo
       ├── docs
       ├── website
       │   ├── blog
      @@ -85,7 +85,7 @@
       

      Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.

      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.

      If you do not want a footer for your site, change the render function of core/Footer.js to return null. e.g.,

      -
      const React = require('react');
      +
      const React = require('react');
       
       class Footer extends React.Component {
         render() {
      diff --git a/docs/en/1.1.1/custom-pages/index.html b/docs/en/1.1.1/custom-pages/index.html
      index 3dda67d7d5..3998b40688 100644
      --- a/docs/en/1.1.1/custom-pages/index.html
      +++ b/docs/en/1.1.1/custom-pages/index.html
      @@ -53,7 +53,7 @@
       

      You can start your local server and go to http://localhost:3000 to see what the example home page looks like. From there, edit the website/pages/en/index.js file and its various components to use the images and text you want for your project.

      Adding Other Custom Pages

      Docusaurus provides some simple example pages in the website/pages/en directory, including index.js, users.js, and help.js. These are good examples to showcase how to create a custom page for Docusaurus.

      -
      root-of-repo
      +
      root-of-repo
       ├── docs
       ├── website
       │   ├── blog
      @@ -85,7 +85,7 @@
       

      Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.

      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.

      If you do not want a footer for your site, change the render function of core/Footer.js to return null. e.g.,

      -
      const React = require('react');
      +
      const React = require('react');
       
       class Footer extends React.Component {
         render() {
      diff --git a/docs/en/1.1.1/doc-markdown.html b/docs/en/1.1.1/doc-markdown.html
      index 764ba6fb3e..1587de594b 100644
      --- a/docs/en/1.1.1/doc-markdown.html
      +++ b/docs/en/1.1.1/doc-markdown.html
      @@ -55,7 +55,7 @@
       

      hide_title: Whether to hide the title at the top of the doc.

      sidebar_label: The text shown in the document sidebar for this document. If this field is not present, the document's sidebar_label will default to its title.

      For example:

      -
      ---
      +
      ---
       id: doc1
       title: My Document
       sidebar_label: Document
      @@ -63,7 +63,7 @@
       

      Versioned documents have their ids altered to include the version number when they get copied. The new id is version-${version}-${id} where ${version} is the version number of that document and ${id} is the original id. Additionally, versioned documents get an added original_id field with the original document id.

      For example:

      -
      ---
      +
      ---
       id: version-1.0.0-doc1
       title: My Document
       sidebar_label: Document
      @@ -72,7 +72,7 @@
       

      custom_edit_url: The url for editing this document. If this field is not present, the document's edit url will fallback to editUrl from optional fields of siteConfig.js. See siteConfig.js docs for more information.

      For example:

      -
      ---
      +
      ---
       id: doc-markdown
       title: Markdown Features
       custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
      @@ -85,7 +85,7 @@
       

      authorURL: 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.

      authorFBID: 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.

      For example:

      -
      ---
      +
      ---
       title: My First Blog Post
       author: Frank Li
       authorURL: http://twitter.com/franchementli
      @@ -97,20 +97,20 @@
       

      Linking other Documents

      You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.

      Example:

      -
      [This links to another document](other-document.md)
      +
      [This links to another document](other-document.md)
       

      This markdown will automatically get converted into a link to /docs/other-document.html (or the appropriately translated/versioned link) once it gets rendered.

      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.

      Linking to Images and Other Assets

      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 docs/assets and website/blog/assets, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.

      Example:

      -
      ![alt-text](/docs/assets/doc-image.png)
      +
      ![alt-text](/docs/assets/doc-image.png)
       

      Generating Table of Contents

      You can make an autogenerated list of links, which can be useful as a table of contents for API docs.

      In your markdown file, insert a line with the text <AUTOGENERATED_TABLE_OF_CONTENTS>. Write your documentation using h3 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 <AUTOGENERATED_TABLE_OF_CONTENTS>.

      Example:

      -
      ### `docusaurus.function(a, b)`
      +
      ### `docusaurus.function(a, b)`
       
       Text describing my function
       
      @@ -119,7 +119,7 @@ Text describing my function
       Text describing my function
       

      will lead to a table of contents of the functions:

      -
      - `docusaurus.function(a, b)`
      +
      - `docusaurus.function(a, b)`
       - `docdoc(file)`
       

      and each function will link to their corresponding sections in the page.

      @@ -133,13 +133,13 @@ ReactDOM.render( ```

      ...would be rendered with syntax highlighting like so:

      -
      ReactDOM.render(
      +
      ReactDOM.render(
         <h1>Hello, world!</h1>,
         document.getElementById('root')
       );
       

      Highlighting is provided by Highlight.js using the theme specified in your siteConfig.js file as part of the highlight key:

      -
      {
      +
      {
         ...
         highlight: {
           theme: 'default'
      @@ -150,7 +150,7 @@ ReactDOM.render(
       

      You can find the full list of supported themes in the Highlight.js styles directory.

      Registering additional languages

      While Highlight.js provides support for many popular languages out of the box, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the hljs constant as part of the highlight config key. This in turn allows you to call registerLanguage:

      -
      {
      +
      {
         ...
         highlight: {
           theme: 'default',
      diff --git a/docs/en/1.1.1/doc-markdown/index.html b/docs/en/1.1.1/doc-markdown/index.html
      index 764ba6fb3e..1587de594b 100644
      --- a/docs/en/1.1.1/doc-markdown/index.html
      +++ b/docs/en/1.1.1/doc-markdown/index.html
      @@ -55,7 +55,7 @@
       

      hide_title: Whether to hide the title at the top of the doc.

      sidebar_label: The text shown in the document sidebar for this document. If this field is not present, the document's sidebar_label will default to its title.

      For example:

      -
      ---
      +
      ---
       id: doc1
       title: My Document
       sidebar_label: Document
      @@ -63,7 +63,7 @@
       

      Versioned documents have their ids altered to include the version number when they get copied. The new id is version-${version}-${id} where ${version} is the version number of that document and ${id} is the original id. Additionally, versioned documents get an added original_id field with the original document id.

      For example:

      -
      ---
      +
      ---
       id: version-1.0.0-doc1
       title: My Document
       sidebar_label: Document
      @@ -72,7 +72,7 @@
       

      custom_edit_url: The url for editing this document. If this field is not present, the document's edit url will fallback to editUrl from optional fields of siteConfig.js. See siteConfig.js docs for more information.

      For example:

      -
      ---
      +
      ---
       id: doc-markdown
       title: Markdown Features
       custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
      @@ -85,7 +85,7 @@
       

      authorURL: 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.

      authorFBID: 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.

      For example:

      -
      ---
      +
      ---
       title: My First Blog Post
       author: Frank Li
       authorURL: http://twitter.com/franchementli
      @@ -97,20 +97,20 @@
       

      Linking other Documents

      You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.

      Example:

      -
      [This links to another document](other-document.md)
      +
      [This links to another document](other-document.md)
       

      This markdown will automatically get converted into a link to /docs/other-document.html (or the appropriately translated/versioned link) once it gets rendered.

      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.

      Linking to Images and Other Assets

      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 docs/assets and website/blog/assets, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.

      Example:

      -
      ![alt-text](/docs/assets/doc-image.png)
      +
      ![alt-text](/docs/assets/doc-image.png)
       

      Generating Table of Contents

      You can make an autogenerated list of links, which can be useful as a table of contents for API docs.

      In your markdown file, insert a line with the text <AUTOGENERATED_TABLE_OF_CONTENTS>. Write your documentation using h3 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 <AUTOGENERATED_TABLE_OF_CONTENTS>.

      Example:

      -
      ### `docusaurus.function(a, b)`
      +
      ### `docusaurus.function(a, b)`
       
       Text describing my function
       
      @@ -119,7 +119,7 @@ Text describing my function
       Text describing my function
       

      will lead to a table of contents of the functions:

      -
      - `docusaurus.function(a, b)`
      +
      - `docusaurus.function(a, b)`
       - `docdoc(file)`
       

      and each function will link to their corresponding sections in the page.

      @@ -133,13 +133,13 @@ ReactDOM.render( ```

      ...would be rendered with syntax highlighting like so:

      -
      ReactDOM.render(
      +
      ReactDOM.render(
         <h1>Hello, world!</h1>,
         document.getElementById('root')
       );
       

      Highlighting is provided by Highlight.js using the theme specified in your siteConfig.js file as part of the highlight key:

      -
      {
      +
      {
         ...
         highlight: {
           theme: 'default'
      @@ -150,7 +150,7 @@ ReactDOM.render(
       

      You can find the full list of supported themes in the Highlight.js styles directory.

      Registering additional languages

      While Highlight.js provides support for many popular languages out of the box, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the hljs constant as part of the highlight config key. This in turn allows you to call registerLanguage:

      -
      {
      +
      {
         ...
         highlight: {
           theme: 'default',
      diff --git a/docs/en/1.1.1/installation.html b/docs/en/1.1.1/installation.html
      index 659fd92151..c66e90a86f 100644
      --- a/docs/en/1.1.1/installation.html
      +++ b/docs/en/1.1.1/installation.html
      @@ -62,7 +62,7 @@
       

      After Docusaurus is installed, moving forward, you can check your current version of Docusaurus by going into the website directory and typing yarn outdated docusaurus or npm outdated docusaurus. You can update to the latest version of Docusaurus by typing yarn upgrade docusaurus --latest or npm update docusaurus.

      Verifying Installation

      Along with previously existing files and directories, your root directory will now contain a structure similar to:

      -
      root-of-repo
      +
      root-of-repo
       ├── docs-examples-from-docusaurus
       │   ├── doc1.md
       │   ├── doc2.md
      diff --git a/docs/en/1.1.1/installation/index.html b/docs/en/1.1.1/installation/index.html
      index 659fd92151..c66e90a86f 100644
      --- a/docs/en/1.1.1/installation/index.html
      +++ b/docs/en/1.1.1/installation/index.html
      @@ -62,7 +62,7 @@
       

      After Docusaurus is installed, moving forward, you can check your current version of Docusaurus by going into the website directory and typing yarn outdated docusaurus or npm outdated docusaurus. You can update to the latest version of Docusaurus by typing yarn upgrade docusaurus --latest or npm update docusaurus.

      Verifying Installation

      Along with previously existing files and directories, your root directory will now contain a structure similar to:

      -
      root-of-repo
      +
      root-of-repo
       ├── docs-examples-from-docusaurus
       │   ├── doc1.md
       │   ├── doc2.md
      diff --git a/docs/en/1.1.1/navigation.html b/docs/en/1.1.1/navigation.html
      index 438992b545..8f519d1000 100644
      --- a/docs/en/1.1.1/navigation.html
      +++ b/docs/en/1.1.1/navigation.html
      @@ -50,7 +50,7 @@
               
    Edit

    Navigation and Sidebars

    Referencing Site Documents

    If you want to reference another document in your docs folder (or the location you set via the optional customDocsPath path site configuration option), then you just use the name of the document you want to reference.

    For example, if you are in doc2.md and you want to reference doc1.md:

    -
    I am referencing a [document](doc1.md).
    +
    I am referencing a [document](doc1.md).
     

    Docusaurus currently does not support documents in nested folders; only in a flat folder structure. We are looking into adding support for nested folders.

    @@ -59,7 +59,7 @@

    New markdown files within docs will show up as pages on the website. Links to those documents are created first by using the id in the header of each document. If there is no id field, then the name of the file will serve as the link name.

    For example, creating an empty file such as docs/getting-started.md will enable the new page URL as /docs/getting-started.html.

    Suppose you add this to your document:

    -
    ---
    +
    ---
     id: intro
     title: Getting Started
     ---
    @@ -80,7 +80,7 @@
     

    Until you add your document to website/sidebars.json, they will only be accessible via a direct URL. The doc will not show up in any sidebar.

    Within sidebars.json, add the id you used in the document header to existing sidebar/category. In the below case, docs is the name of the sidebar and Getting Started is a category within the sidebar.

    -
    {
    +
    {
       "docs": {
         "Getting Started": [
           "getting-started"
    @@ -91,7 +91,7 @@
     }
     

    Or you can create a new category within the sidebar:

    -
    {
    +
    {
       "docs": {
         "My New Sidebar Category": [
           "getting-started"
    @@ -103,7 +103,7 @@
     

    Adding New Sidebars

    You can also put a document in a new sidebar. In the following example, we are creating an examples-sidebar sidebar within sidebars.json that has a category called My Example Category containing a document with an id of my-examples.

    -
    {
    +
    {
       "examples-sidebar": {
         "My Example Category": [
           "my-examples"
    @@ -118,7 +118,7 @@
     

    To expose sidebars, you will add clickable labels to the site navigation bar at the top of the website. You can add documents, pages and external links.

    Adding Documents

    After creating a new sidebar for the site by adding it to sidebars.json, you can expose the new sidebar from the top navigation bar by editing the headerLinks field of siteConfig.js.

    -
    {
    +
    {
       headerLinks: [
         ...
         { doc: 'my-examples', label: 'Examples' },
    @@ -130,7 +130,7 @@
     

    A label called Examples will be added to the site navigation bar and when you click on it at the top of your site, the examples-sidebar will be shown and the default document will be my-examples.

    Adding Custom Pages

    To add custom pages to the site navigation bar, entries can be added to the headerLinks of siteConfig.js. For example, if we have a page within website/pages/help.js, we can link to it by adding the following:

    -
    {
    +
    {
       headerLinks: [
         ...
         { page: 'help', label: 'Help' },
    @@ -142,7 +142,7 @@
     

    A label called Help will be added to the site navigation bar and when you click on it at the top of your site, the content from the help.js page will be shown.

    Adding External Links

    Custom links can be added to the site navigation bar with the following entry in siteConfig.js:

    -
    {
    +
    {
       headerLinks: [
         ...
         { href: 'https://github.com/facebook/Docusaurus', label: 'GitHub' },
    @@ -159,7 +159,7 @@
     

    You have limited control where the search and languages dropdown elements are shown in the site navigation bar at the top of your website.

    Search

    If search is enabled on your site, your search bar will appear to the right of your links. If you want to put the search bar between links in the header, add a search entry in the headerLinks config array:

    -
    {
    +
    {
       headerLinks: [
         { doc: 'foo', label: 'Foo' },
         { search: true },
    @@ -170,7 +170,7 @@
     

    Languages Dropdown

    If translations is enabled on your site, the language dropdown will appear to the right of your links (and to the left of the search bar, if search is enabled). If you want to put the language selection drop down between links in the header, add a languages entry in the headerLinks config array:

    -
    {
    +
    {
       headerLinks: [
         { doc: 'foo', label: 'Foo' },
         { languages: true },
    @@ -192,7 +192,7 @@
     

    These are two separate class names so you can have the active styles applied to either exact matches only or a bit more broadly for docs that belong together. If you don't want to make this distinction you can add both classes to the same CSS rule.

    Secondary On-Page Navigation

    We support secondary on-page navigation so you can more easily see the topics associated with a given document. To enable this feature, you need to add the onPageNav site configuration option to your siteConfig.js.

    -
    {
    +
    {
       onPageNav: 'separate',
       ...
     }
    diff --git a/docs/en/1.1.1/navigation/index.html b/docs/en/1.1.1/navigation/index.html
    index 438992b545..8f519d1000 100644
    --- a/docs/en/1.1.1/navigation/index.html
    +++ b/docs/en/1.1.1/navigation/index.html
    @@ -50,7 +50,7 @@
             
    Edit

    Navigation and Sidebars

    Referencing Site Documents

    If you want to reference another document in your docs folder (or the location you set via the optional customDocsPath path site configuration option), then you just use the name of the document you want to reference.

    For example, if you are in doc2.md and you want to reference doc1.md:

    -
    I am referencing a [document](doc1.md).
    +
    I am referencing a [document](doc1.md).
     

    Docusaurus currently does not support documents in nested folders; only in a flat folder structure. We are looking into adding support for nested folders.

    @@ -59,7 +59,7 @@

    New markdown files within docs will show up as pages on the website. Links to those documents are created first by using the id in the header of each document. If there is no id field, then the name of the file will serve as the link name.

    For example, creating an empty file such as docs/getting-started.md will enable the new page URL as /docs/getting-started.html.

    Suppose you add this to your document:

    -
    ---
    +
    ---
     id: intro
     title: Getting Started
     ---
    @@ -80,7 +80,7 @@
     

    Until you add your document to website/sidebars.json, they will only be accessible via a direct URL. The doc will not show up in any sidebar.

    Within sidebars.json, add the id you used in the document header to existing sidebar/category. In the below case, docs is the name of the sidebar and Getting Started is a category within the sidebar.

    -
    {
    +
    {
       "docs": {
         "Getting Started": [
           "getting-started"
    @@ -91,7 +91,7 @@
     }
     

    Or you can create a new category within the sidebar:

    -
    {
    +
    {
       "docs": {
         "My New Sidebar Category": [
           "getting-started"
    @@ -103,7 +103,7 @@
     

    Adding New Sidebars

    You can also put a document in a new sidebar. In the following example, we are creating an examples-sidebar sidebar within sidebars.json that has a category called My Example Category containing a document with an id of my-examples.

    -
    {
    +
    {
       "examples-sidebar": {
         "My Example Category": [
           "my-examples"
    @@ -118,7 +118,7 @@
     

    To expose sidebars, you will add clickable labels to the site navigation bar at the top of the website. You can add documents, pages and external links.

    Adding Documents

    After creating a new sidebar for the site by adding it to sidebars.json, you can expose the new sidebar from the top navigation bar by editing the headerLinks field of siteConfig.js.

    -
    {
    +
    {
       headerLinks: [
         ...
         { doc: 'my-examples', label: 'Examples' },
    @@ -130,7 +130,7 @@
     

    A label called Examples will be added to the site navigation bar and when you click on it at the top of your site, the examples-sidebar will be shown and the default document will be my-examples.

    Adding Custom Pages

    To add custom pages to the site navigation bar, entries can be added to the headerLinks of siteConfig.js. For example, if we have a page within website/pages/help.js, we can link to it by adding the following:

    -
    {
    +
    {
       headerLinks: [
         ...
         { page: 'help', label: 'Help' },
    @@ -142,7 +142,7 @@
     

    A label called Help will be added to the site navigation bar and when you click on it at the top of your site, the content from the help.js page will be shown.

    Adding External Links

    Custom links can be added to the site navigation bar with the following entry in siteConfig.js:

    -
    {
    +
    {
       headerLinks: [
         ...
         { href: 'https://github.com/facebook/Docusaurus', label: 'GitHub' },
    @@ -159,7 +159,7 @@
     

    You have limited control where the search and languages dropdown elements are shown in the site navigation bar at the top of your website.

    Search

    If search is enabled on your site, your search bar will appear to the right of your links. If you want to put the search bar between links in the header, add a search entry in the headerLinks config array:

    -
    {
    +
    {
       headerLinks: [
         { doc: 'foo', label: 'Foo' },
         { search: true },
    @@ -170,7 +170,7 @@
     

    Languages Dropdown

    If translations is enabled on your site, the language dropdown will appear to the right of your links (and to the left of the search bar, if search is enabled). If you want to put the language selection drop down between links in the header, add a languages entry in the headerLinks config array:

    -
    {
    +
    {
       headerLinks: [
         { doc: 'foo', label: 'Foo' },
         { languages: true },
    @@ -192,7 +192,7 @@
     

    These are two separate class names so you can have the active styles applied to either exact matches only or a bit more broadly for docs that belong together. If you don't want to make this distinction you can add both classes to the same CSS rule.

    Secondary On-Page Navigation

    We support secondary on-page navigation so you can more easily see the topics associated with a given document. To enable this feature, you need to add the onPageNav site configuration option to your siteConfig.js.

    -
    {
    +
    {
       onPageNav: 'separate',
       ...
     }
    diff --git a/docs/en/1.1.1/publishing.html b/docs/en/1.1.1/publishing.html
    index 72a2010c47..b4f8900d78 100644
    --- a/docs/en/1.1.1/publishing.html
    +++ b/docs/en/1.1.1/publishing.html
    @@ -50,7 +50,7 @@
             
    Edit

    Publishing your site

    You should now have a site up and running locally. Once you have customized it to your liking, it's time to publish it. Docusaurus generates a static HTML website that is ready to be served by your favorite web server or online hosting solution.

    Building Static HTML Pages

    To create a static build of your website, run the following script from the website directory:

    -
    yarn run build # or `npm run build`
    +
    yarn run build # or `npm run build`
     

    This will generate a build folder inside the website directory containing the .html files from all of your docs and other pages included in pages.

    Hosting Static HTML Pages

    @@ -110,7 +110,7 @@

    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:

    To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate. If you run into issues related to SSH keys, visit Github's authentication documentation.

    -
    GIT_USER=<GIT_USER> \
    +
    GIT_USER=<GIT_USER> \
       CURRENT_BRANCH=master \
       USE_SSH=true \
       yarn run publish-gh-pages # or `npm run publish-gh-pages`
    @@ -134,7 +134,7 @@
     
  • Create a .circleci folder and create a config.yml under that folder.
  • Copy the text below into .circleci/config.yml.
  • -
    # If you only want circle to run on direct commits to master, you can uncomment this out
    +
    # If you only want circle to run on direct commits to master, you can uncomment this out
     # and uncomment the filters: *filter-only-master down below too
     #
     # aliases:
    @@ -181,7 +181,7 @@
     
     

    Tips & Tricks

    When initially deploying to a gh-pages branch using Circle CI, you may notice that some jobs triggered by commits to the gh-pages 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:

    -
    # Circle CI 2.0 Config File
    +
    # Circle CI 2.0 Config File
     # This config file will prevent tests from being run on the gh-pages branch.
     version: 2
     jobs:
    diff --git a/docs/en/1.1.1/publishing/index.html b/docs/en/1.1.1/publishing/index.html
    index 72a2010c47..b4f8900d78 100644
    --- a/docs/en/1.1.1/publishing/index.html
    +++ b/docs/en/1.1.1/publishing/index.html
    @@ -50,7 +50,7 @@
             
    Edit

    Publishing your site

    You should now have a site up and running locally. Once you have customized it to your liking, it's time to publish it. Docusaurus generates a static HTML website that is ready to be served by your favorite web server or online hosting solution.

    Building Static HTML Pages

    To create a static build of your website, run the following script from the website directory:

    -
    yarn run build # or `npm run build`
    +
    yarn run build # or `npm run build`
     

    This will generate a build folder inside the website directory containing the .html files from all of your docs and other pages included in pages.

    Hosting Static HTML Pages

    @@ -110,7 +110,7 @@

    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:

    To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate. If you run into issues related to SSH keys, visit Github's authentication documentation.

    -
    GIT_USER=<GIT_USER> \
    +
    GIT_USER=<GIT_USER> \
       CURRENT_BRANCH=master \
       USE_SSH=true \
       yarn run publish-gh-pages # or `npm run publish-gh-pages`
    @@ -134,7 +134,7 @@
     
  • Create a .circleci folder and create a config.yml under that folder.
  • Copy the text below into .circleci/config.yml.
  • -
    # If you only want circle to run on direct commits to master, you can uncomment this out
    +
    # If you only want circle to run on direct commits to master, you can uncomment this out
     # and uncomment the filters: *filter-only-master down below too
     #
     # aliases:
    @@ -181,7 +181,7 @@
     
     

    Tips & Tricks

    When initially deploying to a gh-pages branch using Circle CI, you may notice that some jobs triggered by commits to the gh-pages 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:

    -
    # Circle CI 2.0 Config File
    +
    # Circle CI 2.0 Config File
     # This config file will prevent tests from being run on the gh-pages branch.
     version: 2
     jobs:
    diff --git a/docs/en/1.1.1/search.html b/docs/en/1.1.1/search.html
    index 77d5d4804c..a1951c23f3 100644
    --- a/docs/en/1.1.1/search.html
    +++ b/docs/en/1.1.1/search.html
    @@ -51,7 +51,7 @@
     

    DocSearch works by crawling the content of your website every 24 hours and putting all the content in an Algolia index. This content is then queried directly from your front-end using the Algolia API. Note that your website need to be publicly available for this to work (ie. not behind a firewall). This service is free.

    Enabling the Search Bar

    Enter your API key and index name (sent by Algolia) into siteConfig.js in the algolia section to enable search for your site.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       algolia: {
         apiKey: 'my-api-key',
    @@ -65,7 +65,7 @@
     

    Controlling the Location of the Search Bar

    By default, the search bar will be the rightmost element in the top navigation bar.

    If you want to change the default location, add the searchBar flag in the headerLinks field of siteConfig.js in your desired location. For example, you may want the search bar between your internal and external links.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       headerLinks: [
         {...}
    diff --git a/docs/en/1.1.1/search/index.html b/docs/en/1.1.1/search/index.html
    index 77d5d4804c..a1951c23f3 100644
    --- a/docs/en/1.1.1/search/index.html
    +++ b/docs/en/1.1.1/search/index.html
    @@ -51,7 +51,7 @@
     

    DocSearch works by crawling the content of your website every 24 hours and putting all the content in an Algolia index. This content is then queried directly from your front-end using the Algolia API. Note that your website need to be publicly available for this to work (ie. not behind a firewall). This service is free.

    Enabling the Search Bar

    Enter your API key and index name (sent by Algolia) into siteConfig.js in the algolia section to enable search for your site.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       algolia: {
         apiKey: 'my-api-key',
    @@ -65,7 +65,7 @@
     

    Controlling the Location of the Search Bar

    By default, the search bar will be the rightmost element in the top navigation bar.

    If you want to change the default location, add the searchBar flag in the headerLinks field of siteConfig.js in your desired location. For example, you may want the search bar between your internal and external links.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       headerLinks: [
         {...}
    diff --git a/docs/en/1.1.1/site-config.html b/docs/en/1.1.1/site-config.html
    index d99f8971ce..ecb6f25bb5 100644
    --- a/docs/en/1.1.1/site-config.html
    +++ b/docs/en/1.1.1/site-config.html
    @@ -66,7 +66,7 @@
     

    headerIcon - url for icon used in header navigation bar.

    headerLinks - Links that will be used in the header navigation bar. The label field of each object will be the link text and will also be translated for each language.

    Example Usage:

    -
    headerLinks: [
    +
    headerLinks: [
       // Links to document with id doc1 for current language/version
       { doc: "doc1", label: "Getting Started" },
       // Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language
    @@ -97,9 +97,9 @@
     

    blogSidebarCount - Control the number of blog posts that show up in the sidebar. See the adding a blog docs for more information.

    cname - The CNAME for your website. It will go into a CNAME file when your site it built.

    customDocsPath - By default, Docusaurus expects your documentation to be in a directory called docs. This directory is at the same level as the website directory (i.e., not inside the website directory). You can specify a custom path to your documentation with this field. Note that all of your documentation *.md files must still reside in a flat hierarchy. You cannot have your documents in nested directories.

    -
    customDocsPath: 'docs/site';
    +
    customDocsPath: 'docs/site';
     
    -
    customDocsPath: 'website-docs';
    +
    customDocsPath: 'website-docs';
     

    defaultVersionShown - The default version for the site to be shown. If this is not set, the latest version will be shown.

    disableHeaderTitle - 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 true.

    @@ -110,7 +110,7 @@

    facebookPixelId - Facebook Pixel ID to track page views.

    fonts - Font-family css configuration for the site. If a font family is specified in siteConfig.js as $myFont, then adding a myFont key to an array in fonts will allow you to configure the font. Items appearing earlier in the array will take priority of later elements, so ordering of the fonts matter.

    In the below example, we have two sets of font configurations, myFont and myOtherFont. Times New Roman is the preferred font in myFont. -apple-system is the preferred in myOtherFont.

    -
    fonts: {
    +
    fonts: {
       myFont: [
         'Times New Roman',
         'Serif'
    @@ -122,7 +122,7 @@
     },
     

    The above fonts would be represented in your CSS file(s) as variables $myFont and $myOtherFont.

    -
    h1 {
    +
    h1 {
       font-family: $myFont;
     }
     
    @@ -155,7 +155,7 @@

    wrapPagesHTML - Boolean flag to indicate whether html files in /pages should be wrapped with Docusaurus site styles, header and footer. This feature is experimental and relies on the files being html fragments instead of complete pages. It inserts the contents of your html file with no extra processing. Defaults to false.

    Users can also add their own custom fields if they wish to provide some data across different files.

    Example siteConfig.js with many available fields

    -
    const users = [
    +
    const users = [
       {
         caption: 'User1',
         image: '/test-site/img/docusaurus.svg',
    diff --git a/docs/en/1.1.1/site-config/index.html b/docs/en/1.1.1/site-config/index.html
    index d99f8971ce..ecb6f25bb5 100644
    --- a/docs/en/1.1.1/site-config/index.html
    +++ b/docs/en/1.1.1/site-config/index.html
    @@ -66,7 +66,7 @@
     

    headerIcon - url for icon used in header navigation bar.

    headerLinks - Links that will be used in the header navigation bar. The label field of each object will be the link text and will also be translated for each language.

    Example Usage:

    -
    headerLinks: [
    +
    headerLinks: [
       // Links to document with id doc1 for current language/version
       { doc: "doc1", label: "Getting Started" },
       // Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language
    @@ -97,9 +97,9 @@
     

    blogSidebarCount - Control the number of blog posts that show up in the sidebar. See the adding a blog docs for more information.

    cname - The CNAME for your website. It will go into a CNAME file when your site it built.

    customDocsPath - By default, Docusaurus expects your documentation to be in a directory called docs. This directory is at the same level as the website directory (i.e., not inside the website directory). You can specify a custom path to your documentation with this field. Note that all of your documentation *.md files must still reside in a flat hierarchy. You cannot have your documents in nested directories.

    -
    customDocsPath: 'docs/site';
    +
    customDocsPath: 'docs/site';
     
    -
    customDocsPath: 'website-docs';
    +
    customDocsPath: 'website-docs';
     

    defaultVersionShown - The default version for the site to be shown. If this is not set, the latest version will be shown.

    disableHeaderTitle - 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 true.

    @@ -110,7 +110,7 @@

    facebookPixelId - Facebook Pixel ID to track page views.

    fonts - Font-family css configuration for the site. If a font family is specified in siteConfig.js as $myFont, then adding a myFont key to an array in fonts will allow you to configure the font. Items appearing earlier in the array will take priority of later elements, so ordering of the fonts matter.

    In the below example, we have two sets of font configurations, myFont and myOtherFont. Times New Roman is the preferred font in myFont. -apple-system is the preferred in myOtherFont.

    -
    fonts: {
    +
    fonts: {
       myFont: [
         'Times New Roman',
         'Serif'
    @@ -122,7 +122,7 @@
     },
     

    The above fonts would be represented in your CSS file(s) as variables $myFont and $myOtherFont.

    -
    h1 {
    +
    h1 {
       font-family: $myFont;
     }
     
    @@ -155,7 +155,7 @@

    wrapPagesHTML - Boolean flag to indicate whether html files in /pages should be wrapped with Docusaurus site styles, header and footer. This feature is experimental and relies on the files being html fragments instead of complete pages. It inserts the contents of your html file with no extra processing. Defaults to false.

    Users can also add their own custom fields if they wish to provide some data across different files.

    Example siteConfig.js with many available fields

    -
    const users = [
    +
    const users = [
       {
         caption: 'User1',
         image: '/test-site/img/docusaurus.svg',
    diff --git a/docs/en/1.1.1/site-creation.html b/docs/en/1.1.1/site-creation.html
    index 80b56372b4..fb1d6c1a15 100644
    --- a/docs/en/1.1.1/site-creation.html
    +++ b/docs/en/1.1.1/site-creation.html
    @@ -51,7 +51,7 @@
     

    After installation and preparation, much of the work to create a basic site for your docs is already complete.

    Site Structure

    Your site structure looks like the following:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs
     ├── website
     │   ├── blog
    @@ -75,7 +75,7 @@
     

    To create a fully functional site, you only need to do a few steps:

    1. Add your documentation to the /docs folder as .md files, ensuring you have the proper header in each file. The simplest header would be the following, where id is the link name (e.g., docs/intro.html) and the title, is, of course, the title of the browser page.

      -
      ---
      +
      ---
       id: intro
       title: Getting Started
       ---
      @@ -93,7 +93,7 @@
       
    2. Place assets, such as images, in the website/static/ folder.
    3. Run the site to see the results of your changes.
    -
    cd website
    +
    cd website
     yarn run start # or `npm run start`
     # Navigate to http://localhost:3000
     
    @@ -104,7 +104,7 @@ yarn run start # or `npm run start`
  • Remove the index.js file from the website/pages directory, if it exists.
  • Add a custom static index.html page in the website/static folder with the following contents:
  • -
    <!DOCTYPE HTML>
    +
    <!DOCTYPE HTML>
     <html lang="en-US">
       <head>
         <meta charset="UTF-8">
    diff --git a/docs/en/1.1.1/site-creation/index.html b/docs/en/1.1.1/site-creation/index.html
    index 80b56372b4..fb1d6c1a15 100644
    --- a/docs/en/1.1.1/site-creation/index.html
    +++ b/docs/en/1.1.1/site-creation/index.html
    @@ -51,7 +51,7 @@
     

    After installation and preparation, much of the work to create a basic site for your docs is already complete.

    Site Structure

    Your site structure looks like the following:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs
     ├── website
     │   ├── blog
    @@ -75,7 +75,7 @@
     

    To create a fully functional site, you only need to do a few steps:

    1. Add your documentation to the /docs folder as .md files, ensuring you have the proper header in each file. The simplest header would be the following, where id is the link name (e.g., docs/intro.html) and the title, is, of course, the title of the browser page.

      -
      ---
      +
      ---
       id: intro
       title: Getting Started
       ---
      @@ -93,7 +93,7 @@
       
    2. Place assets, such as images, in the website/static/ folder.
    3. Run the site to see the results of your changes.
    -
    cd website
    +
    cd website
     yarn run start # or `npm run start`
     # Navigate to http://localhost:3000
     
    @@ -104,7 +104,7 @@ yarn run start # or `npm run start`
  • Remove the index.js file from the website/pages directory, if it exists.
  • Add a custom static index.html page in the website/static folder with the following contents:
  • -
    <!DOCTYPE HTML>
    +
    <!DOCTYPE HTML>
     <html lang="en-US">
       <head>
         <meta charset="UTF-8">
    diff --git a/docs/en/1.1.1/site-preparation.html b/docs/en/1.1.1/site-preparation.html
    index abaf2e6697..233cc4ce20 100644
    --- a/docs/en/1.1.1/site-preparation.html
    +++ b/docs/en/1.1.1/site-preparation.html
    @@ -50,7 +50,7 @@
             
    Edit

    Site Preparation

    After installing Docusaurus, 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.

    Directory Structure

    As shown after you installed Docusaurus, the initialization script created a directory structure similar to:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs-examples-from-docusaurus
     │   ├── doc1.md
     │   ├── doc2.md
    diff --git a/docs/en/1.1.1/site-preparation/index.html b/docs/en/1.1.1/site-preparation/index.html
    index abaf2e6697..233cc4ce20 100644
    --- a/docs/en/1.1.1/site-preparation/index.html
    +++ b/docs/en/1.1.1/site-preparation/index.html
    @@ -50,7 +50,7 @@
             
    Edit

    Site Preparation

    After installing Docusaurus, 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.

    Directory Structure

    As shown after you installed Docusaurus, the initialization script created a directory structure similar to:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs-examples-from-docusaurus
     │   ├── doc1.md
     │   ├── doc2.md
    diff --git a/docs/en/1.1.1/translation.html b/docs/en/1.1.1/translation.html
    index 3932377a16..42add290ee 100644
    --- a/docs/en/1.1.1/translation.html
    +++ b/docs/en/1.1.1/translation.html
    @@ -50,13 +50,13 @@
             
    Edit

    Translations & Localization

    Docusaurus allows for easy translation functionality using Crowdin. Documentation files written in English are uploaded to Crowdin for translation by users within a community. Top-level pages written with English strings can be translated by wrapping any strings you want to translate in a <translate> tag. Other titles and labels will also be found and properly translated.

    Docusaurus Translation Configurations

    To generate example files for translations with Docusaurus, run the examples script with the command line argument translations:

    -
    npm run examples translations
    +
    npm run examples translations
     

    or

    -
    yarn examples translations
    +
    yarn examples translations
     

    This will create the following files:

    -
    pages/en/help-with-translations.js
    +
    pages/en/help-with-translations.js
     languages.js
     ../crowdin.yaml
     
    @@ -76,7 +76,7 @@ languages.js

    Pages allow you to customize layout and specific content of pages like a custom index page or help page.

    Pages with text that you want translated should be placed in website/pages/en folder.

    Wrap strings you want translated in a <translate> tag, and add the following require statement to the top of the file:

    -
    ...
    +
    ...
     const translate = require('../../server/translate.js').translate;
     ...
     <h2>
    @@ -85,7 +85,7 @@ languages.js
     ...
     

    You can also include an optional description attribute to give more context to a translator about how to translate the string:

    -
    <p>
    +
    <p>
       <translate desc="flower, not verb">Rose</translate>
     <p>
     
    @@ -95,7 +95,7 @@ languages.js

    Gathering Strings to Translate

    The strings within localized Pages must be extracted and provided to Crowdin.

    Add the following script to your website/package.json file, if it does not exist already:

    -
    {
    +
    {
       ...
       "scripts": {
         "write-translations": "docusaurus-write-translations"
    @@ -135,7 +135,7 @@ languages.js
     
     

    The example below can be automatically generated by the Docusaurus cli with the examples script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.

    Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.

    -
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
    +
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
     api_key_env: CROWDIN_DOCUSAURUS_API_KEY
     base_path: "./"
     preserve_hierarchy: true
    @@ -160,14 +160,14 @@ languages.js
     

    Setup the Crowdin Scripts

    You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in /docs as well as translatable strings in website/i18n/en.json. (These strings can be generated by running yarn write-translations.)

    You can add the following to your package.json to manually trigger Crowdin.

    -
    "scripts": {
    +
    "scripts": {
       "crowdin-upload": "crowdin --config ../crowdin.yaml upload sources --auto-update -b master",
       "crowdin-download": "crowdin --config ../crowdin.yaml download -b master"
     },
     

    Manual File Sync

    You will always want to upload your markdown files and translatable strings first and the download the translations section. So run the commands in this order:

    -
    CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-upload
    +
    CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-upload
     CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-download
     
    @@ -185,7 +185,7 @@ CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY

    Automated File Sync Using CircleCI

    You can automate pulling down and uploading translations for your files using the CircleCI web continuous integration service.

    First, update the circle.yml 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 circle.yml file:

    -
    machine:
    +
    machine:
       node:
         version: 6.10.3
       npm:
    @@ -221,7 +221,7 @@ CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY
     

    If you wish to use Crowdin on your machine locally, you can install the Crowdin CLI tool and run the same commands found in the circle.yaml file. The only difference is that you must set project_identifier and api_key values in the crowdin.yaml file since you will not have Circle environment variables set up.

    Versioned Translations

    If you wish to have translation and versioning for your documentation, add the following section to the end of your crowdin.yaml file:

    -
      -
    +
      -
         source: '/website/versioned_docs/**/*.md'
         translation: '/website/translated_docs/%locale%/**/%original_file_name%'
         languages_mapping: *anchor
    diff --git a/docs/en/1.1.1/translation/index.html b/docs/en/1.1.1/translation/index.html
    index 3932377a16..42add290ee 100644
    --- a/docs/en/1.1.1/translation/index.html
    +++ b/docs/en/1.1.1/translation/index.html
    @@ -50,13 +50,13 @@
             
    Edit

    Translations & Localization

    Docusaurus allows for easy translation functionality using Crowdin. Documentation files written in English are uploaded to Crowdin for translation by users within a community. Top-level pages written with English strings can be translated by wrapping any strings you want to translate in a <translate> tag. Other titles and labels will also be found and properly translated.

    Docusaurus Translation Configurations

    To generate example files for translations with Docusaurus, run the examples script with the command line argument translations:

    -
    npm run examples translations
    +
    npm run examples translations
     

    or

    -
    yarn examples translations
    +
    yarn examples translations
     

    This will create the following files:

    -
    pages/en/help-with-translations.js
    +
    pages/en/help-with-translations.js
     languages.js
     ../crowdin.yaml
     
    @@ -76,7 +76,7 @@ languages.js

    Pages allow you to customize layout and specific content of pages like a custom index page or help page.

    Pages with text that you want translated should be placed in website/pages/en folder.

    Wrap strings you want translated in a <translate> tag, and add the following require statement to the top of the file:

    -
    ...
    +
    ...
     const translate = require('../../server/translate.js').translate;
     ...
     <h2>
    @@ -85,7 +85,7 @@ languages.js
     ...
     

    You can also include an optional description attribute to give more context to a translator about how to translate the string:

    -
    <p>
    +
    <p>
       <translate desc="flower, not verb">Rose</translate>
     <p>
     
    @@ -95,7 +95,7 @@ languages.js

    Gathering Strings to Translate

    The strings within localized Pages must be extracted and provided to Crowdin.

    Add the following script to your website/package.json file, if it does not exist already:

    -
    {
    +
    {
       ...
       "scripts": {
         "write-translations": "docusaurus-write-translations"
    @@ -135,7 +135,7 @@ languages.js
     
     

    The example below can be automatically generated by the Docusaurus cli with the examples script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.

    Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.

    -
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
    +
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
     api_key_env: CROWDIN_DOCUSAURUS_API_KEY
     base_path: "./"
     preserve_hierarchy: true
    @@ -160,14 +160,14 @@ languages.js
     

    Setup the Crowdin Scripts

    You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in /docs as well as translatable strings in website/i18n/en.json. (These strings can be generated by running yarn write-translations.)

    You can add the following to your package.json to manually trigger Crowdin.

    -
    "scripts": {
    +
    "scripts": {
       "crowdin-upload": "crowdin --config ../crowdin.yaml upload sources --auto-update -b master",
       "crowdin-download": "crowdin --config ../crowdin.yaml download -b master"
     },
     

    Manual File Sync

    You will always want to upload your markdown files and translatable strings first and the download the translations section. So run the commands in this order:

    -
    CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-upload
    +
    CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-upload
     CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-download
     
    @@ -185,7 +185,7 @@ CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY

    Automated File Sync Using CircleCI

    You can automate pulling down and uploading translations for your files using the CircleCI web continuous integration service.

    First, update the circle.yml 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 circle.yml file:

    -
    machine:
    +
    machine:
       node:
         version: 6.10.3
       npm:
    @@ -221,7 +221,7 @@ CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY
     

    If you wish to use Crowdin on your machine locally, you can install the Crowdin CLI tool and run the same commands found in the circle.yaml file. The only difference is that you must set project_identifier and api_key values in the crowdin.yaml file since you will not have Circle environment variables set up.

    Versioned Translations

    If you wish to have translation and versioning for your documentation, add the following section to the end of your crowdin.yaml file:

    -
      -
    +
      -
         source: '/website/versioned_docs/**/*.md'
         translation: '/website/translated_docs/%locale%/**/%original_file_name%'
         languages_mapping: *anchor
    diff --git a/docs/en/1.1.1/versioning.html b/docs/en/1.1.1/versioning.html
    index 07b02054a6..3b8841cd4f 100644
    --- a/docs/en/1.1.1/versioning.html
    +++ b/docs/en/1.1.1/versioning.html
    @@ -50,19 +50,19 @@
             
    Edit

    Versioning

    You can use the version script to cut a new documentation version based on the latest content in the docs folder. That specific set of documentation will then be preserved and accessible even as the documentation in the docs folder changes moving forward.

    How to Create New Versions

    Run the following script to generate a starter versions page listing all the site versions:

    -
    yarn examples versions
    +
    yarn examples versions
     

    This creates the pages/en/versions.js file.

    You can edit this file later on to customize how you display the versions.

    Add the following script to your package.json file if it doesn't already exist:

    -
    ...
    +
    ...
     "scripts": {
       "version": "docusaurus-version"
     },
     ...
     

    Run the script with a command line argument of the version you wish to create. e.g.,

    -
    yarn run version 1.0.0
    +
    yarn run version 1.0.0
     

    This will preserve all documents currently in the docs folder and make them available as documentation for version 1.0.0.

    If, for example, you ran the version script with 1.0.0 as the version number, version 1.0.0 is considered the latest release version for your project. 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.

    @@ -93,14 +93,14 @@

    For example, a document with the original id doc1 exists for the latest version, 1.0.0, and has the same content as the document with the id doc1 in the docs folder. When a new version 2.0.0 is created, the file for doc1 will not be copied into versioned_docs/version-2.0.0/. There will still be a page for docs/2.0.0/doc1.html, but it will use the file from version 1.0.0.

    Renaming Existing Versions

    To rename an existing version number to something else, first make sure the following script is in your package.json file:

    -
    ...
    +
    ...
     "scripts": {
       "rename-version": "docusaurus-rename-version"
     },
     ...
     

    Run the script with command line arguments of first, the current version name, then second, the new version name. e.g.,

    -
    yarn run rename-version 1.0.0 1.0.1
    +
    yarn run rename-version 1.0.0 1.0.1
     

    Versioning and Translations

    If you wish to use versioning and translations features, the crowdin.yaml 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 translated_docs/${language}/version-${version}/. For more information, check out the translations guide.

    diff --git a/docs/en/1.1.1/versioning/index.html b/docs/en/1.1.1/versioning/index.html index 07b02054a6..3b8841cd4f 100644 --- a/docs/en/1.1.1/versioning/index.html +++ b/docs/en/1.1.1/versioning/index.html @@ -50,19 +50,19 @@
    Edit

    Versioning

    You can use the version script to cut a new documentation version based on the latest content in the docs folder. That specific set of documentation will then be preserved and accessible even as the documentation in the docs folder changes moving forward.

    How to Create New Versions

    Run the following script to generate a starter versions page listing all the site versions:

    -
    yarn examples versions
    +
    yarn examples versions
     

    This creates the pages/en/versions.js file.

    You can edit this file later on to customize how you display the versions.

    Add the following script to your package.json file if it doesn't already exist:

    -
    ...
    +
    ...
     "scripts": {
       "version": "docusaurus-version"
     },
     ...
     

    Run the script with a command line argument of the version you wish to create. e.g.,

    -
    yarn run version 1.0.0
    +
    yarn run version 1.0.0
     

    This will preserve all documents currently in the docs folder and make them available as documentation for version 1.0.0.

    If, for example, you ran the version script with 1.0.0 as the version number, version 1.0.0 is considered the latest release version for your project. 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.

    @@ -93,14 +93,14 @@

    For example, a document with the original id doc1 exists for the latest version, 1.0.0, and has the same content as the document with the id doc1 in the docs folder. When a new version 2.0.0 is created, the file for doc1 will not be copied into versioned_docs/version-2.0.0/. There will still be a page for docs/2.0.0/doc1.html, but it will use the file from version 1.0.0.

    Renaming Existing Versions

    To rename an existing version number to something else, first make sure the following script is in your package.json file:

    -
    ...
    +
    ...
     "scripts": {
       "rename-version": "docusaurus-rename-version"
     },
     ...
     

    Run the script with command line arguments of first, the current version name, then second, the new version name. e.g.,

    -
    yarn run rename-version 1.0.0 1.0.1
    +
    yarn run rename-version 1.0.0 1.0.1
     

    Versioning and Translations

    If you wish to use versioning and translations features, the crowdin.yaml 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 translated_docs/${language}/version-${version}/. For more information, check out the translations guide.

    diff --git a/docs/en/1.1.2/api-pages.html b/docs/en/1.1.2/api-pages.html index ffb9ed0cde..70dc7a7488 100644 --- a/docs/en/1.1.2/api-pages.html +++ b/docs/en/1.1.2/api-pages.html @@ -59,7 +59,7 @@

    CompLibrary.MarkdownBlock

    A React component that parses markdown and renders to HTML.

    Example:

    -
    const MarkdownBlock = CompLibrary.MarkdownBlock;
    +
    const MarkdownBlock = CompLibrary.MarkdownBlock;
     
     <MarkdownBlock>
       [Markdown syntax for a link](http://www.example.com)
    @@ -79,7 +79,7 @@
     
     
     

    Example

    -
    <Container
    +
    <Container
       padding={['bottom', 'top']}
       background="light"
       className="myCustomClass">
    @@ -115,7 +115,7 @@
     
     
     

    Example

    -
    <GridBlock
    +
    <GridBlock
       align="center"
       layout="threeColumn"
       className="myCustomClass"
    @@ -144,19 +144,19 @@
     

    Translating Strings

    When translations are enabled, any pages inside website/pages/en will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the languages.js file. E.g. The url for a French page of website/pages/en/help.js would be found at ${baseUrl}fr/help.html.

    When writing pages that you wish to translate, wrap any strings to be translated inside a <translate> tag. e.g.,

    -
    <p>
    +
    <p>
       <translate>I like translations</translate>
     </p>
     

    You can also provide an optional description attribute to provide context for translators. e.g,

    -
    <a href="/community">
    +
    <a href="/community">
       <translate desc="Footer link to page referring to community GitHub and Slack">
         Community
       </translate>
     </a>
     

    Add the following require statement as well:

    -
    const translate = require('../../server/translate.js').translate;
    +
    const translate = require('../../server/translate.js').translate;
     

    Note that this path is valid for files inside pages/en and should be adjusted accordingly if files are in different locations, as discussed above.

    Using Static Assets

    diff --git a/docs/en/1.1.2/api-pages/index.html b/docs/en/1.1.2/api-pages/index.html index ffb9ed0cde..70dc7a7488 100644 --- a/docs/en/1.1.2/api-pages/index.html +++ b/docs/en/1.1.2/api-pages/index.html @@ -59,7 +59,7 @@

    CompLibrary.MarkdownBlock

    A React component that parses markdown and renders to HTML.

    Example:

    -
    const MarkdownBlock = CompLibrary.MarkdownBlock;
    +
    const MarkdownBlock = CompLibrary.MarkdownBlock;
     
     <MarkdownBlock>
       [Markdown syntax for a link](http://www.example.com)
    @@ -79,7 +79,7 @@
     
     
     

    Example

    -
    <Container
    +
    <Container
       padding={['bottom', 'top']}
       background="light"
       className="myCustomClass">
    @@ -115,7 +115,7 @@
     
     
     

    Example

    -
    <GridBlock
    +
    <GridBlock
       align="center"
       layout="threeColumn"
       className="myCustomClass"
    @@ -144,19 +144,19 @@
     

    Translating Strings

    When translations are enabled, any pages inside website/pages/en will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the languages.js file. E.g. The url for a French page of website/pages/en/help.js would be found at ${baseUrl}fr/help.html.

    When writing pages that you wish to translate, wrap any strings to be translated inside a <translate> tag. e.g.,

    -
    <p>
    +
    <p>
       <translate>I like translations</translate>
     </p>
     

    You can also provide an optional description attribute to provide context for translators. e.g,

    -
    <a href="/community">
    +
    <a href="/community">
       <translate desc="Footer link to page referring to community GitHub and Slack">
         Community
       </translate>
     </a>
     

    Add the following require statement as well:

    -
    const translate = require('../../server/translate.js').translate;
    +
    const translate = require('../../server/translate.js').translate;
     

    Note that this path is valid for files inside pages/en and should be adjusted accordingly if files are in different locations, as discussed above.

    Using Static Assets

    diff --git a/docs/en/1.1.2/blog.html b/docs/en/1.1.2/blog.html index af120af7ed..74b3e0f07a 100644 --- a/docs/en/1.1.2/blog.html +++ b/docs/en/1.1.2/blog.html @@ -50,7 +50,7 @@
    Edit

    Adding a Blog

    Initial Setup

    To setup your site's blog, start by creating a blog folder within your repo's website directory.

    Then, add a header link to your blog within siteConfig.js:

    -
    headerLinks: [
    +
    headerLinks: [
         ...
         { blog: true, label: 'Blog' },
         ...
    @@ -59,7 +59,7 @@
     

    Adding Posts

    To publish in the blog, create a file within the blog folder with a formatted name of YYYY-MM-DD-My-Blog-Post-Title.md. The post date is extracted from the file name.

    For example, at website/blog/2017-08-18-Introducing-Docusaurus.md:

    -
    ---
    +
    ---
     author: Frank Li
     authorURL: https://twitter.com/foobarbaz
     authorFBID: 503283835
    @@ -79,7 +79,7 @@
     
     

    Summary Truncation

    Use the <!--truncate--> marker in your blog post to represent what will be shown as the summary when viewing all blog published blog posts. Anything above <!--truncate--> will be part of the summary. For example:

    -
    ---
    +
    ---
     title: Truncation Example
     ---
     
    @@ -100,7 +100,7 @@
     

    You can configure a specific amount of blog posts to show by adding a blogSidebarCount setting to your siteConfig.js.

    The available options are an integer representing the number of posts you wish to show or a string with the value 'ALL'.

    Example:

    -
    blogSidebarCount: 'ALL'
    +
    blogSidebarCount: 'ALL'
     

    RSS Feed

    Docusaurus provides a simple RSS feed for your blog posts. Both RSS and Atom feed formats are supported. This data is automatically to your website page's HTML tag.

    @@ -121,7 +121,7 @@

    Now, when Docusaurus generates or builds your site, it will copy the file from static/index.html 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 /blog.

    You can use this template:

    -
    <!DOCTYPE HTML>
    +
    <!DOCTYPE HTML>
     <html lang="en-US">
       <head>
         <meta charset="UTF-8">
    diff --git a/docs/en/1.1.2/blog/index.html b/docs/en/1.1.2/blog/index.html
    index af120af7ed..74b3e0f07a 100644
    --- a/docs/en/1.1.2/blog/index.html
    +++ b/docs/en/1.1.2/blog/index.html
    @@ -50,7 +50,7 @@
             
    Edit

    Adding a Blog

    Initial Setup

    To setup your site's blog, start by creating a blog folder within your repo's website directory.

    Then, add a header link to your blog within siteConfig.js:

    -
    headerLinks: [
    +
    headerLinks: [
         ...
         { blog: true, label: 'Blog' },
         ...
    @@ -59,7 +59,7 @@
     

    Adding Posts

    To publish in the blog, create a file within the blog folder with a formatted name of YYYY-MM-DD-My-Blog-Post-Title.md. The post date is extracted from the file name.

    For example, at website/blog/2017-08-18-Introducing-Docusaurus.md:

    -
    ---
    +
    ---
     author: Frank Li
     authorURL: https://twitter.com/foobarbaz
     authorFBID: 503283835
    @@ -79,7 +79,7 @@
     
     

    Summary Truncation

    Use the <!--truncate--> marker in your blog post to represent what will be shown as the summary when viewing all blog published blog posts. Anything above <!--truncate--> will be part of the summary. For example:

    -
    ---
    +
    ---
     title: Truncation Example
     ---
     
    @@ -100,7 +100,7 @@
     

    You can configure a specific amount of blog posts to show by adding a blogSidebarCount setting to your siteConfig.js.

    The available options are an integer representing the number of posts you wish to show or a string with the value 'ALL'.

    Example:

    -
    blogSidebarCount: 'ALL'
    +
    blogSidebarCount: 'ALL'
     

    RSS Feed

    Docusaurus provides a simple RSS feed for your blog posts. Both RSS and Atom feed formats are supported. This data is automatically to your website page's HTML tag.

    @@ -121,7 +121,7 @@

    Now, when Docusaurus generates or builds your site, it will copy the file from static/index.html 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 /blog.

    You can use this template:

    -
    <!DOCTYPE HTML>
    +
    <!DOCTYPE HTML>
     <html lang="en-US">
       <head>
         <meta charset="UTF-8">
    diff --git a/docs/en/1.1.2/commands.html b/docs/en/1.1.2/commands.html
    index 0790d58a69..1cfe0a6c2e 100644
    --- a/docs/en/1.1.2/commands.html
    +++ b/docs/en/1.1.2/commands.html
    @@ -54,18 +54,18 @@
     
     

    Running from the command line

    The scripts can be run using either Yarn or npm. If you've already gone through our Getting Started guide, you may already be familiar with the start command. It's the command that tells Docusaurus to run the docusaurus-start script which generates the site and starts up a server, and it's usually invoked like so:

    -
    yarn run start
    +
    yarn run start
     

    The same script can be invoked using npm:

    -
    npm run start
    +
    npm run start
     

    To run a particular script, just replace the start command in the examples above with the command associated with your script.

    Using arguments

    Some commands support optional arguments. For example, to start a server on port 8080, you can specify the --port argument when running start:

    -
    yarn run start --port 8080
    +
    yarn run start --port 8080
     

    If you run Docusaurus using npm, you can still use the command line arguments by inserting a -- between npm run <command> and the command arguments:

    -
    npm run start -- --port 8080
    +
    npm run start -- --port 8080
     

    Configuration

    These scripts are set up under the "scripts" key in your website/package.json file as part of the installation process. If you need help setting them up again, please refer to the Installation guide.

    @@ -106,7 +106,7 @@

    Example

    -
    docusaurus-examples <feature>
    +
    docusaurus-examples <feature>
     

    When no feature is specified, sets up a minimally configured example website in your project. This command is covered in depth in the Site Preparation guide.


    @@ -119,7 +119,7 @@
  • USE_SSH: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.
  • Example

    -
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
    +
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
     

    The following environment variables are set by CircleCI during the build process.

      @@ -146,7 +146,7 @@

      Example

      -
      docusaurus-rename-version <currentVersion> <newVersion>
      +
      docusaurus-rename-version <currentVersion> <newVersion>
       

      See the Versioning guide to learn more.


      diff --git a/docs/en/1.1.2/commands/index.html b/docs/en/1.1.2/commands/index.html index 0790d58a69..1cfe0a6c2e 100644 --- a/docs/en/1.1.2/commands/index.html +++ b/docs/en/1.1.2/commands/index.html @@ -54,18 +54,18 @@

    Running from the command line

    The scripts can be run using either Yarn or npm. If you've already gone through our Getting Started guide, you may already be familiar with the start command. It's the command that tells Docusaurus to run the docusaurus-start script which generates the site and starts up a server, and it's usually invoked like so:

    -
    yarn run start
    +
    yarn run start
     

    The same script can be invoked using npm:

    -
    npm run start
    +
    npm run start
     

    To run a particular script, just replace the start command in the examples above with the command associated with your script.

    Using arguments

    Some commands support optional arguments. For example, to start a server on port 8080, you can specify the --port argument when running start:

    -
    yarn run start --port 8080
    +
    yarn run start --port 8080
     

    If you run Docusaurus using npm, you can still use the command line arguments by inserting a -- between npm run <command> and the command arguments:

    -
    npm run start -- --port 8080
    +
    npm run start -- --port 8080
     

    Configuration

    These scripts are set up under the "scripts" key in your website/package.json file as part of the installation process. If you need help setting them up again, please refer to the Installation guide.

    @@ -106,7 +106,7 @@

    Example

    -
    docusaurus-examples <feature>
    +
    docusaurus-examples <feature>
     

    When no feature is specified, sets up a minimally configured example website in your project. This command is covered in depth in the Site Preparation guide.


    @@ -119,7 +119,7 @@
  • USE_SSH: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.
  • Example

    -
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
    +
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
     

    The following environment variables are set by CircleCI during the build process.

      @@ -146,7 +146,7 @@

      Example

      -
      docusaurus-rename-version <currentVersion> <newVersion>
      +
      docusaurus-rename-version <currentVersion> <newVersion>
       

      See the Versioning guide to learn more.


      diff --git a/docs/en/1.1.2/custom-pages.html b/docs/en/1.1.2/custom-pages.html index c7f5dae60e..bcf46847ed 100644 --- a/docs/en/1.1.2/custom-pages.html +++ b/docs/en/1.1.2/custom-pages.html @@ -53,7 +53,7 @@

      You can start your local server and go to http://localhost:3000 to see what the example home page looks like. From there, edit the website/pages/en/index.js file and its various components to use the images and text you want for your project.

      Adding Other Custom Pages

      Docusaurus provides some simple example pages in the website/pages/en directory, including index.js, users.js, and help.js. These are good examples to showcase how to create a custom page for Docusaurus.

      -
      root-of-repo
      +
      root-of-repo
       ├── docs
       ├── website
       │   ├── blog
      @@ -85,7 +85,7 @@
       

      Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.

      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.

      If you do not want a footer for your site, change the render function of core/Footer.js to return null. e.g.,

      -
      const React = require('react');
      +
      const React = require('react');
       
       class Footer extends React.Component {
         render() {
      diff --git a/docs/en/1.1.2/custom-pages/index.html b/docs/en/1.1.2/custom-pages/index.html
      index c7f5dae60e..bcf46847ed 100644
      --- a/docs/en/1.1.2/custom-pages/index.html
      +++ b/docs/en/1.1.2/custom-pages/index.html
      @@ -53,7 +53,7 @@
       

      You can start your local server and go to http://localhost:3000 to see what the example home page looks like. From there, edit the website/pages/en/index.js file and its various components to use the images and text you want for your project.

      Adding Other Custom Pages

      Docusaurus provides some simple example pages in the website/pages/en directory, including index.js, users.js, and help.js. These are good examples to showcase how to create a custom page for Docusaurus.

      -
      root-of-repo
      +
      root-of-repo
       ├── docs
       ├── website
       │   ├── blog
      @@ -85,7 +85,7 @@
       

      Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.

      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.

      If you do not want a footer for your site, change the render function of core/Footer.js to return null. e.g.,

      -
      const React = require('react');
      +
      const React = require('react');
       
       class Footer extends React.Component {
         render() {
      diff --git a/docs/en/1.1.2/doc-markdown.html b/docs/en/1.1.2/doc-markdown.html
      index dcba972791..d29d9c3d43 100644
      --- a/docs/en/1.1.2/doc-markdown.html
      +++ b/docs/en/1.1.2/doc-markdown.html
      @@ -55,7 +55,7 @@
       

      hide_title: Whether to hide the title at the top of the doc.

      sidebar_label: The text shown in the document sidebar for this document. If this field is not present, the document's sidebar_label will default to its title.

      For example:

      -
      ---
      +
      ---
       id: doc1
       title: My Document
       sidebar_label: Document
      @@ -63,7 +63,7 @@
       

      Versioned documents have their ids altered to include the version number when they get copied. The new id is version-${version}-${id} where ${version} is the version number of that document and ${id} is the original id. Additionally, versioned documents get an added original_id field with the original document id.

      For example:

      -
      ---
      +
      ---
       id: version-1.0.0-doc1
       title: My Document
       sidebar_label: Document
      @@ -72,7 +72,7 @@
       

      custom_edit_url: The url for editing this document. If this field is not present, the document's edit url will fallback to editUrl from optional fields of siteConfig.js. See siteConfig.js docs for more information.

      For example:

      -
      ---
      +
      ---
       id: doc-markdown
       title: Markdown Features
       custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
      @@ -85,7 +85,7 @@
       

      authorURL: 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.

      authorFBID: 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.

      For example:

      -
      ---
      +
      ---
       title: My First Blog Post
       author: Frank Li
       authorURL: http://twitter.com/franchementli
      @@ -97,20 +97,20 @@
       

      Linking other Documents

      You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.

      Example:

      -
      [This links to another document](other-document.md)
      +
      [This links to another document](other-document.md)
       

      This markdown will automatically get converted into a link to /docs/other-document.html (or the appropriately translated/versioned link) once it gets rendered.

      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.

      Linking to Images and Other Assets

      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 docs/assets and website/blog/assets, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.

      Example:

      -
      ![alt-text](/docs/assets/doc-image.png)
      +
      ![alt-text](/docs/assets/doc-image.png)
       

      Generating Table of Contents

      You can make an autogenerated list of links, which can be useful as a table of contents for API docs.

      In your markdown file, insert a line with the text <AUTOGENERATED_TABLE_OF_CONTENTS>. Write your documentation using h3 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 <AUTOGENERATED_TABLE_OF_CONTENTS>.

      Example:

      -
      ### `docusaurus.function(a, b)`
      +
      ### `docusaurus.function(a, b)`
       
       Text describing my function
       
      @@ -119,7 +119,7 @@ Text describing my function
       Text describing my function
       

      will lead to a table of contents of the functions:

      -
      - `docusaurus.function(a, b)`
      +
      - `docusaurus.function(a, b)`
       - `docdoc(file)`
       

      and each function will link to their corresponding sections in the page.

      @@ -133,13 +133,13 @@ ReactDOM.render( ```

      ...would be rendered with syntax highlighting like so:

      -
      ReactDOM.render(
      +
      ReactDOM.render(
         <h1>Hello, world!</h1>,
         document.getElementById('root')
       );
       

      Highlighting is provided by Highlight.js using the theme specified in your siteConfig.js file as part of the highlight key:

      -
      {
      +
      {
         ...
         highlight: {
           theme: 'default'
      @@ -150,7 +150,7 @@ ReactDOM.render(
       

      You can find the full list of supported themes in the Highlight.js styles directory.

      Registering additional languages

      While Highlight.js provides support for many popular languages out of the box, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the hljs constant as part of the highlight config key. This in turn allows you to call registerLanguage:

      -
      {
      +
      {
         ...
         highlight: {
           theme: 'default',
      diff --git a/docs/en/1.1.2/doc-markdown/index.html b/docs/en/1.1.2/doc-markdown/index.html
      index dcba972791..d29d9c3d43 100644
      --- a/docs/en/1.1.2/doc-markdown/index.html
      +++ b/docs/en/1.1.2/doc-markdown/index.html
      @@ -55,7 +55,7 @@
       

      hide_title: Whether to hide the title at the top of the doc.

      sidebar_label: The text shown in the document sidebar for this document. If this field is not present, the document's sidebar_label will default to its title.

      For example:

      -
      ---
      +
      ---
       id: doc1
       title: My Document
       sidebar_label: Document
      @@ -63,7 +63,7 @@
       

      Versioned documents have their ids altered to include the version number when they get copied. The new id is version-${version}-${id} where ${version} is the version number of that document and ${id} is the original id. Additionally, versioned documents get an added original_id field with the original document id.

      For example:

      -
      ---
      +
      ---
       id: version-1.0.0-doc1
       title: My Document
       sidebar_label: Document
      @@ -72,7 +72,7 @@
       

      custom_edit_url: The url for editing this document. If this field is not present, the document's edit url will fallback to editUrl from optional fields of siteConfig.js. See siteConfig.js docs for more information.

      For example:

      -
      ---
      +
      ---
       id: doc-markdown
       title: Markdown Features
       custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
      @@ -85,7 +85,7 @@
       

      authorURL: 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.

      authorFBID: 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.

      For example:

      -
      ---
      +
      ---
       title: My First Blog Post
       author: Frank Li
       authorURL: http://twitter.com/franchementli
      @@ -97,20 +97,20 @@
       

      Linking other Documents

      You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.

      Example:

      -
      [This links to another document](other-document.md)
      +
      [This links to another document](other-document.md)
       

      This markdown will automatically get converted into a link to /docs/other-document.html (or the appropriately translated/versioned link) once it gets rendered.

      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.

      Linking to Images and Other Assets

      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 docs/assets and website/blog/assets, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.

      Example:

      -
      ![alt-text](/docs/assets/doc-image.png)
      +
      ![alt-text](/docs/assets/doc-image.png)
       

      Generating Table of Contents

      You can make an autogenerated list of links, which can be useful as a table of contents for API docs.

      In your markdown file, insert a line with the text <AUTOGENERATED_TABLE_OF_CONTENTS>. Write your documentation using h3 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 <AUTOGENERATED_TABLE_OF_CONTENTS>.

      Example:

      -
      ### `docusaurus.function(a, b)`
      +
      ### `docusaurus.function(a, b)`
       
       Text describing my function
       
      @@ -119,7 +119,7 @@ Text describing my function
       Text describing my function
       

      will lead to a table of contents of the functions:

      -
      - `docusaurus.function(a, b)`
      +
      - `docusaurus.function(a, b)`
       - `docdoc(file)`
       

      and each function will link to their corresponding sections in the page.

      @@ -133,13 +133,13 @@ ReactDOM.render( ```

      ...would be rendered with syntax highlighting like so:

      -
      ReactDOM.render(
      +
      ReactDOM.render(
         <h1>Hello, world!</h1>,
         document.getElementById('root')
       );
       

      Highlighting is provided by Highlight.js using the theme specified in your siteConfig.js file as part of the highlight key:

      -
      {
      +
      {
         ...
         highlight: {
           theme: 'default'
      @@ -150,7 +150,7 @@ ReactDOM.render(
       

      You can find the full list of supported themes in the Highlight.js styles directory.

      Registering additional languages

      While Highlight.js provides support for many popular languages out of the box, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the hljs constant as part of the highlight config key. This in turn allows you to call registerLanguage:

      -
      {
      +
      {
         ...
         highlight: {
           theme: 'default',
      diff --git a/docs/en/1.1.2/installation.html b/docs/en/1.1.2/installation.html
      index 6d4e223d62..06a55eb9c0 100644
      --- a/docs/en/1.1.2/installation.html
      +++ b/docs/en/1.1.2/installation.html
      @@ -62,7 +62,7 @@
       

      After Docusaurus is installed, moving forward, you can check your current version of Docusaurus by going into the website directory and typing yarn outdated docusaurus or npm outdated docusaurus. You can update to the latest version of Docusaurus by typing yarn upgrade docusaurus --latest or npm update docusaurus.

      Verifying Installation

      Along with previously existing files and directories, your root directory will now contain a structure similar to:

      -
      root-of-repo
      +
      root-of-repo
       ├── docs-examples-from-docusaurus
       │   ├── doc1.md
       │   ├── doc2.md
      diff --git a/docs/en/1.1.2/installation/index.html b/docs/en/1.1.2/installation/index.html
      index 6d4e223d62..06a55eb9c0 100644
      --- a/docs/en/1.1.2/installation/index.html
      +++ b/docs/en/1.1.2/installation/index.html
      @@ -62,7 +62,7 @@
       

      After Docusaurus is installed, moving forward, you can check your current version of Docusaurus by going into the website directory and typing yarn outdated docusaurus or npm outdated docusaurus. You can update to the latest version of Docusaurus by typing yarn upgrade docusaurus --latest or npm update docusaurus.

      Verifying Installation

      Along with previously existing files and directories, your root directory will now contain a structure similar to:

      -
      root-of-repo
      +
      root-of-repo
       ├── docs-examples-from-docusaurus
       │   ├── doc1.md
       │   ├── doc2.md
      diff --git a/docs/en/1.1.2/navigation.html b/docs/en/1.1.2/navigation.html
      index dd48fbf393..6187e9bc3a 100644
      --- a/docs/en/1.1.2/navigation.html
      +++ b/docs/en/1.1.2/navigation.html
      @@ -50,7 +50,7 @@
               
    Edit

    Navigation and Sidebars

    Referencing Site Documents

    If you want to reference another document in your docs folder (or the location you set via the optional customDocsPath path site configuration option), then you just use the name of the document you want to reference.

    For example, if you are in doc2.md and you want to reference doc1.md:

    -
    I am referencing a [document](doc1.md).
    +
    I am referencing a [document](doc1.md).
     

    Docusaurus currently does not support documents in nested folders; only in a flat folder structure. We are looking into adding support for nested folders.

    @@ -59,7 +59,7 @@

    New markdown files within docs will show up as pages on the website. Links to those documents are created first by using the id in the header of each document. If there is no id field, then the name of the file will serve as the link name.

    For example, creating an empty file such as docs/getting-started.md will enable the new page URL as /docs/getting-started.html.

    Suppose you add this to your document:

    -
    ---
    +
    ---
     id: intro
     title: Getting Started
     ---
    @@ -80,7 +80,7 @@
     

    Until you add your document to website/sidebars.json, they will only be accessible via a direct URL. The doc will not show up in any sidebar.

    Within sidebars.json, add the id you used in the document header to existing sidebar/category. In the below case, docs is the name of the sidebar and Getting Started is a category within the sidebar.

    -
    {
    +
    {
       "docs": {
         "Getting Started": [
           "getting-started"
    @@ -91,7 +91,7 @@
     }
     

    Or you can create a new category within the sidebar:

    -
    {
    +
    {
       "docs": {
         "My New Sidebar Category": [
           "getting-started"
    @@ -103,7 +103,7 @@
     

    Adding New Sidebars

    You can also put a document in a new sidebar. In the following example, we are creating an examples-sidebar sidebar within sidebars.json that has a category called My Example Category containing a document with an id of my-examples.

    -
    {
    +
    {
       "examples-sidebar": {
         "My Example Category": [
           "my-examples"
    @@ -118,7 +118,7 @@
     

    To expose sidebars, you will add clickable labels to the site navigation bar at the top of the website. You can add documents, pages and external links.

    Adding Documents

    After creating a new sidebar for the site by adding it to sidebars.json, you can expose the new sidebar from the top navigation bar by editing the headerLinks field of siteConfig.js.

    -
    {
    +
    {
       headerLinks: [
         ...
         { doc: 'my-examples', label: 'Examples' },
    @@ -130,7 +130,7 @@
     

    A label called Examples will be added to the site navigation bar and when you click on it at the top of your site, the examples-sidebar will be shown and the default document will be my-examples.

    Adding Custom Pages

    To add custom pages to the site navigation bar, entries can be added to the headerLinks of siteConfig.js. For example, if we have a page within website/pages/help.js, we can link to it by adding the following:

    -
    {
    +
    {
       headerLinks: [
         ...
         { page: 'help', label: 'Help' },
    @@ -142,7 +142,7 @@
     

    A label called Help will be added to the site navigation bar and when you click on it at the top of your site, the content from the help.js page will be shown.

    Adding External Links

    Custom links can be added to the site navigation bar with the following entry in siteConfig.js:

    -
    {
    +
    {
       headerLinks: [
         ...
         { href: 'https://github.com/facebook/Docusaurus', label: 'GitHub' },
    @@ -159,7 +159,7 @@
     

    You have limited control where the search and languages dropdown elements are shown in the site navigation bar at the top of your website.

    Search

    If search is enabled on your site, your search bar will appear to the right of your links. If you want to put the search bar between links in the header, add a search entry in the headerLinks config array:

    -
    {
    +
    {
       headerLinks: [
         { doc: 'foo', label: 'Foo' },
         { search: true },
    @@ -170,7 +170,7 @@
     

    Languages Dropdown

    If translations is enabled on your site, the language dropdown will appear to the right of your links (and to the left of the search bar, if search is enabled). If you want to put the language selection drop down between links in the header, add a languages entry in the headerLinks config array:

    -
    {
    +
    {
       headerLinks: [
         { doc: 'foo', label: 'Foo' },
         { languages: true },
    @@ -192,7 +192,7 @@
     

    These are two separate class names so you can have the active styles applied to either exact matches only or a bit more broadly for docs that belong together. If you don't want to make this distinction you can add both classes to the same CSS rule.

    Secondary On-Page Navigation

    We support secondary on-page navigation so you can more easily see the topics associated with a given document. To enable this feature, you need to add the onPageNav site configuration option to your siteConfig.js.

    -
    {
    +
    {
       onPageNav: 'separate',
       ...
     }
    diff --git a/docs/en/1.1.2/navigation/index.html b/docs/en/1.1.2/navigation/index.html
    index dd48fbf393..6187e9bc3a 100644
    --- a/docs/en/1.1.2/navigation/index.html
    +++ b/docs/en/1.1.2/navigation/index.html
    @@ -50,7 +50,7 @@
             
    Edit

    Navigation and Sidebars

    Referencing Site Documents

    If you want to reference another document in your docs folder (or the location you set via the optional customDocsPath path site configuration option), then you just use the name of the document you want to reference.

    For example, if you are in doc2.md and you want to reference doc1.md:

    -
    I am referencing a [document](doc1.md).
    +
    I am referencing a [document](doc1.md).
     

    Docusaurus currently does not support documents in nested folders; only in a flat folder structure. We are looking into adding support for nested folders.

    @@ -59,7 +59,7 @@

    New markdown files within docs will show up as pages on the website. Links to those documents are created first by using the id in the header of each document. If there is no id field, then the name of the file will serve as the link name.

    For example, creating an empty file such as docs/getting-started.md will enable the new page URL as /docs/getting-started.html.

    Suppose you add this to your document:

    -
    ---
    +
    ---
     id: intro
     title: Getting Started
     ---
    @@ -80,7 +80,7 @@
     

    Until you add your document to website/sidebars.json, they will only be accessible via a direct URL. The doc will not show up in any sidebar.

    Within sidebars.json, add the id you used in the document header to existing sidebar/category. In the below case, docs is the name of the sidebar and Getting Started is a category within the sidebar.

    -
    {
    +
    {
       "docs": {
         "Getting Started": [
           "getting-started"
    @@ -91,7 +91,7 @@
     }
     

    Or you can create a new category within the sidebar:

    -
    {
    +
    {
       "docs": {
         "My New Sidebar Category": [
           "getting-started"
    @@ -103,7 +103,7 @@
     

    Adding New Sidebars

    You can also put a document in a new sidebar. In the following example, we are creating an examples-sidebar sidebar within sidebars.json that has a category called My Example Category containing a document with an id of my-examples.

    -
    {
    +
    {
       "examples-sidebar": {
         "My Example Category": [
           "my-examples"
    @@ -118,7 +118,7 @@
     

    To expose sidebars, you will add clickable labels to the site navigation bar at the top of the website. You can add documents, pages and external links.

    Adding Documents

    After creating a new sidebar for the site by adding it to sidebars.json, you can expose the new sidebar from the top navigation bar by editing the headerLinks field of siteConfig.js.

    -
    {
    +
    {
       headerLinks: [
         ...
         { doc: 'my-examples', label: 'Examples' },
    @@ -130,7 +130,7 @@
     

    A label called Examples will be added to the site navigation bar and when you click on it at the top of your site, the examples-sidebar will be shown and the default document will be my-examples.

    Adding Custom Pages

    To add custom pages to the site navigation bar, entries can be added to the headerLinks of siteConfig.js. For example, if we have a page within website/pages/help.js, we can link to it by adding the following:

    -
    {
    +
    {
       headerLinks: [
         ...
         { page: 'help', label: 'Help' },
    @@ -142,7 +142,7 @@
     

    A label called Help will be added to the site navigation bar and when you click on it at the top of your site, the content from the help.js page will be shown.

    Adding External Links

    Custom links can be added to the site navigation bar with the following entry in siteConfig.js:

    -
    {
    +
    {
       headerLinks: [
         ...
         { href: 'https://github.com/facebook/Docusaurus', label: 'GitHub' },
    @@ -159,7 +159,7 @@
     

    You have limited control where the search and languages dropdown elements are shown in the site navigation bar at the top of your website.

    Search

    If search is enabled on your site, your search bar will appear to the right of your links. If you want to put the search bar between links in the header, add a search entry in the headerLinks config array:

    -
    {
    +
    {
       headerLinks: [
         { doc: 'foo', label: 'Foo' },
         { search: true },
    @@ -170,7 +170,7 @@
     

    Languages Dropdown

    If translations is enabled on your site, the language dropdown will appear to the right of your links (and to the left of the search bar, if search is enabled). If you want to put the language selection drop down between links in the header, add a languages entry in the headerLinks config array:

    -
    {
    +
    {
       headerLinks: [
         { doc: 'foo', label: 'Foo' },
         { languages: true },
    @@ -192,7 +192,7 @@
     

    These are two separate class names so you can have the active styles applied to either exact matches only or a bit more broadly for docs that belong together. If you don't want to make this distinction you can add both classes to the same CSS rule.

    Secondary On-Page Navigation

    We support secondary on-page navigation so you can more easily see the topics associated with a given document. To enable this feature, you need to add the onPageNav site configuration option to your siteConfig.js.

    -
    {
    +
    {
       onPageNav: 'separate',
       ...
     }
    diff --git a/docs/en/1.1.2/publishing.html b/docs/en/1.1.2/publishing.html
    index eaaf79ad6f..f5700a2f0f 100644
    --- a/docs/en/1.1.2/publishing.html
    +++ b/docs/en/1.1.2/publishing.html
    @@ -50,7 +50,7 @@
             
    Edit

    Publishing your site

    You should now have a site up and running locally. Once you have customized it to your liking, it's time to publish it. Docusaurus generates a static HTML website that is ready to be served by your favorite web server or online hosting solution.

    Building Static HTML Pages

    To create a static build of your website, run the following script from the website directory:

    -
    yarn run build # or `npm run build`
    +
    yarn run build # or `npm run build`
     

    This will generate a build folder inside the website directory containing the .html files from all of your docs and other pages included in pages.

    Hosting Static HTML Pages

    @@ -110,7 +110,7 @@

    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:

    To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate. If you run into issues related to SSH keys, visit Github's authentication documentation.

    -
    GIT_USER=<GIT_USER> \
    +
    GIT_USER=<GIT_USER> \
       CURRENT_BRANCH=master \
       USE_SSH=true \
       yarn run publish-gh-pages # or `npm run publish-gh-pages`
    @@ -134,7 +134,7 @@
     
  • Create a .circleci folder and create a config.yml under that folder.
  • Copy the text below into .circleci/config.yml.
  • -
    # If you only want circle to run on direct commits to master, you can uncomment this out
    +
    # If you only want circle to run on direct commits to master, you can uncomment this out
     # and uncomment the filters: *filter-only-master down below too
     #
     # aliases:
    @@ -181,7 +181,7 @@
     
     

    Tips & Tricks

    When initially deploying to a gh-pages branch using Circle CI, you may notice that some jobs triggered by commits to the gh-pages 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:

    -
    # Circle CI 2.0 Config File
    +
    # Circle CI 2.0 Config File
     # This config file will prevent tests from being run on the gh-pages branch.
     version: 2
     jobs:
    diff --git a/docs/en/1.1.2/publishing/index.html b/docs/en/1.1.2/publishing/index.html
    index eaaf79ad6f..f5700a2f0f 100644
    --- a/docs/en/1.1.2/publishing/index.html
    +++ b/docs/en/1.1.2/publishing/index.html
    @@ -50,7 +50,7 @@
             
    Edit

    Publishing your site

    You should now have a site up and running locally. Once you have customized it to your liking, it's time to publish it. Docusaurus generates a static HTML website that is ready to be served by your favorite web server or online hosting solution.

    Building Static HTML Pages

    To create a static build of your website, run the following script from the website directory:

    -
    yarn run build # or `npm run build`
    +
    yarn run build # or `npm run build`
     

    This will generate a build folder inside the website directory containing the .html files from all of your docs and other pages included in pages.

    Hosting Static HTML Pages

    @@ -110,7 +110,7 @@

    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:

    To run the script directly from the command-line, you can use the following, filling in the parameter values as appropriate. If you run into issues related to SSH keys, visit Github's authentication documentation.

    -
    GIT_USER=<GIT_USER> \
    +
    GIT_USER=<GIT_USER> \
       CURRENT_BRANCH=master \
       USE_SSH=true \
       yarn run publish-gh-pages # or `npm run publish-gh-pages`
    @@ -134,7 +134,7 @@
     
  • Create a .circleci folder and create a config.yml under that folder.
  • Copy the text below into .circleci/config.yml.
  • -
    # If you only want circle to run on direct commits to master, you can uncomment this out
    +
    # If you only want circle to run on direct commits to master, you can uncomment this out
     # and uncomment the filters: *filter-only-master down below too
     #
     # aliases:
    @@ -181,7 +181,7 @@
     
     

    Tips & Tricks

    When initially deploying to a gh-pages branch using Circle CI, you may notice that some jobs triggered by commits to the gh-pages 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:

    -
    # Circle CI 2.0 Config File
    +
    # Circle CI 2.0 Config File
     # This config file will prevent tests from being run on the gh-pages branch.
     version: 2
     jobs:
    diff --git a/docs/en/1.1.2/search.html b/docs/en/1.1.2/search.html
    index 82f3253019..46c3a7e23d 100644
    --- a/docs/en/1.1.2/search.html
    +++ b/docs/en/1.1.2/search.html
    @@ -51,7 +51,7 @@
     

    DocSearch works by crawling the content of your website every 24 hours and putting all the content in an Algolia index. This content is then queried directly from your front-end using the Algolia API. Note that your website need to be publicly available for this to work (ie. not behind a firewall). This service is free.

    Enabling the Search Bar

    Enter your API key and index name (sent by Algolia) into siteConfig.js in the algolia section to enable search for your site.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       algolia: {
         apiKey: 'my-api-key',
    @@ -65,7 +65,7 @@
     

    Controlling the Location of the Search Bar

    By default, the search bar will be the rightmost element in the top navigation bar.

    If you want to change the default location, add the searchBar flag in the headerLinks field of siteConfig.js in your desired location. For example, you may want the search bar between your internal and external links.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       headerLinks: [
         {...}
    diff --git a/docs/en/1.1.2/search/index.html b/docs/en/1.1.2/search/index.html
    index 82f3253019..46c3a7e23d 100644
    --- a/docs/en/1.1.2/search/index.html
    +++ b/docs/en/1.1.2/search/index.html
    @@ -51,7 +51,7 @@
     

    DocSearch works by crawling the content of your website every 24 hours and putting all the content in an Algolia index. This content is then queried directly from your front-end using the Algolia API. Note that your website need to be publicly available for this to work (ie. not behind a firewall). This service is free.

    Enabling the Search Bar

    Enter your API key and index name (sent by Algolia) into siteConfig.js in the algolia section to enable search for your site.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       algolia: {
         apiKey: 'my-api-key',
    @@ -65,7 +65,7 @@
     

    Controlling the Location of the Search Bar

    By default, the search bar will be the rightmost element in the top navigation bar.

    If you want to change the default location, add the searchBar flag in the headerLinks field of siteConfig.js in your desired location. For example, you may want the search bar between your internal and external links.

    -
    const siteConfig = {
    +
    const siteConfig = {
       ...
       headerLinks: [
         {...}
    diff --git a/docs/en/1.1.2/site-config.html b/docs/en/1.1.2/site-config.html
    index 5795899bec..33aed46013 100644
    --- a/docs/en/1.1.2/site-config.html
    +++ b/docs/en/1.1.2/site-config.html
    @@ -66,7 +66,7 @@
     

    headerIcon - url for icon used in header navigation bar.

    headerLinks - Links that will be used in the header navigation bar. The label field of each object will be the link text and will also be translated for each language.

    Example Usage:

    -
    headerLinks: [
    +
    headerLinks: [
       // Links to document with id doc1 for current language/version
       { doc: "doc1", label: "Getting Started" },
       // Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language
    @@ -97,9 +97,9 @@
     

    blogSidebarCount - Control the number of blog posts that show up in the sidebar. See the adding a blog docs for more information.

    cname - The CNAME for your website. It will go into a CNAME file when your site it built.

    customDocsPath - By default, Docusaurus expects your documentation to be in a directory called docs. This directory is at the same level as the website directory (i.e., not inside the website directory). You can specify a custom path to your documentation with this field. Note that all of your documentation *.md files must still reside in a flat hierarchy. You cannot have your documents in nested directories.

    -
    customDocsPath: 'docs/site';
    +
    customDocsPath: 'docs/site';
     
    -
    customDocsPath: 'website-docs';
    +
    customDocsPath: 'website-docs';
     

    defaultVersionShown - The default version for the site to be shown. If this is not set, the latest version will be shown.

    disableHeaderTitle - 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 true.

    @@ -110,7 +110,7 @@

    facebookPixelId - Facebook Pixel ID to track page views.

    fonts - Font-family css configuration for the site. If a font family is specified in siteConfig.js as $myFont, then adding a myFont key to an array in fonts will allow you to configure the font. Items appearing earlier in the array will take priority of later elements, so ordering of the fonts matter.

    In the below example, we have two sets of font configurations, myFont and myOtherFont. Times New Roman is the preferred font in myFont. -apple-system is the preferred in myOtherFont.

    -
    fonts: {
    +
    fonts: {
       myFont: [
         'Times New Roman',
         'Serif'
    @@ -122,7 +122,7 @@
     },
     

    The above fonts would be represented in your CSS file(s) as variables $myFont and $myOtherFont.

    -
    h1 {
    +
    h1 {
       font-family: $myFont;
     }
     
    @@ -155,7 +155,7 @@

    wrapPagesHTML - Boolean flag to indicate whether html files in /pages should be wrapped with Docusaurus site styles, header and footer. This feature is experimental and relies on the files being html fragments instead of complete pages. It inserts the contents of your html file with no extra processing. Defaults to false.

    Users can also add their own custom fields if they wish to provide some data across different files.

    Example siteConfig.js with many available fields

    -
    const users = [
    +
    const users = [
       {
         caption: 'User1',
         image: '/test-site/img/docusaurus.svg',
    diff --git a/docs/en/1.1.2/site-config/index.html b/docs/en/1.1.2/site-config/index.html
    index 5795899bec..33aed46013 100644
    --- a/docs/en/1.1.2/site-config/index.html
    +++ b/docs/en/1.1.2/site-config/index.html
    @@ -66,7 +66,7 @@
     

    headerIcon - url for icon used in header navigation bar.

    headerLinks - Links that will be used in the header navigation bar. The label field of each object will be the link text and will also be translated for each language.

    Example Usage:

    -
    headerLinks: [
    +
    headerLinks: [
       // Links to document with id doc1 for current language/version
       { doc: "doc1", label: "Getting Started" },
       // Link to page found at pages/en/help.js or if that does not exist, pages/help.js, for current language
    @@ -97,9 +97,9 @@
     

    blogSidebarCount - Control the number of blog posts that show up in the sidebar. See the adding a blog docs for more information.

    cname - The CNAME for your website. It will go into a CNAME file when your site it built.

    customDocsPath - By default, Docusaurus expects your documentation to be in a directory called docs. This directory is at the same level as the website directory (i.e., not inside the website directory). You can specify a custom path to your documentation with this field. Note that all of your documentation *.md files must still reside in a flat hierarchy. You cannot have your documents in nested directories.

    -
    customDocsPath: 'docs/site';
    +
    customDocsPath: 'docs/site';
     
    -
    customDocsPath: 'website-docs';
    +
    customDocsPath: 'website-docs';
     

    defaultVersionShown - The default version for the site to be shown. If this is not set, the latest version will be shown.

    disableHeaderTitle - 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 true.

    @@ -110,7 +110,7 @@

    facebookPixelId - Facebook Pixel ID to track page views.

    fonts - Font-family css configuration for the site. If a font family is specified in siteConfig.js as $myFont, then adding a myFont key to an array in fonts will allow you to configure the font. Items appearing earlier in the array will take priority of later elements, so ordering of the fonts matter.

    In the below example, we have two sets of font configurations, myFont and myOtherFont. Times New Roman is the preferred font in myFont. -apple-system is the preferred in myOtherFont.

    -
    fonts: {
    +
    fonts: {
       myFont: [
         'Times New Roman',
         'Serif'
    @@ -122,7 +122,7 @@
     },
     

    The above fonts would be represented in your CSS file(s) as variables $myFont and $myOtherFont.

    -
    h1 {
    +
    h1 {
       font-family: $myFont;
     }
     
    @@ -155,7 +155,7 @@

    wrapPagesHTML - Boolean flag to indicate whether html files in /pages should be wrapped with Docusaurus site styles, header and footer. This feature is experimental and relies on the files being html fragments instead of complete pages. It inserts the contents of your html file with no extra processing. Defaults to false.

    Users can also add their own custom fields if they wish to provide some data across different files.

    Example siteConfig.js with many available fields

    -
    const users = [
    +
    const users = [
       {
         caption: 'User1',
         image: '/test-site/img/docusaurus.svg',
    diff --git a/docs/en/1.1.2/site-creation.html b/docs/en/1.1.2/site-creation.html
    index ca3107a3d9..370032bd48 100644
    --- a/docs/en/1.1.2/site-creation.html
    +++ b/docs/en/1.1.2/site-creation.html
    @@ -51,7 +51,7 @@
     

    After installation and preparation, much of the work to create a basic site for your docs is already complete.

    Site Structure

    Your site structure looks like the following:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs
     ├── website
     │   ├── blog
    @@ -75,7 +75,7 @@
     

    To create a fully functional site, you only need to do a few steps:

    1. Add your documentation to the /docs folder as .md files, ensuring you have the proper header in each file. The simplest header would be the following, where id is the link name (e.g., docs/intro.html) and the title, is, of course, the title of the browser page.

      -
      ---
      +
      ---
       id: intro
       title: Getting Started
       ---
      @@ -93,7 +93,7 @@
       
    2. Place assets, such as images, in the website/static/ folder.
    3. Run the site to see the results of your changes.
    -
    cd website
    +
    cd website
     yarn run start # or `npm run start`
     # Navigate to http://localhost:3000
     
    @@ -104,7 +104,7 @@ yarn run start # or `npm run start`
  • Remove the index.js file from the website/pages directory, if it exists.
  • Add a custom static index.html page in the website/static folder with the following contents:
  • -
    <!DOCTYPE HTML>
    +
    <!DOCTYPE HTML>
     <html lang="en-US">
       <head>
         <meta charset="UTF-8">
    diff --git a/docs/en/1.1.2/site-creation/index.html b/docs/en/1.1.2/site-creation/index.html
    index ca3107a3d9..370032bd48 100644
    --- a/docs/en/1.1.2/site-creation/index.html
    +++ b/docs/en/1.1.2/site-creation/index.html
    @@ -51,7 +51,7 @@
     

    After installation and preparation, much of the work to create a basic site for your docs is already complete.

    Site Structure

    Your site structure looks like the following:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs
     ├── website
     │   ├── blog
    @@ -75,7 +75,7 @@
     

    To create a fully functional site, you only need to do a few steps:

    1. Add your documentation to the /docs folder as .md files, ensuring you have the proper header in each file. The simplest header would be the following, where id is the link name (e.g., docs/intro.html) and the title, is, of course, the title of the browser page.

      -
      ---
      +
      ---
       id: intro
       title: Getting Started
       ---
      @@ -93,7 +93,7 @@
       
    2. Place assets, such as images, in the website/static/ folder.
    3. Run the site to see the results of your changes.
    -
    cd website
    +
    cd website
     yarn run start # or `npm run start`
     # Navigate to http://localhost:3000
     
    @@ -104,7 +104,7 @@ yarn run start # or `npm run start`
  • Remove the index.js file from the website/pages directory, if it exists.
  • Add a custom static index.html page in the website/static folder with the following contents:
  • -
    <!DOCTYPE HTML>
    +
    <!DOCTYPE HTML>
     <html lang="en-US">
       <head>
         <meta charset="UTF-8">
    diff --git a/docs/en/1.1.2/site-preparation.html b/docs/en/1.1.2/site-preparation.html
    index 0b4d3e62e9..cd5100a241 100644
    --- a/docs/en/1.1.2/site-preparation.html
    +++ b/docs/en/1.1.2/site-preparation.html
    @@ -50,7 +50,7 @@
             
    Edit

    Site Preparation

    After installing Docusaurus, 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.

    Directory Structure

    As shown after you installed Docusaurus, the initialization script created a directory structure similar to:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs-examples-from-docusaurus
     │   ├── doc1.md
     │   ├── doc2.md
    diff --git a/docs/en/1.1.2/site-preparation/index.html b/docs/en/1.1.2/site-preparation/index.html
    index 0b4d3e62e9..cd5100a241 100644
    --- a/docs/en/1.1.2/site-preparation/index.html
    +++ b/docs/en/1.1.2/site-preparation/index.html
    @@ -50,7 +50,7 @@
             
    Edit

    Site Preparation

    After installing Docusaurus, 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.

    Directory Structure

    As shown after you installed Docusaurus, the initialization script created a directory structure similar to:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs-examples-from-docusaurus
     │   ├── doc1.md
     │   ├── doc2.md
    diff --git a/docs/en/1.1.2/translation.html b/docs/en/1.1.2/translation.html
    index 8726bd01f2..839a86052a 100644
    --- a/docs/en/1.1.2/translation.html
    +++ b/docs/en/1.1.2/translation.html
    @@ -50,13 +50,13 @@
             
    Edit

    Translations & Localization

    Docusaurus allows for easy translation functionality using Crowdin. Documentation files written in English are uploaded to Crowdin for translation by users within a community. Top-level pages written with English strings can be translated by wrapping any strings you want to translate in a <translate> tag. Other titles and labels will also be found and properly translated.

    Docusaurus Translation Configurations

    To generate example files for translations with Docusaurus, run the examples script with the command line argument translations:

    -
    npm run examples translations
    +
    npm run examples translations
     

    or

    -
    yarn examples translations
    +
    yarn examples translations
     

    This will create the following files:

    -
    pages/en/help-with-translations.js
    +
    pages/en/help-with-translations.js
     languages.js
     ../crowdin.yaml
     
    @@ -76,7 +76,7 @@ languages.js

    Pages allow you to customize layout and specific content of pages like a custom index page or help page.

    Pages with text that you want translated should be placed in website/pages/en folder.

    Wrap strings you want translated in a <translate> tag, and add the following require statement to the top of the file:

    -
    ...
    +
    ...
     const translate = require('../../server/translate.js').translate;
     ...
     <h2>
    @@ -85,7 +85,7 @@ languages.js
     ...
     

    You can also include an optional description attribute to give more context to a translator about how to translate the string:

    -
    <p>
    +
    <p>
       <translate desc="flower, not verb">Rose</translate>
     <p>
     
    @@ -95,7 +95,7 @@ languages.js

    Gathering Strings to Translate

    The strings within localized Pages must be extracted and provided to Crowdin.

    Add the following script to your website/package.json file, if it does not exist already:

    -
    {
    +
    {
       ...
       "scripts": {
         "write-translations": "docusaurus-write-translations"
    @@ -135,7 +135,7 @@ languages.js
     
     

    The example below can be automatically generated by the Docusaurus cli with the examples script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.

    Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.

    -
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
    +
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
     api_key_env: CROWDIN_DOCUSAURUS_API_KEY
     base_path: "./"
     preserve_hierarchy: true
    @@ -160,14 +160,14 @@ languages.js
     

    Setup the Crowdin Scripts

    You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in /docs as well as translatable strings in website/i18n/en.json. (These strings can be generated by running yarn write-translations.)

    You can add the following to your package.json to manually trigger Crowdin.

    -
    "scripts": {
    +
    "scripts": {
       "crowdin-upload": "crowdin --config ../crowdin.yaml upload sources --auto-update -b master",
       "crowdin-download": "crowdin --config ../crowdin.yaml download -b master"
     },
     

    Manual File Sync

    You will always want to upload your markdown files and translatable strings first and the download the translations section. So run the commands in this order:

    -
    CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-upload
    +
    CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-upload
     CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-download
     
    @@ -185,7 +185,7 @@ CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY

    Automated File Sync Using CircleCI

    You can automate pulling down and uploading translations for your files using the CircleCI web continuous integration service.

    First, update the circle.yml 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 circle.yml file:

    -
    machine:
    +
    machine:
       node:
         version: 6.10.3
       npm:
    @@ -221,7 +221,7 @@ CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY
     

    If you wish to use Crowdin on your machine locally, you can install the Crowdin CLI tool and run the same commands found in the circle.yaml file. The only difference is that you must set project_identifier and api_key values in the crowdin.yaml file since you will not have Circle environment variables set up.

    Versioned Translations

    If you wish to have translation and versioning for your documentation, add the following section to the end of your crowdin.yaml file:

    -
      -
    +
      -
         source: '/website/versioned_docs/**/*.md'
         translation: '/website/translated_docs/%locale%/**/%original_file_name%'
         languages_mapping: *anchor
    diff --git a/docs/en/1.1.2/translation/index.html b/docs/en/1.1.2/translation/index.html
    index 8726bd01f2..839a86052a 100644
    --- a/docs/en/1.1.2/translation/index.html
    +++ b/docs/en/1.1.2/translation/index.html
    @@ -50,13 +50,13 @@
             
    Edit

    Translations & Localization

    Docusaurus allows for easy translation functionality using Crowdin. Documentation files written in English are uploaded to Crowdin for translation by users within a community. Top-level pages written with English strings can be translated by wrapping any strings you want to translate in a <translate> tag. Other titles and labels will also be found and properly translated.

    Docusaurus Translation Configurations

    To generate example files for translations with Docusaurus, run the examples script with the command line argument translations:

    -
    npm run examples translations
    +
    npm run examples translations
     

    or

    -
    yarn examples translations
    +
    yarn examples translations
     

    This will create the following files:

    -
    pages/en/help-with-translations.js
    +
    pages/en/help-with-translations.js
     languages.js
     ../crowdin.yaml
     
    @@ -76,7 +76,7 @@ languages.js

    Pages allow you to customize layout and specific content of pages like a custom index page or help page.

    Pages with text that you want translated should be placed in website/pages/en folder.

    Wrap strings you want translated in a <translate> tag, and add the following require statement to the top of the file:

    -
    ...
    +
    ...
     const translate = require('../../server/translate.js').translate;
     ...
     <h2>
    @@ -85,7 +85,7 @@ languages.js
     ...
     

    You can also include an optional description attribute to give more context to a translator about how to translate the string:

    -
    <p>
    +
    <p>
       <translate desc="flower, not verb">Rose</translate>
     <p>
     
    @@ -95,7 +95,7 @@ languages.js

    Gathering Strings to Translate

    The strings within localized Pages must be extracted and provided to Crowdin.

    Add the following script to your website/package.json file, if it does not exist already:

    -
    {
    +
    {
       ...
       "scripts": {
         "write-translations": "docusaurus-write-translations"
    @@ -135,7 +135,7 @@ languages.js
     
     

    The example below can be automatically generated by the Docusaurus cli with the examples script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.

    Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.

    -
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
    +
    project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
     api_key_env: CROWDIN_DOCUSAURUS_API_KEY
     base_path: "./"
     preserve_hierarchy: true
    @@ -160,14 +160,14 @@ languages.js
     

    Setup the Crowdin Scripts

    You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in /docs as well as translatable strings in website/i18n/en.json. (These strings can be generated by running yarn write-translations.)

    You can add the following to your package.json to manually trigger Crowdin.

    -
    "scripts": {
    +
    "scripts": {
       "crowdin-upload": "crowdin --config ../crowdin.yaml upload sources --auto-update -b master",
       "crowdin-download": "crowdin --config ../crowdin.yaml download -b master"
     },
     

    Manual File Sync

    You will always want to upload your markdown files and translatable strings first and the download the translations section. So run the commands in this order:

    -
    CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-upload
    +
    CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-upload
     CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-download
     
    @@ -185,7 +185,7 @@ CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY

    Automated File Sync Using CircleCI

    You can automate pulling down and uploading translations for your files using the CircleCI web continuous integration service.

    First, update the circle.yml 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 circle.yml file:

    -
    machine:
    +
    machine:
       node:
         version: 6.10.3
       npm:
    @@ -221,7 +221,7 @@ CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY
     

    If you wish to use Crowdin on your machine locally, you can install the Crowdin CLI tool and run the same commands found in the circle.yaml file. The only difference is that you must set project_identifier and api_key values in the crowdin.yaml file since you will not have Circle environment variables set up.

    Versioned Translations

    If you wish to have translation and versioning for your documentation, add the following section to the end of your crowdin.yaml file:

    -
      -
    +
      -
         source: '/website/versioned_docs/**/*.md'
         translation: '/website/translated_docs/%locale%/**/%original_file_name%'
         languages_mapping: *anchor
    diff --git a/docs/en/1.1.2/versioning.html b/docs/en/1.1.2/versioning.html
    index 70c18f7797..85e79bdede 100644
    --- a/docs/en/1.1.2/versioning.html
    +++ b/docs/en/1.1.2/versioning.html
    @@ -50,19 +50,19 @@
             
    Edit

    Versioning

    You can use the version script to cut a new documentation version based on the latest content in the docs folder. That specific set of documentation will then be preserved and accessible even as the documentation in the docs folder changes moving forward.

    How to Create New Versions

    Run the following script to generate a starter versions page listing all the site versions:

    -
    yarn examples versions
    +
    yarn examples versions
     

    This creates the pages/en/versions.js file.

    You can edit this file later on to customize how you display the versions.

    Add the following script to your package.json file if it doesn't already exist:

    -
    ...
    +
    ...
     "scripts": {
       "version": "docusaurus-version"
     },
     ...
     

    Run the script with a command line argument of the version you wish to create. e.g.,

    -
    yarn run version 1.0.0
    +
    yarn run version 1.0.0
     

    This will preserve all documents currently in the docs folder and make them available as documentation for version 1.0.0.

    If, for example, you ran the version script with 1.0.0 as the version number, version 1.0.0 is considered the latest release version for your project. 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.

    @@ -93,14 +93,14 @@

    For example, a document with the original id doc1 exists for the latest version, 1.0.0, and has the same content as the document with the id doc1 in the docs folder. When a new version 2.0.0 is created, the file for doc1 will not be copied into versioned_docs/version-2.0.0/. There will still be a page for docs/2.0.0/doc1.html, but it will use the file from version 1.0.0.

    Renaming Existing Versions

    To rename an existing version number to something else, first make sure the following script is in your package.json file:

    -
    ...
    +
    ...
     "scripts": {
       "rename-version": "docusaurus-rename-version"
     },
     ...
     

    Run the script with command line arguments of first, the current version name, then second, the new version name. e.g.,

    -
    yarn run rename-version 1.0.0 1.0.1
    +
    yarn run rename-version 1.0.0 1.0.1
     

    Versioning and Translations

    If you wish to use versioning and translations features, the crowdin.yaml 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 translated_docs/${language}/version-${version}/. For more information, check out the translations guide.

    diff --git a/docs/en/1.1.2/versioning/index.html b/docs/en/1.1.2/versioning/index.html index 70c18f7797..85e79bdede 100644 --- a/docs/en/1.1.2/versioning/index.html +++ b/docs/en/1.1.2/versioning/index.html @@ -50,19 +50,19 @@
    Edit

    Versioning

    You can use the version script to cut a new documentation version based on the latest content in the docs folder. That specific set of documentation will then be preserved and accessible even as the documentation in the docs folder changes moving forward.

    How to Create New Versions

    Run the following script to generate a starter versions page listing all the site versions:

    -
    yarn examples versions
    +
    yarn examples versions
     

    This creates the pages/en/versions.js file.

    You can edit this file later on to customize how you display the versions.

    Add the following script to your package.json file if it doesn't already exist:

    -
    ...
    +
    ...
     "scripts": {
       "version": "docusaurus-version"
     },
     ...
     

    Run the script with a command line argument of the version you wish to create. e.g.,

    -
    yarn run version 1.0.0
    +
    yarn run version 1.0.0
     

    This will preserve all documents currently in the docs folder and make them available as documentation for version 1.0.0.

    If, for example, you ran the version script with 1.0.0 as the version number, version 1.0.0 is considered the latest release version for your project. 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.

    @@ -93,14 +93,14 @@

    For example, a document with the original id doc1 exists for the latest version, 1.0.0, and has the same content as the document with the id doc1 in the docs folder. When a new version 2.0.0 is created, the file for doc1 will not be copied into versioned_docs/version-2.0.0/. There will still be a page for docs/2.0.0/doc1.html, but it will use the file from version 1.0.0.

    Renaming Existing Versions

    To rename an existing version number to something else, first make sure the following script is in your package.json file:

    -
    ...
    +
    ...
     "scripts": {
       "rename-version": "docusaurus-rename-version"
     },
     ...
     

    Run the script with command line arguments of first, the current version name, then second, the new version name. e.g.,

    -
    yarn run rename-version 1.0.0 1.0.1
    +
    yarn run rename-version 1.0.0 1.0.1
     

    Versioning and Translations

    If you wish to use versioning and translations features, the crowdin.yaml 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 translated_docs/${language}/version-${version}/. For more information, check out the translations guide.

    diff --git a/docs/en/1.1.3/api-pages.html b/docs/en/1.1.3/api-pages.html index d98f15a7d7..25efe3ca12 100644 --- a/docs/en/1.1.3/api-pages.html +++ b/docs/en/1.1.3/api-pages.html @@ -59,7 +59,7 @@

    CompLibrary.MarkdownBlock

    A React component that parses markdown and renders to HTML.

    Example:

    -
    const MarkdownBlock = CompLibrary.MarkdownBlock;
    +
    const MarkdownBlock = CompLibrary.MarkdownBlock;
     
     <MarkdownBlock>
       [Markdown syntax for a link](http://www.example.com)
    @@ -79,7 +79,7 @@
     
     
     

    Example

    -
    <Container
    +
    <Container
       padding={['bottom', 'top']}
       background="light"
       className="myCustomClass">
    @@ -115,7 +115,7 @@
     
     
     

    Example

    -
    <GridBlock
    +
    <GridBlock
       align="center"
       layout="threeColumn"
       className="myCustomClass"
    @@ -144,19 +144,19 @@
     

    Translating Strings

    When translations are enabled, any pages inside website/pages/en will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the languages.js file. E.g. The url for a French page of website/pages/en/help.js would be found at ${baseUrl}fr/help.html.

    When writing pages that you wish to translate, wrap any strings to be translated inside a <translate> tag. e.g.,

    -
    <p>
    +
    <p>
       <translate>I like translations</translate>
     </p>
     

    You can also provide an optional description attribute to provide context for translators. e.g,

    -
    <a href="/community">
    +
    <a href="/community">
       <translate desc="Footer link to page referring to community GitHub and Slack">
         Community
       </translate>
     </a>
     

    Add the following require statement as well:

    -
    const translate = require('../../server/translate.js').translate;
    +
    const translate = require('../../server/translate.js').translate;
     

    Note that this path is valid for files inside pages/en and should be adjusted accordingly if files are in different locations, as discussed above.

    Using Static Assets

    diff --git a/docs/en/1.1.3/api-pages/index.html b/docs/en/1.1.3/api-pages/index.html index d98f15a7d7..25efe3ca12 100644 --- a/docs/en/1.1.3/api-pages/index.html +++ b/docs/en/1.1.3/api-pages/index.html @@ -59,7 +59,7 @@

    CompLibrary.MarkdownBlock

    A React component that parses markdown and renders to HTML.

    Example:

    -
    const MarkdownBlock = CompLibrary.MarkdownBlock;
    +
    const MarkdownBlock = CompLibrary.MarkdownBlock;
     
     <MarkdownBlock>
       [Markdown syntax for a link](http://www.example.com)
    @@ -79,7 +79,7 @@
     
     
     

    Example

    -
    <Container
    +
    <Container
       padding={['bottom', 'top']}
       background="light"
       className="myCustomClass">
    @@ -115,7 +115,7 @@
     
     
     

    Example

    -
    <GridBlock
    +
    <GridBlock
       align="center"
       layout="threeColumn"
       className="myCustomClass"
    @@ -144,19 +144,19 @@
     

    Translating Strings

    When translations are enabled, any pages inside website/pages/en will be translated for all enabled languages. Urls for non-English pages will use their language tags as specified in the languages.js file. E.g. The url for a French page of website/pages/en/help.js would be found at ${baseUrl}fr/help.html.

    When writing pages that you wish to translate, wrap any strings to be translated inside a <translate> tag. e.g.,

    -
    <p>
    +
    <p>
       <translate>I like translations</translate>
     </p>
     

    You can also provide an optional description attribute to provide context for translators. e.g,

    -
    <a href="/community">
    +
    <a href="/community">
       <translate desc="Footer link to page referring to community GitHub and Slack">
         Community
       </translate>
     </a>
     

    Add the following require statement as well:

    -
    const translate = require('../../server/translate.js').translate;
    +
    const translate = require('../../server/translate.js').translate;
     

    Note that this path is valid for files inside pages/en and should be adjusted accordingly if files are in different locations, as discussed above.

    Using Static Assets

    diff --git a/docs/en/1.1.3/blog.html b/docs/en/1.1.3/blog.html index 5117b3a149..2e6948edfa 100644 --- a/docs/en/1.1.3/blog.html +++ b/docs/en/1.1.3/blog.html @@ -50,7 +50,7 @@
    Edit

    Adding a Blog

    Initial Setup

    To setup your site's blog, start by creating a blog folder within your repo's website directory.

    Then, add a header link to your blog within siteConfig.js:

    -
    headerLinks: [
    +
    headerLinks: [
         ...
         { blog: true, label: 'Blog' },
         ...
    @@ -59,7 +59,7 @@
     

    Adding Posts

    To publish in the blog, create a file within the blog folder with a formatted name of YYYY-MM-DD-My-Blog-Post-Title.md. The post date is extracted from the file name.

    For example, at website/blog/2017-08-18-Introducing-Docusaurus.md:

    -
    ---
    +
    ---
     author: Frank Li
     authorURL: https://twitter.com/foobarbaz
     authorFBID: 503283835
    @@ -79,7 +79,7 @@
     
     

    Summary Truncation

    Use the <!--truncate--> marker in your blog post to represent what will be shown as the summary when viewing all blog published blog posts. Anything above <!--truncate--> will be part of the summary. For example:

    -
    ---
    +
    ---
     title: Truncation Example
     ---
     
    @@ -100,7 +100,7 @@
     

    You can configure a specific amount of blog posts to show by adding a blogSidebarCount setting to your siteConfig.js.

    The available options are an integer representing the number of posts you wish to show or a string with the value 'ALL'.

    Example:

    -
    blogSidebarCount: 'ALL'
    +
    blogSidebarCount: 'ALL'
     

    RSS Feed

    Docusaurus provides a simple RSS feed for your blog posts. Both RSS and Atom feed formats are supported. This data is automatically to your website page's HTML tag.

    @@ -121,7 +121,7 @@

    Now, when Docusaurus generates or builds your site, it will copy the file from static/index.html 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 /blog.

    You can use this template:

    -
    <!DOCTYPE HTML>
    +
    <!DOCTYPE HTML>
     <html lang="en-US">
       <head>
         <meta charset="UTF-8">
    diff --git a/docs/en/1.1.3/blog/index.html b/docs/en/1.1.3/blog/index.html
    index 5117b3a149..2e6948edfa 100644
    --- a/docs/en/1.1.3/blog/index.html
    +++ b/docs/en/1.1.3/blog/index.html
    @@ -50,7 +50,7 @@
             
    Edit

    Adding a Blog

    Initial Setup

    To setup your site's blog, start by creating a blog folder within your repo's website directory.

    Then, add a header link to your blog within siteConfig.js:

    -
    headerLinks: [
    +
    headerLinks: [
         ...
         { blog: true, label: 'Blog' },
         ...
    @@ -59,7 +59,7 @@
     

    Adding Posts

    To publish in the blog, create a file within the blog folder with a formatted name of YYYY-MM-DD-My-Blog-Post-Title.md. The post date is extracted from the file name.

    For example, at website/blog/2017-08-18-Introducing-Docusaurus.md:

    -
    ---
    +
    ---
     author: Frank Li
     authorURL: https://twitter.com/foobarbaz
     authorFBID: 503283835
    @@ -79,7 +79,7 @@
     
     

    Summary Truncation

    Use the <!--truncate--> marker in your blog post to represent what will be shown as the summary when viewing all blog published blog posts. Anything above <!--truncate--> will be part of the summary. For example:

    -
    ---
    +
    ---
     title: Truncation Example
     ---
     
    @@ -100,7 +100,7 @@
     

    You can configure a specific amount of blog posts to show by adding a blogSidebarCount setting to your siteConfig.js.

    The available options are an integer representing the number of posts you wish to show or a string with the value 'ALL'.

    Example:

    -
    blogSidebarCount: 'ALL'
    +
    blogSidebarCount: 'ALL'
     

    RSS Feed

    Docusaurus provides a simple RSS feed for your blog posts. Both RSS and Atom feed formats are supported. This data is automatically to your website page's HTML tag.

    @@ -121,7 +121,7 @@

    Now, when Docusaurus generates or builds your site, it will copy the file from static/index.html 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 /blog.

    You can use this template:

    -
    <!DOCTYPE HTML>
    +
    <!DOCTYPE HTML>
     <html lang="en-US">
       <head>
         <meta charset="UTF-8">
    diff --git a/docs/en/1.1.3/commands.html b/docs/en/1.1.3/commands.html
    index 80baa425f9..789dc7e0fd 100644
    --- a/docs/en/1.1.3/commands.html
    +++ b/docs/en/1.1.3/commands.html
    @@ -54,18 +54,18 @@
     
     

    Running from the command line

    The scripts can be run using either Yarn or npm. If you've already gone through our Getting Started guide, you may already be familiar with the start command. It's the command that tells Docusaurus to run the docusaurus-start script which generates the site and starts up a server, and it's usually invoked like so:

    -
    yarn run start
    +
    yarn run start
     

    The same script can be invoked using npm:

    -
    npm run start
    +
    npm run start
     

    To run a particular script, just replace the start command in the examples above with the command associated with your script.

    Using arguments

    Some commands support optional arguments. For example, to start a server on port 8080, you can specify the --port argument when running start:

    -
    yarn run start --port 8080
    +
    yarn run start --port 8080
     

    If you run Docusaurus using npm, you can still use the command line arguments by inserting a -- between npm run <command> and the command arguments:

    -
    npm run start -- --port 8080
    +
    npm run start -- --port 8080
     

    Configuration

    These scripts are set up under the "scripts" key in your website/package.json file as part of the installation process. If you need help setting them up again, please refer to the Installation guide.

    @@ -106,7 +106,7 @@

    Example

    -
    docusaurus-examples <feature>
    +
    docusaurus-examples <feature>
     

    When no feature is specified, sets up a minimally configured example website in your project. This command is covered in depth in the Site Preparation guide.


    @@ -119,7 +119,7 @@
  • USE_SSH: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.
  • Example

    -
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
    +
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
     

    The following environment variables are set by CircleCI during the build process.

      @@ -146,7 +146,7 @@

      Example

      -
      docusaurus-rename-version <currentVersion> <newVersion>
      +
      docusaurus-rename-version <currentVersion> <newVersion>
       

      See the Versioning guide to learn more.


      diff --git a/docs/en/1.1.3/commands/index.html b/docs/en/1.1.3/commands/index.html index 80baa425f9..789dc7e0fd 100644 --- a/docs/en/1.1.3/commands/index.html +++ b/docs/en/1.1.3/commands/index.html @@ -54,18 +54,18 @@

    Running from the command line

    The scripts can be run using either Yarn or npm. If you've already gone through our Getting Started guide, you may already be familiar with the start command. It's the command that tells Docusaurus to run the docusaurus-start script which generates the site and starts up a server, and it's usually invoked like so:

    -
    yarn run start
    +
    yarn run start
     

    The same script can be invoked using npm:

    -
    npm run start
    +
    npm run start
     

    To run a particular script, just replace the start command in the examples above with the command associated with your script.

    Using arguments

    Some commands support optional arguments. For example, to start a server on port 8080, you can specify the --port argument when running start:

    -
    yarn run start --port 8080
    +
    yarn run start --port 8080
     

    If you run Docusaurus using npm, you can still use the command line arguments by inserting a -- between npm run <command> and the command arguments:

    -
    npm run start -- --port 8080
    +
    npm run start -- --port 8080
     

    Configuration

    These scripts are set up under the "scripts" key in your website/package.json file as part of the installation process. If you need help setting them up again, please refer to the Installation guide.

    @@ -106,7 +106,7 @@

    Example

    -
    docusaurus-examples <feature>
    +
    docusaurus-examples <feature>
     

    When no feature is specified, sets up a minimally configured example website in your project. This command is covered in depth in the Site Preparation guide.


    @@ -119,7 +119,7 @@
  • USE_SSH: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.
  • Example

    -
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
    +
    GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
     

    The following environment variables are set by CircleCI during the build process.

      @@ -146,7 +146,7 @@

      Example

      -
      docusaurus-rename-version <currentVersion> <newVersion>
      +
      docusaurus-rename-version <currentVersion> <newVersion>
       

      See the Versioning guide to learn more.


      diff --git a/docs/en/1.1.3/custom-pages.html b/docs/en/1.1.3/custom-pages.html index 6e2eff0ac7..49aaf1159e 100644 --- a/docs/en/1.1.3/custom-pages.html +++ b/docs/en/1.1.3/custom-pages.html @@ -53,7 +53,7 @@

      You can start your local server and go to http://localhost:3000 to see what the example home page looks like. From there, edit the website/pages/en/index.js file and its various components to use the images and text you want for your project.

      Adding Other Custom Pages

      Docusaurus provides some simple example pages in the website/pages/en directory, including index.js, users.js, and help.js. These are good examples to showcase how to create a custom page for Docusaurus.

      -
      root-of-repo
      +
      root-of-repo
       ├── docs
       ├── website
       │   ├── blog
      @@ -85,7 +85,7 @@
       

      Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.

      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.

      If you do not want a footer for your site, change the render function of core/Footer.js to return null. e.g.,

      -
      const React = require('react');
      +
      const React = require('react');
       
       class Footer extends React.Component {
         render() {
      diff --git a/docs/en/1.1.3/custom-pages/index.html b/docs/en/1.1.3/custom-pages/index.html
      index 6e2eff0ac7..49aaf1159e 100644
      --- a/docs/en/1.1.3/custom-pages/index.html
      +++ b/docs/en/1.1.3/custom-pages/index.html
      @@ -53,7 +53,7 @@
       

      You can start your local server and go to http://localhost:3000 to see what the example home page looks like. From there, edit the website/pages/en/index.js file and its various components to use the images and text you want for your project.

      Adding Other Custom Pages

      Docusaurus provides some simple example pages in the website/pages/en directory, including index.js, users.js, and help.js. These are good examples to showcase how to create a custom page for Docusaurus.

      -
      root-of-repo
      +
      root-of-repo
       ├── docs
       ├── website
       │   ├── blog
      @@ -85,7 +85,7 @@
       

      Some suggestions for links you may want to provide: documentation, API, Twitter, Discord, Facebook groups, Stack Overflow, GitHub, etc.

      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.

      If you do not want a footer for your site, change the render function of core/Footer.js to return null. e.g.,

      -
      const React = require('react');
      +
      const React = require('react');
       
       class Footer extends React.Component {
         render() {
      diff --git a/docs/en/1.1.3/doc-markdown.html b/docs/en/1.1.3/doc-markdown.html
      index 99a2615412..3ee6f43ddc 100644
      --- a/docs/en/1.1.3/doc-markdown.html
      +++ b/docs/en/1.1.3/doc-markdown.html
      @@ -55,7 +55,7 @@
       

      hide_title: Whether to hide the title at the top of the doc.

      sidebar_label: The text shown in the document sidebar for this document. If this field is not present, the document's sidebar_label will default to its title.

      For example:

      -
      ---
      +
      ---
       id: doc1
       title: My Document
       sidebar_label: Document
      @@ -63,7 +63,7 @@
       

      Versioned documents have their ids altered to include the version number when they get copied. The new id is version-${version}-${id} where ${version} is the version number of that document and ${id} is the original id. Additionally, versioned documents get an added original_id field with the original document id.

      For example:

      -
      ---
      +
      ---
       id: version-1.0.0-doc1
       title: My Document
       sidebar_label: Document
      @@ -72,7 +72,7 @@
       

      custom_edit_url: The url for editing this document. If this field is not present, the document's edit url will fallback to editUrl from optional fields of siteConfig.js. See siteConfig.js docs for more information.

      For example:

      -
      ---
      +
      ---
       id: doc-markdown
       title: Markdown Features
       custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
      @@ -85,7 +85,7 @@
       

      authorURL: 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.

      authorFBID: 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.

      For example:

      -
      ---
      +
      ---
       title: My First Blog Post
       author: Frank Li
       authorURL: http://twitter.com/franchementli
      @@ -97,20 +97,20 @@
       

      Linking other Documents

      You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.

      Example:

      -
      [This links to another document](other-document.md)
      +
      [This links to another document](other-document.md)
       

      This markdown will automatically get converted into a link to /docs/other-document.html (or the appropriately translated/versioned link) once it gets rendered.

      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.

      Linking to Images and Other Assets

      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 docs/assets and website/blog/assets, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.

      Example:

      -
      ![alt-text](/docs/assets/doc-image.png)
      +
      ![alt-text](/docs/assets/doc-image.png)
       

      Generating Table of Contents

      You can make an autogenerated list of links, which can be useful as a table of contents for API docs.

      In your markdown file, insert a line with the text <AUTOGENERATED_TABLE_OF_CONTENTS>. Write your documentation using h3 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 <AUTOGENERATED_TABLE_OF_CONTENTS>.

      Example:

      -
      ### `docusaurus.function(a, b)`
      +
      ### `docusaurus.function(a, b)`
       
       Text describing my function
       
      @@ -119,7 +119,7 @@ Text describing my function
       Text describing my function
       

      will lead to a table of contents of the functions:

      -
      - `docusaurus.function(a, b)`
      +
      - `docusaurus.function(a, b)`
       - `docdoc(file)`
       

      and each function will link to their corresponding sections in the page.

      @@ -133,13 +133,13 @@ ReactDOM.render( ```

      ...would be rendered with syntax highlighting like so:

      -
      ReactDOM.render(
      +
      ReactDOM.render(
         <h1>Hello, world!</h1>,
         document.getElementById('root')
       );
       

      Highlighting is provided by Highlight.js using the theme specified in your siteConfig.js file as part of the highlight key:

      -
      {
      +
      {
         ...
         highlight: {
           theme: 'default'
      @@ -150,7 +150,7 @@ ReactDOM.render(
       

      You can find the full list of supported themes in the Highlight.js styles directory.

      Registering additional languages

      While Highlight.js provides support for many popular languages out of the box, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the hljs constant as part of the highlight config key. This in turn allows you to call registerLanguage:

      -
      {
      +
      {
         ...
         highlight: {
           theme: 'default',
      diff --git a/docs/en/1.1.3/doc-markdown/index.html b/docs/en/1.1.3/doc-markdown/index.html
      index 99a2615412..3ee6f43ddc 100644
      --- a/docs/en/1.1.3/doc-markdown/index.html
      +++ b/docs/en/1.1.3/doc-markdown/index.html
      @@ -55,7 +55,7 @@
       

      hide_title: Whether to hide the title at the top of the doc.

      sidebar_label: The text shown in the document sidebar for this document. If this field is not present, the document's sidebar_label will default to its title.

      For example:

      -
      ---
      +
      ---
       id: doc1
       title: My Document
       sidebar_label: Document
      @@ -63,7 +63,7 @@
       

      Versioned documents have their ids altered to include the version number when they get copied. The new id is version-${version}-${id} where ${version} is the version number of that document and ${id} is the original id. Additionally, versioned documents get an added original_id field with the original document id.

      For example:

      -
      ---
      +
      ---
       id: version-1.0.0-doc1
       title: My Document
       sidebar_label: Document
      @@ -72,7 +72,7 @@
       

      custom_edit_url: The url for editing this document. If this field is not present, the document's edit url will fallback to editUrl from optional fields of siteConfig.js. See siteConfig.js docs for more information.

      For example:

      -
      ---
      +
      ---
       id: doc-markdown
       title: Markdown Features
       custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
      @@ -85,7 +85,7 @@
       

      authorURL: 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.

      authorFBID: 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.

      For example:

      -
      ---
      +
      ---
       title: My First Blog Post
       author: Frank Li
       authorURL: http://twitter.com/franchementli
      @@ -97,20 +97,20 @@
       

      Linking other Documents

      You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.

      Example:

      -
      [This links to another document](other-document.md)
      +
      [This links to another document](other-document.md)
       

      This markdown will automatically get converted into a link to /docs/other-document.html (or the appropriately translated/versioned link) once it gets rendered.

      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.

      Linking to Images and Other Assets

      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 docs/assets and website/blog/assets, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.

      Example:

      -
      ![alt-text](/docs/assets/doc-image.png)
      +
      ![alt-text](/docs/assets/doc-image.png)
       

      Generating Table of Contents

      You can make an autogenerated list of links, which can be useful as a table of contents for API docs.

      In your markdown file, insert a line with the text <AUTOGENERATED_TABLE_OF_CONTENTS>. Write your documentation using h3 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 <AUTOGENERATED_TABLE_OF_CONTENTS>.

      Example:

      -
      ### `docusaurus.function(a, b)`
      +
      ### `docusaurus.function(a, b)`
       
       Text describing my function
       
      @@ -119,7 +119,7 @@ Text describing my function
       Text describing my function
       

      will lead to a table of contents of the functions:

      -
      - `docusaurus.function(a, b)`
      +
      - `docusaurus.function(a, b)`
       - `docdoc(file)`
       

      and each function will link to their corresponding sections in the page.

      @@ -133,13 +133,13 @@ ReactDOM.render( ```

      ...would be rendered with syntax highlighting like so:

      -
      ReactDOM.render(
      +
      ReactDOM.render(
         <h1>Hello, world!</h1>,
         document.getElementById('root')
       );
       

      Highlighting is provided by Highlight.js using the theme specified in your siteConfig.js file as part of the highlight key:

      -
      {
      +
      {
         ...
         highlight: {
           theme: 'default'
      @@ -150,7 +150,7 @@ ReactDOM.render(
       

      You can find the full list of supported themes in the Highlight.js styles directory.

      Registering additional languages

      While Highlight.js provides support for many popular languages out of the box, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the hljs constant as part of the highlight config key. This in turn allows you to call registerLanguage:

      -
      {
      +
      {
         ...
         highlight: {
           theme: 'default',
      diff --git a/docs/en/1.1.3/installation.html b/docs/en/1.1.3/installation.html
      index f52b4a5147..a77ac17a1a 100644
      --- a/docs/en/1.1.3/installation.html
      +++ b/docs/en/1.1.3/installation.html
      @@ -62,7 +62,7 @@
       

      After Docusaurus is installed, moving forward, you can check your current version of Docusaurus by going into the website directory and typing yarn outdated docusaurus or npm outdated docusaurus. You can update to the latest version of Docusaurus by typing yarn upgrade docusaurus --latest or npm update docusaurus.

      Verifying Installation

      Along with previously existing files and directories, your root directory will now contain a structure similar to:

      -
      root-of-repo
      +
      root-of-repo
       ├── docs-examples-from-docusaurus
       │   ├── doc1.md
       │   ├── doc2.md
      @@ -93,7 +93,7 @@
       

      Launching the server behind a proxy

      If you are behind a corporate proxy, you need to disable it for the development server requests. It can be done using the NO_PROXY environment variable.

      -
      SET NO_PROXY=localhost
      +
      SET NO_PROXY=localhost
       yarn start (or npm run start)
       
    Docusaurus
    Docs
    latest version of Docusaurus by typing yarn upgrade docusaurus --latest or npm update docusaurus.

    Verifying Installation

    Along with previously existing files and directories, your root directory will now contain a structure similar to:

    -
    root-of-repo
    +
    root-of-repo
     ├── docs-examples-from-docusaurus
     │   ├── doc1.md
     │   ├── doc2.md
    @@ -93,7 +93,7 @@
     

    Launching the server behind a proxy

    If you are behind a corporate proxy, you need to disable it for the development server requests. It can be done using the NO_PROXY environment variable.

    -
    SET NO_PROXY=localhost
    +
    SET NO_PROXY=localhost
     yarn start (or npm run start)