手把手搭建自己的文档系统 - 详细配置和部署步骤_怎么安装docusaurus-CSDN博客

Excerpt

文章浏览阅读1k次，点赞15次，收藏14次。手把手搭建自己的文档系统 - 详细配置和部署步骤_怎么安装docusaurus

背景介绍

近期正好有个项目需要搭建一个文档, 方便后续查询和使用, 这边调研了市面上一些常见的markdown文档系统如下:

名称	底层框架	适合常见
Docusaurus	NodeJS语言, 基于React构建，支持Markdown中嵌入React组件，适合构建大型文档网站	复杂的文档网站、博客、产品文档
MkDocs	Python语言轻量级、易于上手，视觉效果出色，基于Markdown语法，通过YAML配置文件控制	项目文档、内部手册、个人博客或知识库
GitBook	NodeJS语言强大的文档编写和发布工具，支持Markdown和AsciiDoc	电子书、技术文档、在线手册
Hexo	NodeJS语言高性能、快速生成静态网站的博客框架，支持Markdown	个人博客、技术文档、小型网站
Hugo	GO语言静态网站生成器，支持Markdown等多种标记语言	博客、文档网站、个人网站

综合看了上述不同的框架, 整体facebook的Docusaurus是一个比较好的选择, 首先采用NodeJS引擎, 以及React作为UI框架, 比较适合快速搭建文档.

环境搭建和自定义

下面介绍如何快速搭建一个Docusaurus文档系统:

1. 安装Docusaurus

首先，确保已经安装了Node.js（版本18或更高）和npm（或Yarn）。然后，通过以下命令安装Docusaurus脚手架工具：

npx create-docusaurus@latest my-website classic

上述命令将在当前目录下创建一个名为my-website的新项目，并配置好经典主题。

2. 启动开发服务器

进入项目目录并启动开发服务器：

cd my-website  

npm run start

默认情况下，浏览器将打开http://localhost:3000地址，预览网站。

3. 添加文档

在docs目录下添加Markdown文件，例如my-first-doc.md

---  

id: my-first-doc  

title: 我的第一篇文档  

---  

# 这是标题

## 这是内容

保存后，刷新页面即可看到新添加的文档。

4. 自定义网站

Docusaurus提供了丰富的自定义选项，可以通过修改配置文件和React组件来定制网站。

修改配置文件

docusaurus.config.js是Docusaurus的核心配置文件，可以在这里修改网站的标题、标签行、URL等。

const config = {  

title: 'My Docusaurus Site',  

tagline: 'A custom Docusaurus site',  

url: 'https://your-docusaurus-site.com',  

};

自定义导航栏和页脚

在docusaurus.config.js中，可以自定义导航栏和页脚的链接和图标。

navbar: {  

title: 'My Site',  

logo: {  

alt: 'My Logo',  

src: 'img/logo.png',  

  },  

items: [  

    {to: '/docs/', label: 'Docs', position: 'left'},  

    {to: '/blog', label: 'Blog', position: 'left'},  

  ],  

},  

footer: {  

style: 'dark',

links: [  

    {  

title: 'Docs',  

items: [  

        {label: 'Tutorial', to: '/docs/tutorial'},  

      ],  

    },  

  ],  

},

创建自定义页面

在src/pages目录下创建新的React组件文件（如custom-page.js），并在其中编写页面内容。

import React from 'react';  

import Layout from '@theme/Layout';  

function CustomPage() {  

return (  

<Layout title="Custom Page">  

<h1>This is a custom page</h1>  

<p>You can add any content here.</p>  

</Layout>  

  );  

}

export default CustomPage;

然后，在sidebars.js中添加指向新页面的链接，使其出现在侧边栏中。

5. 部署网站

最后，将网站部署到GitHub Pages或其他静态网站托管服务上。执行以下命令来构建并部署网站：

npm run build  

cd ..  

git init  

git remote add origin https:

git add .  

git commit -m "Initial commit"  

git push -u origin master

这样就可以通过github page访问网站了。

以上便是关于文档搭建的介绍, 欢迎点赞关注收藏~