Docusaurus

入门

npx create-docusaurus@latest my-website classic

默认目录结构:

• blog/ %% 不要在这里用文件夹 %%
• docs/ %% 当前版本文档 %%
• src/
  • components/
  • css/
  • pages/: Pages do not have sidebars, only docs do.
• static/
• docusaurus.config.js | 主配置文件
• sidebars.js

配置

• https://docusaurus.io/docs/api/docusaurus-config
• https://docusaurus.io/docs/api/themes/configuration
• 📦 plugin-content-docs | Docusaurus
• 📦 plugin-content-blog | Docusaurus
• 📦 plugin-content-pages | Docusaurus

basic

const config = {
    url: 'https://xxx.github.io',
    baseUrl: '/',
    projectName: 'xxx.github.io',
    organizationName: 'xxx',
    deploymentBranch: 'gh-pages',
    trailingSlash: false,
}

presets

• docs
  • id %% 默认为 default %%
  • path
  • routeBasePath: 不建议改为/
  • sidebarPath
  • editUrl
  • breadcrumbs
  • showLastUpdateTime
  • showLastUpdateAuthor
  • versions
  • lastVersion
• blog
  • id
  • path
  • routeBasePath
  • editUrl
  • postsPerPage
  • blogSidebarTitle
  • blogSidebarCount
  • showLastUpdateTime
  • showLastUpdateAuthor
• theme
  • customCss

themeConfig

• docs.sidebar
  • hideable
  • autoCollapseCategories
• navbar %% type: default、dropdown、doc、docSidebar、docsVersionDropdown、docsVersion、localeDropdown、search、html %%
• footer
• prism
  • theme https://docusaurus.io/docs/api/themes/configuration#theme
  • darkTheme
  • additionalLanguages https://docusaurus.io/docs/markdown-features/code-blocks#supported-languages
  • defaultLanguage

sidebars

The sidebar supports various item types:

• Doc: link to a doc page, associating it with the sidebar
• Link: link to any internal or external page
• Category: creates a dropdown of sidebar items
• Autogenerated: generate a sidebar slice automatically
• HTML: renders pure HTML in the item's position
• Ref: link to a doc page, without making the item take part in navigation generation

const sidebars = {
    defaultSidebar: [{type: 'autogenerated', dirName: '.'}],
    xxxSidebar: [{type: 'autogenerated', dirName: 'xxx'}],
}

多个边栏, 改变 dirName 即可. 打开对应路径下的文档时会自动切换到对应的边栏.

multiple

• blog
• docs

const config = {
    plugins: [
      [
        '@docusaurus/plugin-content-blog',
        {
          id: 'blog2',
          path: './blog2',
          routeBasePath: 'blog2'
        }
      ]
    ],
}

versioning

i18n

Markdown

Frontmatter

Markdown Features | Docusaurus

常用字段

• sidebar_position | doc 特有
• slug
• title
• date
• draft
• unlisted

const config = {
    markdown: {
        parseFrontMatter: async (params) => {
            const result = await params.defaultParseFrontMatter(params);
            /** @type {{from: string, to: string, transform?: (v: any) => any}[]} */
            const mappings = [
                { from: "created", to: "date" },
                { from: 'updated', to: 'last_update', transform: v => ({date: v}) },
                { from: 'modified', to: 'last_update', transform: v => ({date: v}) },
                { from: 'private', to: 'unlisted' },
                { from: 'public', to: 'unlisted', transform: v => !v }
            ];
            
            mappings.forEach(({ from, to, transform }) => {
                if (from !== to && from in result.frontMatter) {
                    result.frontMatter[to] = transform
                        ? transform(result.frontMatter[from])
                        : result.frontMatter[from];
                    delete result.frontMatter[from];
                }
            });
            return result;
        },
    },
}

Math Equations

npm install --save remark-math@6 rehype-katex@7

具体配置见官网文档

Diagrams

npm install --save @docusaurus/theme-mermaid

具体配置见官网文档

MDX Plugins

• Remark: processes the Markdown AST.
• Rehype: processes the Hypertext AST.

部署

• github pages: GIT_USER=<GITHUB_USERNAME> npm run deploy %% 本质上是 git push %%
• cloudflare pages
• vercel

样式

Styling and Layout | Docusaurus

https://infima.dev/

:root {
  --doc-sidebar-width: 240px;
}

strong {
  color: var(--ifm-color-danger);
}
em {
  color: var(--ifm-color-warning);
}

:not(pre) > code {
  color: var(--ifm-color-info);
}

article [href^="http"] {
  /* 外部链接样式 */
  /* color: #e91e63; */
  text-decoration: underline;
  /* position: relative; */
  /* padding-right: 18px; */
}

/* article a[href^="http"]::after {
  content: "↗";
  position: absolute;
  font-size: 0.8em;
  margin-left: 3px;
} */

插件

Tips

首页

移除 HomepageFeatures 后让 .hero 占满剩余空间

.hero {
  flex: 1;
}

/* (可选) 移除背景色*/
.hero--primary {
  --ifm-hero-background-color: var(--ifm-background-color);
  --ifm-hero-text-color: var(--ifm-font-color-base);
}

集成 Obsidian

更改 persets 中 docs、blog 的 path 配置即可.

附件用相对路径.

例如:

• vault/
  • assets/
  • docs/
  • blog/

Resources

• docusaurus.community