This is the sixth day of my participation in the August Text Challenge.More challenges in August

preface

I wrote this article when a friend came to me and said that the React community felt there was no document site tool or framework similar to VuePress. However, VuePress is not so easy to use, so I would like to recommend one for you. In keeping with the idea that “add me” is “me”, I typed it out with my backhand — Docusaurus — perfectly matching your requirements. At the time of writing this article, I had no idea what this word actually meant. How could I possibly recommend it to my friends?

Step 1: Baidu/Google

That’s pretty much what it was like. I went through a search and looked at several recommendations, but none of them seemed to be the framework I wanted (no, none of them seemed to be the framework my friends wanted).

Step 2: Go to the React homepage

Now that the community can not find the right, of course, probably because we didn’t search for key words, but I really don’t know how to describe, so old, and we go to a website to recommend looking, I also recommend actually here, if you encounter problems, can’t find the idea of tracing, the best guide is hidden in the official website of the document.

Went to the official recommendation, the results are as follows:

OK, AFTER seeing CRA, Next. Js and Gatsby, to be honest, I have used both Next. Js and Gatsby for static content sites, and they are both competent. He just wanted a document content site out of the box, and the two weren’t a good match, so keep looking.

Step 3: Go to the Facebook warehouse

There is no official Git website, so you have to go to the official Git repository to find it. Why? Generally speaking, a mature front-end framework has its own community extensions for more robust development, such as React CRA and Vue Cli. Who knows the framework itself better than their team? So the probability is that they will make one themselves, not to say more nonsense, to find out.

Enter the official warehouse, according to the keyword random search, greeted is this string of English characters — Docusaurus, although I haven’t clicked in, but I already know, this lovely little guy is the target I want to find today.

Here, I want to ridicule, this framework awareness is not high (or I informed the) most of the reasons, always feel is not enough ground in this name, Doc is easy to understand what is the document, but behind a bunch of really don’t know is what meaning, if you have know bosses, explain can leave a message to me ~

Finally, I helped my friend solve the problem perfectly, and this week the resolve partner issue task was completed. (ORIGINALLY, I hoped to write an article every day, but it takes a lot of time to write the article. Usually, I only have time to write it on weekends.)

Want to enter the group communication can find my contact information through the nuggets home page, into the group communication ~

The above search process leads to this article, since it is a framework recommended to partners, then I can not help but also have a look at the end of this Docusaurus, otherwise it will not be very embarrassing. To be honest, I use a lot of technology stacks in the React community. If I didn’t help my friends find a one-click framework for static site documents, I think I might build one with Next. Js or Gatsby. The main reason is that the process of building is a process of knowledge accumulation, but now it is more efficient to leave professional work to professional framework tools and just focus on what needs to be done. Before using Docusaurus, let’s take a look at some of the well-known document sites that use it to build websites.

  • Jest

  • React Native

  • Create-React-App

  • . There are a lot of big names in the React community

Docusaurus is used to build many of the most popular frameworks on Facebook and the React community. This means that the framework itself is proven, so let’s try it out for ourselves.

Hello Docusaurus – First acquaintance

The habit of learning about any new framework is to Get Started and start a Hello World application. So this article will follow my ideas, a look at the framework for building a document site is more convenient.

Initialize the project

NPX @docusaurus/init@latest init [name] [template] NPX @docusaurus/init@latest init docusaurus-luffyzh-website classicCopy the code

After initialization, start the project and let’s see what happens:

A quick look shows that the basic content site architecture is built automatically, including the home page and two built-in document pages, Tutorial and Blog. As for why there are two tabs, I will explain later, but also automatically support the conversion of the Dark mode, it is really a conscience.

For docs, it’s just writing MD files and rendering them to the page, there’s nothing to say, so the core of the docs framework is actually the config file, try to change the core configuration file docusaurus.config.js, and change the basic information of some websites.


module.exports = {
  title: 'Front End Student Zhou \'s Blog'.tagline: '📖 official account: Front-end Zhou Student '.url: 'https://github.com'.baseUrl: '/'.onBrokenLinks: 'throw'.onBrokenMarkdownLinks: 'warn'.favicon: 'img/favicon.ico'.organizationName: 'luffyZh'.// Usually your GitHub org/user name.
  projectName: 'docusaurus-luffyzh-website'.// Usually your repo name.
  themeConfig: {
    navbar: {
      title: 'Front End Student Zhou'.logo: {
        alt: 'My Site Logo'.src: 'img/logo.svg',},items: [{type: 'doc'.docId: 'intro'.position: 'left'.label: 'document'}, {position: 'left'.to: '/blog'.label: 'blog'}, {href: 'https://github.com/luffyZh/docusaurus-luffyzh-website'.label: 'GitHub'.position: 'right',}]},footer: {
      style: 'dark'.links: [{title: 'Docs'.items: [{label: 'document'.to: '/docs/intro',},],}, {title: 'Blog'.items: [{label: 'blog'.to: '/blog',},],}, {title: 'more'.items: [{label: 'the nuggets'.href: 'https://juejin.cn/user/96412752681079'
            },
            {
              label: 'GitHub'.href: 'https://github.com/luffzh/docusaurus-luffyzh-website',},],},],copyright: ` Copyright ©The ${new Date().getFullYear()}Front end zhou students ~ ',},prism: {
      theme: lightCodeTheme,
      darkTheme: darkCodeTheme,
    },
  },
};

Copy the code

As you can see, I changed a few simple configuration copy, content station has been very good, really is very simple, can not help but continue to explore ~

The directory structure

Take a look at the directory structure of the whole project, and understand the function of each directory and each file.

Docusaurus luffyzh - website ├ ─ ─ a blog// The Markdown file containing the blog. If you do not need a blog, you can delete this directory│ ├ ─ ─2019- 05- 28- hola. Md │ ├ ─ ─2019- 05- 29- hello - world. Md │ └ ─ ─2020- 05- 30- welcome. Md ├ ─ ─ the docs// The Markdown file containing the document. You can customize the sidebar order of documents in sidebars.js.│ │ ├ ─ ─ doc1. Md ├ ─ ─ doc2. Md │ ├ ─ ─ doc3. Md │ └ ─ ─ MDX. Md ├ ─ ─ the SRC// Non-document files such as pages or custom React components│ ├─ CSS │ ├─ custom.css │ ├─ pages// All files placed here will be converted to web pages, similar to next.js.│ ├─ └─ styles.module. CSS │ ├─ ├.js ├─ static// Static resources│ ├─ img ├─ docusaurus.config.js// Site configuration file├─ Package. json ├─ Readme.md ├─ sidebars// Used to specify the order of documents in the sidebar└ ─ ─ yarn. The lockCopy the code

Saw a lap down Docusaurus configuration and function is really very simple and aim is clear, just feel it is special for content to stand, the framework itself opened two slits for developers, is a document (one of the main purposes: document station, also mentioned above stood there are so many documents to use it.) The other is blogs. As mentioned above, there are differences between these two functions, so what are the differences?

  • /doc— Document folder

This folder is specifically used to generate the document site core. It identifies.md files and parses the following subdirectories to generate a sidebar of the directory tree structure, as shown below:

[Document rules] : The.md of the document can be used to write the content directly, just like the normal Markdown document. The only thing to note is that you can use a header to display the file in the sidebar sequence:

-- sidebar_position: 3 // This document is displayed in the third order --Copy the code
  • /blog— Blog folder

This folder is used to generate blog posts. It also recognizes.md files, but the difference is that it does not recognize directories. The generated sidebars are sorted by document name.

[Document rules] : The md file header of the blog needs to be matched and identified according to certain rules, as follows:

-- slug: first post -> /blog/first post title: first post LuffyZh // convert to the title of the article author_title: author_title: https://github.com/luffyZh / / into the authors link author_image_url: HTTP: / / https://avatars.githubusercontent.com/u/17840558?s=60&v=4 / / into the head tags:test] // Convert to category tags -- write the content directly outside the heading.Copy the code

contrast

It is very simple to use, to tell the truth, it feels good, and in fact, most developers if they do not care about the site class operation, see here can completely come out of a very well-formed document and blog. So since it is a static content site generation tool, so in the end it has what advantages? For example, most of the content sites, document requirements we see most of the Gitbook, VuePress and even language, flying books and so on. I’m sure you’re still wondering, why Docusaurus and not some other framework? There should always be a reason. As for the answer, we can still look at the official website and let it tell us that it is not a KPI framework itself, but can really help developers solve the pain points of document construction.

  • Gatsby – Good but steep

If you have ever used Gatsby, I believe you should know that Gatsby is driven by Graphql. If you simply make a document content site, then you are overqualified to use Gatsby. Of course, there is no denying the excellence of Gatsby.

  • Next-js – Excellent but unnecessary

Next. Js is the best hybrid framework in the React community. It can do a lot of things, such as SSR, PWA, SSG, and so on. You can do it by simply developing your own with next.js, but there is a certain cost and if you just want to focus on writing documentation and building documentation sites, there is no need to use the knife of next.js.

  • VuePress – Equally good

As mentioned before, VuePress is not used to it because it is the React stack. Therefore, Docusaurus is the document construction framework of VuePress for the React community.

  • Gitbook – Good but different idea

Gitbook was supposed to be the official documentation of choice for many open source tools, but it lost a lot of users as its own team slowly shifted its focus to commercial products. The most familiar is that Redux documents have gone from Gitbook to Docusaurus, and the idea behind Docusaurus is that it’s free for all users (of course, I don’t know if that will ever change, but with Facebook as a funding dad, Compared with money).

Here I would like to say that the official website of Docusaurus is worth us to learn from each framework, that is, when it introduces the comparison of other frameworks, it does not disparage any framework, but states the advantages and disadvantages of each framework in the content station, and honestly says that it borrowed some advantages of the other framework. Compared with many frameworks in order to promote their own belittling each other’s behavior is really better. For more detailed comparison, please refer to the official documents. I just summarize here. comparison-with-other-tools

Advance Docusaurus – Advance Docusaurus

Written into the order of time, in fact, I have felt this to a friend’s recommendation is yes, if you just want to do a content of pure document station, so basically ten minutes, can build a very decent content to stand and contains documentation and blog, only need according to the rules of the official document writing.

However, in the process of learning a new framework, I hope to use all its functions as much as possible. It may not be so in-depth, but just a little. In the future, if you have similar needs, you can directly use it, because it has already been in your knowledge base

The deployment of

A basic documentation blog content site has been completed, but only locally, so let’s see how it can be deployed to the public network to make it easier to view and share. I’ll briefly introduce two: Github Pages and Vercel.

  • Github Pages

Deploying Github Pages should have been fairly simple, but for some reason, authentication was a bit of a bumble, as I’ll explain here.

It’s official: To deploy your documents to Github, run the command GIT_USER=your_username && YARN deploy. However, after my practice, because some repositories have certain permissions, they cannot be successfully deployed, as shown in the following picture:

Therefore, additional methods are required for successful deployment.

Zhou’s own practice:

// build.sh
GIT_USER=your_github_username GIT_PASS=your_personal_token yarn deploy
Copy the code

As for the generation method of Personal token and possible problems, two websites are posted here to facilitate troubleshooting.

Generate your Personal token

If the deployment fails after the token is generated, it is likely that your repository is using SSH instead of HTTPS, and you need to switch. ssh -> https

After that, we’ll be all right.

Take a look at the final effect of our deployment success, done, directly look at the effect ~

Github Actions can also be used for automatic deployment of build, here because of the time, you can try their own, the official has detailed documentation, or quite clear ~

  • Vercel

Github Pages (Github Pages, Github Pages, Github Pages, Github Pages, Github Pages, Github Pages, Github Pages, Github Pages, Github Pages, Github Pages, Github Pages, Github Pages, Github Pages, Github Pages, Github Pages, Github Pages, Github Pages, Github Pages, Github Pages, Github Pages, Github Pages, Github Pages, Github Pages, Github Pages, Github Pages, Github Pages

First, go to Vercel and import our Github repository project.

Then, we don’t have to do anything, just hit Publish, because Vercel will help us identify the repository type, and anything it supports will be one-click deployment.

After deployment, the effect is shown in the figure below:

Oh dear, did I pay by mistake? Vercel, the man I trusted the most, is gone? Don’t worry, let’s take a closer look at Vercel’s power because we’ve already deployed Github Pages once, so our configuration files are actually configured according to Github Pages. For example, the baseUrl field is configured as /repo-name/ in our project because of the special nature of Github Pages. However, Vercel does not have the control of Github Pages. BaseUrl can be directly set to /. So let’s open a new branch, Feature/Vercel, change the configuration, redeploy, go back to Vercel, switch the deployment branch to Feature/Vercel, and see what happens:

I won’t say any more, it’s perfect, and that concludes the presentation of two very convenient ways to deploy a document site.

Rich functionality

Docusaurus has already done a lot of work for developers in the process of initializing the document content site, such as generating the home page, configuring the path, and adapting the dark mode. So beyond those features, are there other features we haven’t touched on? Of course there are and there are many, here, a few brief introduction, the rest of you can explore in the process of building their own projects ~

1 – Beautify your home page

Introduce blog stand in front of the building to the deployment process basically haven’t written a single line of code, very convenient, is also for this reason, lead to our blog actually stand for now a lot of things is a must, in accordance with the contract, such as the style of the home page is the same, so if we want to make home page looks more attractive or more individuation should be how to do? Finally, I’ll show you how to beautify your home page by writing code.

In fact, Docusaurus allows us to keep the ability to split. Just like Next. Js, files in the Pages folder are rendered as pages, so we can use React development mode to extend our pages. Below I have simply transformed the home page, and the final effect is as follows:

2 – Search for content

Docusaurus has a built-in search function, so let’s expose it to the user.

There are two ways to implement search: first, use the search capabilities provided by Algolia (recommended), and second, write your own. Again, we just want to build the site easily and avoid unnecessary development, so we use the first one directly.

yarn add @docusaurus/theme-search-algolia
Copy the code

Then go to the official website to apply for permission, because each website needs a corresponding apiKey and indexName, the official will send you an email to send you the two necessary contents. For simple use, I use the Demo Key given by the official to demonstrate.

After applying for permission, you need a certain amount of time to review, if you are in a hurry, you can use the following test.

algolia: {
  apiKey: '25626fae796133dc1e734c6bcaaeac3c'.indexName: 'docsearch',},Copy the code

After the configuration, the effect is shown in the figure below, you can see that it is very good.

Other features

Docusaurus also has many other features, such as:

  • Markdown features

  • Browser support

  • Internationalization and so on

As a series of exploration tutorials, more interested partners can go to their own needs to experiment, in a word, it is really worth using.

conclusion

Finally, the entire project address is here -> docusaurus-luffyzh-website, interested partners can go to see, used to build their own personal blog, or framework document site, it is really the only choice, very convenient and powerful ~

I am Zhou, if you think the article is good or you want to communicate privately, you can add my wechat/official/video account to chat about something interesting