使用docusaurus快速搭建静态博客站点

原创

walrus

发布于 2022-04-16 13:55:51

1.3K0

发布于 2022-04-16 13:55:51

文章被收录于专栏：用户7830300的专栏

title: 使用docusaurus快速搭建静态博客站点

description: 使用docusaurus快速搭建静态博客站点

slug: use-docusaurus-to-deploy-blog

tags: static-site generator, blog generator, docusaurus-v2

authors:

name: Walrus title: Creator of Walrus's Blog url: https://walrus.net.cn image_url: img/walrus.jpgundefined

Docusaurus是一种静态站点生成器。它构建了一个具有快速客户端导航的单页应用程序，充分利用React的强大功能使你的站点具有交互性。它提供了开箱即用的文档功能，但可以用来创建任何类型的网站(个人网站、产品、博客、营销登陆页面等)。

第一步：创建一个Docusaurus项目

在当前目录下创建一个名为website-demo的项目，website-demo可以改成任意值。

npx create-docusaurus@latest website-demo classic

上述命令执行完成后，website-demo/目录下会看到下面被生成的文件：

├── babel.config.js
├── blog
│   ├── 2019-05-28-first-blog-post.md
│   ├── 2019-05-29-long-blog-post.md
│   ├── 2021-08-01-mdx-blog-post.mdx
│   ├── 2021-08-26-welcome
│   │   ├── docusaurus-plushie-banner.jpeg
│   │   └── index.md
│   └── authors.yml
├── docs
│   ├── intro.md
│   ├── tutorial-basics
│   │   ├── _category_.json
│   │   ├── congratulations.md
│   │   ├── create-a-blog-post.md
│   │   ├── create-a-document.md
│   │   ├── create-a-page.md
│   │   ├── deploy-your-site.md
│   │   └── markdown-features.mdx
│   └── tutorial-extras
│       ├── _category_.json
│       ├── manage-docs-versions.md
│       └── translate-your-site.md
├── docusaurus.config.js
├── package.json
├── package-lock.json
├── README.md
├── sidebars.js
├── src
│   ├── components
│   │   └── HomepageFeatures
│   │       ├── index.js
│   │       └── styles.module.css
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── index.js
│       ├── index.module.css
│       └── markdown-page.md
└── static
    └── img
        ├── docusaurus.png
        ├── favicon.ico
        ├── logo.svg
        ├── tutorial
        │   ├── docsVersionDropdown.png
        │   └── localeDropdown.png
        ├── undraw_docusaurus_mountain.svg
        ├── undraw_docusaurus_react.svg
        └── undraw_docusaurus_tree.svg

现在，启动开发服务器，查看效果。执行下面的命令，会自动打开一个浏览器窗口，并且每次修改站点内容后，页面会实时渲染出来：

cd website-demo
yarn start

默认效果是这样的：

右上角有一个切换明暗模式的按钮，这里切换到了暗模式。

第二步：修改docusaurus.config.js

修改后的docusaurus.config.js文件内容如下：

// @ts-check
// Note: type annotations allow type checking and IDEs autocompletion

const lightCodeTheme = require('prism-react-renderer/themes/github');
const darkCodeTheme = require('prism-react-renderer/themes/dracula');

/** @type {import('@docusaurus/types').Config} */
const config = {
  title: 'website-demo',
  tagline: 'Although practicality beats purity.',
  url: 'https://walrus.net.cn',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico',
  organizationName: 'test', // Usually your GitHub org/user name.
  projectName: 'test', // Usually your repo name.

  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: false, // Optional: disable the docs plugin
        blog: {
          routeBasePath: '/', // Serve the blog at the site's root
          /* other blog options */
        },
      },
    ],
  ],

  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      navbar: {
        items: [
          {to: '/', label: 'Blog', position: 'left'},
        ],
      },
      prism: {
        theme: lightCodeTheme,
        darkTheme: darkCodeTheme,
      },
    }),
};

module.exports = config;

这个文件只是导出了一个config对象，定义了站点的一些属性，其中config.title指的是你的站点名称，config.url是你的站点发布后的地址，其他字段按需要修改。

这里只需要博客功能，所以还要把./src/pages/index.js文件删除。

这时再切换到上一步打开的浏览器窗口，可以看到默认显示的只是一个博客列表，如下图所示：

第三步：创建一篇博客文章

博客文件位于./blog目录，要添加博客，只需要在这个目录中写markdown文档，非常方便。

./blog目录中已经存在一些文件，它们是官方给出的模板，可以看看了解博客md的书写格式，后面如果不需要这些文件，可以把它们全部删除。

在./blog目录创建一个md文件，因为今天是2022年4月16日，所以将文件命名为2022-04-16-my-first-blog.md。

2022-04-16-my-first-blog.md文件内容如下：

---
title: My Fisrt Blog
description: this is my first blog
slug: hello-world
authors:
- name: Walrus
  title: Creator of Walrus's Blog
  url: https://walrus.net.cn
  image_url: img/walrus.jpg
---

这是博客概要

<!--truncate-->

这是博客内容

被---包起来的内容定义的是元信息，其中：title是博客标题，description是描述，slug是将要在浏览器地址栏中显示的和博客一一对应的url路径。authors是作者信息：name是作者名称, title相当于个性签名，url是作者主页，image_url是作者头像，支持外部链接，也支持本地相对路径，img/walrus.jpg指向的是./static/img/walrus.jpg文件。

用于显示概要，在该标签之前书写概要，之后书写具体内容。对应的，在博客列表中会有一个"Read More"按钮，点击这个按钮会从博客列表页进入博客详情页。

切换到浏览器，可以看到默认的列表页已经可以看到刚才新增的博客，如下图所示：

第四步：发布博客站点

本地启动的只是开发服务器，一般只建议在开发环境使用它。在发布站点之前，需要先打包，执行如下命令：

yarn build

打包完毕后，可以在./build目录中看到打包之后的静态文件，如下所示：

├── 404.html
├── archive
├── assets
├── atom.xml
├── first-blog-post
├── hello-world
├── img
├── index.html
├── long-blog-post
├── markdown-page
├── mdx-blog-post
├── rss.xml
├── sitemap.xml
├── tags
└── welcome

现在只需要把这些静态文件部署到web服务器即可，如nginx,apache2等，可以发布到github pages。

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

react