跳到主要内容

网站搭建过程

阅读需 8 分钟

在我自学的过程中发现，学了一些内容却不做笔记以及日常不应用的情况下，学过的内容很快就会遗忘，因此我开始做我自己的博客，用于记录我日常学习的笔记和一些疑难问题。这里我使用docusaurus来搭建我自己的博客。相关链接如下：

一、整体布局​

1.1. 导航栏navbar布局​

仅修改 docusaurus.config.mts 中 themeConfig 的 navbar 选项内容即可。配置可以查看官方文档。

1.2. 底部footer布局​

仅修改 docusaurus.config.mts 中 themeConfig的 footer 选项内容即可。只是要注意，每一个item都需要有 label 和 to 或 href 属性。详情可查看官方文档。

二、博客​

2.1. 生成博客​

只要在blog目录下新建.md或.mdx文件即可，这里我创建的文档是 .mdx 后缀的，因为这可以使用 .md 文件的语法，也可以在文档中加入React组件。但 docusaurus v3 依赖的 mdx v3.0 版本对于语法的约束更加严格了，可能会出现一些无法 resolve 的依赖问题，可以参考：

2.2. 博客列表​

博客的首页是博客列表页面，默认情况下，博客列表中的每一篇博客的全部内容都会显示出来。我们可以用{/* truncate */}来隐藏一些内容。在{/* truncate */}下的内容会在博客列表中隐藏，转为显示“阅读更多”。

---
title: MDX blog truncation Example
---

All these will be part of the blog post summary.

{/* truncate */}

But anything from here on down will not be.

我们还可以控制博客列表显示多少篇博客的内容，还有一些别的操作，可以参考：

2.3. 博客作者部分​

docusaurus中有内联作者和全局作者两种表示方法。

（1）内联作者

内联作者是根据 markdown 文档上的 front matter 来生成。

---
authors:
  - name: BearProfessor
    url: https://github.com/bear-doctor?tab=repositories
    image_url: https://upload.cc/i1/2023/07/14/ni9LyD.png
    email: bear_professor@outlook.com
---

如果想要得到图片的 URL 地址，就需要用到图床，我是将图片存储在腾讯云的对象存储中。

（2）全局作者

其实就是把上面的front matter放入一个专门的文件中，需要的时候在front matter中调用即可

authors.ymlyml
bear:
  name: 小熊博士
  title: 转码ing
  url: https://github.com/bear-doctor
  image_url: /img/logo.webp
doc.mdxyml
---
author: bear
---

2.4. 博客日期​

用date属性即可。这有多种格式，具体的格式可以查看官方文档

---
date: 2023-07-14T18:00
---

2.5. 博客侧边栏​

在 docusaurus.config.mts 中的 preset 选项中可以设置相应的博客侧边栏，可查看官方文档。然而，官方文档中也提及——我们可以使用博客插件来设置博客侧边栏，在我们网站的主题中也是这么设置的。

2.6. 博客插件​

我们的网站主题里面对博客插件进行了一定的配置，可以在官方博客插件文档中查看每一个键值对的具体含义和一些其他的配置选项。

docusaurus.config.mtsjs
const config: Config = {
  plugins: [
    // 把插件名称和配置对象放在一个二元组中，可以对这个插件进行配置。
    [
      './src/plugin/plugin-content-blog', // 为了实现全局 blog 数据，必须改写 plugin-content-blog 插件
      {
        path: 'blog', // 博客内容目录的文件系统路径，相对于站点目录
        // 直接编辑博客文件，完全忽略这个变量就会禁用编辑链接。
        // editUrl: ({ locale, blogDirPath, blogPath, permalink }) =>
        //   `https://github.com/kuizuo/blog/edit/main/${blogDirPath}/${blogPath}`,
        editLocalizedFiles: false,
        blogDescription: '学习即是生活',  // 用于增进 SEO 的博客页面元描述。
        blogSidebarCount: 12,
        blogSidebarTitle: 'Blogs',  // 博客侧边栏标题
        postsPerPage: 12,
        showReadingTime: true,
        readingTime: ({ content, frontMatter, defaultReadingTime }) =>
          defaultReadingTime({ content, options: { wordsPerMinute: 300 } }),
        // 博客订阅源
        // feedOptions: {
        //   type: 'all',
        //   title: '小熊博士',
        //   copyright: `Copyright © ${new Date().getFullYear()} 小熊博士 Built with Docusaurus.
        //   <p><a href="http://beian.miit.gov.cn/" class="footer_lin">${beian}</a></p>`,
        // },
      },
    ],
  ]
  ......
}

2.7. front matter​

博客也有前言属性，具体有什么项，每一项的值应该是什么类型可以查看官方文档

三、文档​

3.1 创建文档​

我们在docs文件夹下创建的 .md 和 .mdx 文档将会被渲染为文档页面。

3.2 文档属性​

3.2.1 front matter​

文件的前言是用于给doc页面提供额外的元数据。示例：

---
id: doc-markdown
title: Docs Markdown Features
hide_title: false
hide_table_of_contents: false
sidebar_label: Markdown
sidebar_position: 3
pagination_label: Markdown features
custom_edit_url: https://github.com/facebook/docusaurus/edit/main/docs/api-doc-markdown.md
description: How do I find you when I cannot solve this problem
keywords:
  - docs
  - docusaurus
image: https://i.imgur.com/mErPwqL.png
slug: /myDoc
last_update:
  date: 1/1/2000
  author: custom author name
---

若要了解front matter有什么属性，对应什么值，有什么作用，参考官方文档

3.2.2 文档结构​

这里的文档结构并不是说在本地文件夹中的文档结构，而是指网站中的文档结构。这里主要涉及到两个属性：id 和 slug

  1. 当手写侧边栏，或这使用与文档相关的布局或钩子时，ID 会被用来指代某篇文档。
  2. 使用 slug 前言可以更改文档的 URL。

从上面两个关于这两个前言的描述来看，可以更加明确地体会到，这是配置博客网站的文件结构。当然，查看官方文档可以发现：这两个前言属性的默认值是根据文件的本地结构来生成的。

3.3 侧边栏​

3.3.1 侧边栏的具体类型​

  1. Doc：链接到一个doc页面
  2. link：可以连接到任意一个页面，无论是内部页面还是外部页面
  3. category：创建一个侧边栏的下拉菜单
  4. autogenerated：自动产生侧边栏切片

还有一些其他类型的侧边栏项目，详细内容查看官方文档。而这些侧边栏项目代码可能有简写的格式。

3.3.2 指定侧边栏的顺序​

侧边栏采用的自动生成Autogenerated，默认是按照字母的顺序来排列的，我们可以用front matter来指定文档的顺序。

文档的侧边栏顺序yml
---
sidebar_position: 1
sidebar_label: 文档名称
title: 文档标题
---

我们也可以指定目录的顺序，只要在目录中添加一个 _category_.yml，在其中指定目录顺序即可。

_category_.ymlyml
{
  "position: 2.5"
}

3.3.3 自定义侧边栏​

若在网站中，希望出现不同的侧边栏，就需要我们自定义侧边栏项目。

🔔举个例子：在navbar中，有两项导航按钮，分别是“知识大门”和“算法”，它们链接的文档都是在docs文件夹中，但我们想要点击这两个内容会出现不同的侧边栏，这就需要在sidebar.js文件中自定义侧边栏（可以定义侧边栏包含什么内容）。

sidebar.jsjavascript
// 我们在下面定义了两个侧边栏项目
const sidebars = {
  // 这是知识大门导航栏所对应的侧边栏项目
  knowledge: [
    'intro', //这是指intro.mdx, doc类型的简写
    // .......
  ],
  // 这是算法导航栏对应的侧边栏项目
  algorithm: [
    'algorithm/intro',
    // ......
  ],
};

我们还需要将导航栏项目设置为侧边栏链接类型docsidebar，还有一些其他配置，查看官方文档

docusaurus.config.mtsjavascript
themeConfig:
    ({
      navbar: {
        items: [
          {
            type: 'docSidebar',
            sidebarId: 'knowledge', // 这个导航栏项目链接到的侧边栏项目的id
            position: 'right',
            label: '知识大门',
          },
          {
            type: 'docSidebar',
            sidebarId: 'algorithm',
            position: 'right',
            label: '算法',
          },
        ],
      },
    }),

3.3.4 侧边栏隐藏​

docusaurus.config.mtsjavascript
export default {
  themeConfig: {
    docs: {
      sidebar: {
        hideable: true,
      },
    },
  },
};

3.3.5 autogenerated​

  1. 使用 type:autogenerated 可以自动生成侧边栏，每一个文件夹会生成一个 category 类型的侧边栏，每一个文件会生成一个 doc 类型的侧边栏。
  2. autogenerated产生的侧边栏，无法在 sidebar.js 文件中进行自定义。对于文件而言，可以在 front matter 中进行侧边栏自定义，对于 category 而言，可以在目录中添加_category_.yml 文件，在这个文件中进行声明。
  3. 不是 autogenerated 类型的侧边栏，都是从 sidebar.js 中读取侧边栏信息；而对于 autogenerated 类型的侧边栏，则是从文件中读取信息——从文件中读取 front matter ，从文件夹中的_category_.yml 或是_category_.json 读取侧边栏配置信息。如何在文件中定义侧边栏配置信息可以查看官方文档。

3.3.6 侧边栏实例​

docusaurus官网给出了自己的侧边栏 sidebar.js 的文档，可以结合官方的网站实际表现来看。

3.4. 隐藏文件​

只要将文件命名为带有 _前缀的文件，就不会被Docusaurus显示出来

Loading Comments...
0%