Docusaurus profile

Docusaurus is a static website creation tool developed by Facebook. Docusaurus 1 is a pure document site generator, while Docusaurus 2 retains the advantages of Docusaurus 1, which is easy to use, document versionization, and can be used to quickly create common content driven websites. Documents, blogs, product landing pages, marketing pages, etc.

While Docusaurus is primarily focused on helping developers build document sites properly, because it’s a React app, it can build any type of site.

In addition to Docusaurus, there are Gatsby, GitBook, Jekyll, VuePress, etc., among static website generation tools. Taro documents are built with Docusaurus 1. In addition to its focus on document generation, docSearch is used in search. The whole site is searchable and the search experience is very good. Taro 3 has upgraded to Docusaurus 2. If you choose Docusaurus and don’t need the multilingual version of the document for the time being, Docusaurus 2 is a good choice.

Install Docusaurus

Docusaurus has three templates: classic, Facebook only, and experimental bootstrap.

We created a site using a classic template named Guide, which can be installed using the NPX command as follows:

npx @docusaurus/init@latest init guide classic
Copy the code

It will give you the directory structure of a classic template and install dependencies. After the installation, the directory structure is as follows:

➜ Guide. ├── Heavy Metal Exercises - - Heavy Metal Exercises - - Heavy Metal Exercises - - Heavy metal Exercises - - Heavy metal Exercises - - Heavy metal Exercises │ └ ─ ─ 2019-05-30 - welcome. Md ├ ─ ─ docs / / document directory │ ├ ─ ─ doc1. Md │ ├ ─ ─ doc1. Md │ ├ ─ ─ doc3. Md │ └ ─ ─ MDX. Md / / support MDX oh ├ ─ ─ .js // Config file Directory ├─ node_modules ├─ package.json ├─ sidebars.js // Document sidebar Config file ├─ SRC // page or custom React ├─ └─ CSS │ ├─ pages ├─ ├─ ├─ damn.lockCopy the code

If you want to make changes to the theme of the document, put the theme folder in SRC and it will use the files in the theme folder first.

After the installation is complete, you can run yarn Start to obtain a site that can be previewed. If the browser does not automatically open, you need to manually open the site. Enter the address prompted by the command line (http://localhost:3000/ is normal)

? Something is already running on port 3000. Probably:
  ...
Would you like to run the app on another port instead? Yes
Docusaurus website is running at: http://localhost:3001/
Copy the code

At this point you can access the address as prompted. After starting up, preview the following picture:

configuration

Basic configuration

Docusaurus.config. js can be used to configure the site information, now to configure the site information, because we start yarn Star preview, so the changes in this configuration file can be seen in real time.

module.exports = {
  title: 'Taro document'.// Site name
  tagline: 'Open cross-end cross-framework solution, supporting the use of React/Vue/Nerv frameworks to develop wechat/JINGdong/Baidu/Alipay/Bytedance/QQ mini program /H5 and other applications. '.// slogan
  url: 'https://docs.taro.zone'.// Address of the site
  baseUrl: '/'.// Prepath
  onBrokenLinks: 'throw'.// How to handle dead chain when compiling
  favicon: 'img/favicon.ico'.// The site icon
  organizationName: 'nervjs'.// The organization name or user name on GitHub
  projectName: 'docusaurus'.// The repository name on GitHub
  themeConfig: {
    navbar: {
      title: 'Taro'.// Navigate to the site name
      logo: {
        alt: 'Taro logo'.// Site logo text replacement
        src: 'img/logo.svg'.// Site logo link
      },
      items: [{to: 'docs/'.// click on the back jump link to use href
          activeBasePath: 'docs'.// Use it to display the current highlight
          label: 'document'.// Display the name
          position: 'left'.// Is displayed on the left or right side of the navigation
        },
        {to: 'blog'.label: 'blog'.position: 'left'},
        {
          href: 'https://github.com/facebook/docusaurus'.label: 'GitHub'.position: 'right',}]},footer: {
        // Here is a self-modification}}},presets: [].// Due to the length of this article, it is skipped here
};
Copy the code

As you can see from the configuration file, setting up a site requires only a few configurations. If you want to enable more functions, you need to add a few configuration items.

Fold up the top navigation when scrolling down the document page

navbar: {
    hideOnScroll: true. }Copy the code

Make the sidebar collapsable and unfoldable (after 2.0.0-alpha.67)

 themeConfig: {
    hideableSidebar: true. }Copy the code

Enable multiple document versions

Enable multiple document versions. If you want to create a new document version such as 1.1.0, just

NPM run Docusaurus docs: Version 1.1.0Copy the code

Generate versioned_docs/version-1.1.0/ save 1.1.0 document files in the directory, and generate versioned_sidebars/ version-1.0-sidebars. Json save 1.1.0 document sidebar.

You can add a drop – down menu to switch between versions in the top navigation bar

navbar: {
    ... / / to omit
    items: [{type: 'docsVersionDropdown'.position: 'left'.dropdownActiveClassDisabled: true},.../ / to omit].../ / to omit
}
Copy the code

The effect after addition

Click 1.1.0, will be cut to the corresponding version, and path for http://localhost:3000/docs/, the Next is for http://localhost:3000/docs/next/, because the current version is 1.1.0, The Next version will be Next.

If you are planning multiple versions of your document, consider the following:

  • If there are hundreds of documents like Taro’s, a small version of the upgrade will generate a lot of files
  • For items with a large number of visitors, deleting the old version would result in a 404
  • If you want to change a version of a document, you have to change itversioned_docsFiles in the corresponding version directory

Multiple sites

A document may have two sites, a GitHub Page site and a domain name site. To set up a different URL for SEO, we need two steps to achieve this requirement.

1. Add a new command to the script in package.json and add compile parameters

"build": "docusaurus build"."build:zone": "NODE_OPTIONS=--max-old-space-size=5120 BASE=zone docusaurus build".Copy the code

2, in docusaurus.config.js to determine the environment variables, we need to fill in the address

url: process.env.BASE === 'zone' ? 'https://docs.taro.zone' : 'https://nervjs.github.io', // site addressCopy the code

Written document

Docusaurus supports Markdown and MDX formats. Docusaurus supports Markdown and MDX formats.

Id is optional, it is the unique identifier of the document, default id if missing, if the document path is doc.md its ID is doc, if it is apis/doc1.md then its ID is apis/doc1.

---
id: doc
Title: Best practices --
Copy the code

Set up the sidebar

Sidebars. js can be set in the root directory, which is relatively simple in general. For example, under docs, there are “About Taro”, “Quick Start”, “Basic Tutorial”, “Advanced Guide”, and under the advanced guide there are directories, you need to mark type as category. In items for example:

module.exports = {
  docs{About Taro: ['README'.'team'.'CONTRIBUTING'], quick start: ['GETTING-STARTED'.'composition'[React, vue, vue3]'hooks'.'hybrid',
        {
            label: 'Reverse conversion'.type: 'category'.items: [
                'taroize'.'convert-to-react'.'taroize-troubleshooting'}]}}Copy the code

Add document search

Docusaurus supports search using Algolia DocSearch. New features are being added in version 2 to support other searches. For now, Algolia is the only option.

After entering THE DocSearch website, “JOIN THE PROGRAM” in THE middle of THE page to enter THE application page, enter THE relevant information of your website, check THE button below, and submit. Be sure to check your site here according to its checklist of guidelines so that you can quickly apply for approval.

The last

If you use Docusaurus, don’t forget to provide them with a showcase, there is no reward for such a great documentation tool except voting. Your case will be presented in a showcase on the official website.