Moved my website from Dumi to Docusaurus at the beginning of the New Year.

Address: icodex. Me

Wood3n/ICodeX-Next: Blog (github.com)

background

Over the past year or so, I have been building my front-end knowledge body documentation with Dumi, upgrading versions of Dumi many times and watching Dumi grow from 200 + star to 2k + star.

In the past, I chose Dumi mainly because of dumi’s ability to interact with online documents, because sometimes I always want to use demo to realize a new knowledge point, especially CSS. The interaction capability provided by Dumi can exactly meet this demand of mine. It is also very convenient to write Markdown documents with Typora.

But I also noticed that docusaurus (a combination of document and saurus is really hard to remember) was a document generating tool that was abandoned a year ago when it was too young to offer comprehensive capabilities. But as more sites started using Docusaurus, SO did I.

Migration steps

Docusaurus provides scaffolding tools to generate site project code directly, which is created using scaffolding directly.

 npx create-docusaurus@latest my-website classic --typescript
Copy the code

The generated project directory is as follows:

My - website ├ ─ ─ blog │ ├ ─ ─ 2019-05-28 - hola. Md │ ├ ─ ─ 2019-05-29 - hello - world. Md │ └ ─ ─ 2020-05-30 - welcome. Md ├ ─ ─ docs │ ├ ─ ─ Doc1. Md │ ├ ─ ─ doc2. Md │ ├ ─ ─ doc3. Md │ └ ─ ─ MDX. Md ├ ─ ─ the SRC │ ├ ─ ─ CSS │ │ └ ─ ─ the custom. The CSS │ └ ─ ─ pages │ ├ ─ ─ Styles.module. CSS │ ├─ ├─ ├─ download.txt ├─ download.txt ├─ download.txt ├─ download.txt ├─ download.txt └─ Sidebars. Js └ ─ ─ yarn. The lockCopy the code

Plugins and preset capabilities

Docusaurus provides plugins and preset configurations, similar to the capabilities of tools like Babel, Webpack, and using the CLI to specify @docusaurus/preset-classic presets will contain all three crucial plugins at the same time:

  • @docusaurus/plugin-content-docs: Provides document writing capability, corresponding to generateddocsdirectory
  • @docusaurus/plugin-content-blog: provides blog rendering capabilities corresponding to generatedblogdirectory
  • @docusaurus/plugin-content-pages: provides normal front-end page rendering capabilities, corresponding to the generatedpagesdirectory

These three plug-in configuration are docusaurus. Config. Js under this file, for my personal needs of the three ability needs to be, so I can open, if you don’t need, directly in the presets. Docs | | blog pages can be set to false.

Modify home page pointing

In docusaurus.config.js, set routeBasePath to/and specify the path of the blog document. So the other routes in Docs or Pages are relative to blogs.

 // docusaurus.config.js
 ​
 module.exports = {
   presets: [
     "classic",
     {
       blog: {
         // Blog as the home page
         routeBasePath: "/".path: "./blog". },pages: {
         path: "src/pages".// Specify the routing path for Pages, since the blog is the home page
         routeBasePath: "/pages". }}}]Copy the code

Top navigation bar configuration

The top bar is nothing more than the Logo, navigation bar and so on, which corresponds to the NavBar of the theme configuration items provided by Docusaurus.

Configuration items type The default value describe
title string undefined At the top of the title
logo object undefined At the top of the logo
items NavbarItem[] [] Top menu navigation
hideOnScroll boolean false Whether the navigation bar is automatically hidden when the page scrolls down
style `’primary’ ‘dark’`

The navigation menu is configured through items, and Docusaurus provides 5 menu configuration types:

  • type="link": The default value is configurationtoorhrefSpecify the menu to click jump route;
  • type="dropdown": Drop-down menu navigation

  • type="docsVersionDropdown": Document version drop-down menu
  • type="localeDropdown": Document multilingual select drop-down menu
  • type="search": Search box, which needs to be configuredSearch engineIs only available

At the top, by default, is a toggle button for the site’s night and day themes.

I think the only drawback is that there is no support for custom ICONS of menu items, such as GitHub links, which need to be overwritten in SRC /custom.css:

 {
   href: "https://github.com/wood3n/icodex".position: "right".// custom logo in custom.css
   className: "header-github-link"."aria-label": "GitHub repository",}Copy the code
 /* GitHub Link */
 .header-github-link:hover {
   opacity: 0.6;
 }
 ​
 .header-github-link:before {
   content: "";
   width: 24px;
   height: 24px;
   display: flex;
   background: url("Data: image/SVG + XML, % 3 CSVG viewBox = '0 0 24 24 XMLNS =' http://www.w3.org/2000/svg '% 3 e % 3 cpath d =' M12. 297 c - 6.63-0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-776.417-1.305.76-1.605-2.665-3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 00 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0. 315.21.69.825.57C20.565 22.092 24 17.592 24 12.297 c0-6.627-5.373 - the 12-12-12 '/ % 3 e % 3 c/SVG % 3 e")
     no-repeat;
 }
 ​
 html[data-theme="dark"] .header-github-link:before {
   background: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath fill='white' d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-776.417-1.305.76-1.605-2.665-3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 00 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0. 315.21.69.825.57C20.565 22.092 24 17.592 24 12.297 c0-6.627-5.373 - the 12-12-12 '/ % 3 e % 3 c/SVG % 3 e")
     no-repeat;
 }
Copy the code

Document sidebar menu configuration

Docusaurus will render.md or.mdx files in the blog folder by default, any file in the SRC/Pages directory will be rendered as a page, while markdown files in the docs directory can be configured to generate different side menu bars via sidebarPath.

If scaffolding is used to create a documentation site, Ducusaurus generates a sidebars.js file by default, containing the following default configuration items:

 module.exports = {
   mySidebar: [{type: 'autogenerated'.dirName: '. '},]};Copy the code

By default, markdown files in the Docs directory are all displayed and not automatically categorized, but my requirement was to be able to sort by folders I created in the Docs directory and automatically generate routing addresses for each document. The ability to look at docusaurus provide – Sidebar | docusaurus, generated for the Sidebar type has the following kinds:

  • type="doc": cooperate withidSpecify the title and link of a single document
  • type="link": cooperate withhrefSpecify any jump link
  • type="category": cooperate withitemsSpecifies the documents included in the classification
  • type="autogenerated": cooperate withdirNameGenerate the sidebar automatically

It looked like type=”category” would work for me, but I had to configure the sidebar at the end of every post and that was too much work, so I tried type=”autogenerated”, Dirname can be configured as the name of the directory created under docs to automatically classify the documents under this directory. Combined with the docId on the top navigation bar, it points to the first article under each document category. After clicking it, the list of documents classified under different directories will be automatically opened.

 // sidebars.js
 const sidebars = {
   javascript: [{type: "autogenerated".dirName: "javascript"],},typescript: [{type: "autogenerated".dirName: "typescript"],},css: [{type: "autogenerated".dirName: "css",]}}Copy the code
 // docusaurus.config.js
 module.exports = {
   themeConfig: {
     navbar: {
       items: [{type: "dropdown".label: "Skill".position: "right".items: [{type: "doc".label: "JavaScript".docId: "Javascript/type/Type definition",}... ] }]}}}Copy the code

The images directory

Docusaurus provides a staticDirectories configuration item to specify a static resource directory. The default is a static folder. For static directories, all files will be copied to the site root directory after the build.

Any file directories that are not included with staticDirectories, including images referenced in Markdown, will be copied to assets at the root of the site after the build, and the path will be automatically converted. Taking advantage of this ability, I created a public/images directory in the website code root directory to save all the images contained in the Markdown page. With Typora’s ability to copy images and convert their relative paths, the images can be displayed normally wherever MarkDown is opened.

Site deployment

Site Deployment needless to say, still white piao making Pages, docusaurus also provides integrated making Actions automatically Deployment configuration reference – Deployment | docusaurus:

 name: Deploy to GitHub Pages
 ​
 on:
   push:
     branches: [main]
     paths: [website/**]
 ​
 jobs:
   deploy:
     name: Deploy to GitHub Pages
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v2
         with:
           node-version: 14.x
           cache: yarn
       - name: Build website
         run: |
           yarn install --frozen-lockfile
           yarn build
 ​
       # Popular action to deploy to GitHub Pages:
       # Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: The ${{ secrets.GITHUB_TOKEN }}
           # Build output to publish to the `gh-pages` branch:
           publish_dir: ./build
Copy the code

In this way, after using Typora to write a document or blog, directly push to GitHub repository, trigger GitHub Actions to complete automatic build packaging and deployment, in one go, mom no longer need to worry about my blog when the deployment of chaos.

Site Global Search

Docusaurus prioritizes the ability to support Algolia and is simple to use in three steps:

  1. First submit a PR in the Algolia repository to configure the site index;
  2. After the PR mergerDocSearchWebsite Submit the domain name and contact email address of the websiteappIdandapiKey;
  3. indocusaurus.config.jscompleteconfigurationCan be