linghutianhao
235 lines
8.5 KiB
Markdown
235 lines
8.5 KiB
Markdown
---
|
||
title: docusaurus构建说明
|
||
sidebar_position: 1
|
||
---
|
||
|
||
|
||
## Docusaurus 项目结构
|
||
### 搭建流程
|
||
|
||
```
|
||
1.初始化
|
||
npx create-docusaurus@latest my-website classic
|
||
|
||
2.启动
|
||
npm start
|
||
|
||
# 附
|
||
好看的网站 https://ai-speaker.com/
|
||
```
|
||
### 修改内容
|
||
```
|
||
# 配置
|
||
1.blog的预计阅读时间关,默认展示数量改成无限
|
||
2.i18默认zh-Hans
|
||
3.colorMode默认浅色,不使用用户偏好色
|
||
|
||
# 样式
|
||
1.表格样式
|
||
2.代码块字体样式,java代码识别
|
||
|
||
# 其他
|
||
1.editUrl 可以在本地打开typora
|
||
1.1先搞个注册表register-typora-protocol.reg 目标路径 typora-handler.wsf
|
||
1.2再wsf转换一下url编码,然后静默打开typora
|
||
2.新增了启动器start.vbs
|
||
```
|
||
|
||
### 增加一个docs页
|
||
|
||
```
|
||
# docusaurus.config.ts
|
||
plugins: [
|
||
[
|
||
'@docusaurus/plugin-content-docs',
|
||
{
|
||
path: 'docs2',
|
||
routeBasePath: 'docs2',
|
||
sidebarPath: './sidebars.ts',
|
||
editUrl: 'typora://file/D:/projects/my-website/',
|
||
},
|
||
],
|
||
],
|
||
|
||
|
||
themeConfig.navbar.items:
|
||
{
|
||
type: 'docSidebar',
|
||
sidebarId: 'tutorialSidebar2',
|
||
docsPluginId: 'docs2',
|
||
position: 'left',
|
||
label: '文档2',
|
||
},
|
||
|
||
# sidebars.ts
|
||
tutorialSidebar2: [{type: 'autogenerated', dirName: '.'}],
|
||
```
|
||
|
||
|
||
|
||
## 一端多git-ssh
|
||
|
||
```
|
||
#生成ssh秘钥
|
||
ssh-keygen -t ed25519 -C "haotiandev@outlook.com" -f ~/.ssh/id_ed25519_gitee
|
||
|
||
#私钥 C:\Users\haoti\.ssh\id_ed25519_gitee
|
||
|
||
#找到公钥 C:\Users\haoti\.ssh\id_ed25519_gitee.pub
|
||
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJ5usext5BEGqdXEkwIgdOWZodGCMZqlOpMs7pmYuO3V haotiandev@outlook.com
|
||
|
||
#把公钥在git后台配进ssh公钥里
|
||
|
||
#在C:\Users\haoti\.ssh 下创建config文件,写入
|
||
# 个人 Gitee 账号
|
||
Host gitee.com
|
||
HostName gitee.com
|
||
User git
|
||
IdentityFile ~/.ssh/id_ed25519_gitee
|
||
IdentitiesOnly yes
|
||
|
||
#绑定git地址
|
||
git remote add origin git@gitee.com:lhth/docusaurus.git
|
||
|
||
#测试
|
||
ssh -T git@gitee.com
|
||
```
|
||
|
||
|
||
|
||
## 完整项目地图
|
||
|
||
```
|
||
my-website/
|
||
│
|
||
├── 📄 docusaurus.config.js ← 【核心】整个站点的总配置
|
||
│ 标题、导航栏、页脚、主题、插件、国际化、深色模式……一切全局设置
|
||
├── 📄 sidebars.js ← 文档侧边栏菜单的结构定义
|
||
├── 📄 package.json ← 项目依赖 + npm 启动脚本
|
||
│
|
||
├── 📁 blog/ ← 博客系统
|
||
│ ├── authors.yml ← 作者信息（头像、简介、社交链接）
|
||
│ ├── tags.yml ← 博客标签定义
|
||
│ ├── 2021-08-26-welcome/ ← 博客可以是文件夹（含图片等资源）
|
||
│ ├── 2019-05-28-first-blog-post.mdx ← 单文件博客文章
|
||
│ ├── 2019-05-29-long-blog-post.mdx ← 文件名格式：YYYY-MM-DD-标题.mdx
|
||
│ └── 2021-08-01-mdx-blog-post.mdx ← 用 Markdown + JSX 写作
|
||
│ ↑ 自动生成：RSS 订阅、标签筛选页、文章归档页
|
||
│
|
||
├── 📁 docs/ ← 文档系统
|
||
│ ├── intro.mdx ← 文档的首页 / 入口
|
||
│ ├── tutorial-basics/ ← 一个文档章节（目录）
|
||
│ │ ├── _category_.json ← 章节配置：标签名、排序、是否折叠
|
||
│ │ ├── congratulations.mdx
|
||
│ │ ├── create-a-blog-post.mdx
|
||
│ │ ├── create-a-document.mdx
|
||
│ │ ├── create-a-page.mdx
|
||
│ │ ├── deploy-your-site.mdx
|
||
│ │ └── markdown-features.mdx
|
||
│ └── tutorial-extras/ ← 另一个章节
|
||
│ ├── _category_.json
|
||
│ ├── manage-docs-versions.mdx
|
||
│ ├── translate-your-site.mdx
|
||
│ └── img/ ← 文档里引用的图片
|
||
│ ↑ 支持多版本管理（v1, v2, next……）
|
||
│
|
||
├── 📁 src/ ← 自定义代码（React）
|
||
│ ├── pages/ ← 独立页面，文件会自动生成路由
|
||
│ │ ├── index.js ← 【首页！】网站的主入口页
|
||
│ │ ├── index.module.css ← 首页专属样式
|
||
│ │ └── markdown-page.mdx ← 纯 Markdown 写页面
|
||
│ ├── components/ ← 可复用的 React 组件
|
||
│ │ └── HomepageFeatures/ ← 首页的"特性展示"区块组件
|
||
│ └── css/
|
||
│ └── custom.css ← 全局自定义样式（覆盖主题默认样式）
|
||
│
|
||
├── 📁 static/ ← 静态资源（原封不动复制到最终网站根目录）
|
||
│ ├── img/
|
||
│ │ ├── favicon.ico ← 浏览器标签页小图标
|
||
│ │ ├── logo.svg ← 导航栏 Logo
|
||
│ │ ├── docusaurus-social-card.jpg ← 分享到社交媒体时的预览图
|
||
│ │ ├── docusaurus.png
|
||
│ │ └── undraw_docusaurus_*.svg ← 首页的插画素材
|
||
│ └── .nojekyll ← GitHub Pages 需要（告诉 GitHub 这不是 Jekyll 项目）
|
||
│
|
||
├── 📁 .docusaurus/ ← 【自动生成】Docusaurus 内部缓存和构建产物
|
||
│ │ ← 千万不要手动编辑！里面有个文件叫
|
||
│ │ DONT-EDIT-THIS-FOLDER 就在提醒这一点
|
||
│ │ ← 可以随时删掉（npm run clear），
|
||
│ │ 下次 npm start / build 会自动重建
|
||
│ │
|
||
│ ├── docusaurus.config.mjs ← 源配置编译后的版本
|
||
│ ├── routes.js / routesChunkNames.json ← 站点路由表（代码分割用）
|
||
│ ├── registry.js ← 所有页面和组件的模块注册表
|
||
│ ├── globalData.json ← 各插件暴露的全局运行时数据
|
||
│ ├── i18n.json ← 国际化翻译数据
|
||
│ ├── site-metadata.json ← 站点元信息
|
||
│ ├── site-storage.json ← 持久化存储
|
||
│ ├── client-modules.js ← 客户端模块入口
|
||
│ │
|
||
│ ├── docusaurus-plugin-content-docs/ ← 文档插件缓存
|
||
│ │ ├── default/
|
||
│ │ │ └── p/ ← 每个 .mdx 文档文件被编译成一个 JSON
|
||
│ │ │ ↑ 浏览器最终加载的就是这些 JSON
|
||
│ │ │
|
||
│ ├── docusaurus-plugin-content-blog/ ← 博客插件缓存
|
||
│ │ └── default/
|
||
│ │ ├── blogMetadata-default.json ← 博客元数据
|
||
│ │ ├── blog-post-list-prop-default.json
|
||
│ │ └── p/ ← 博客文章、标签页、归档页的编译产物
|
||
│ │
|
||
│ ├── docusaurus-plugin-content-pages/ ← 独立页面插件缓存
|
||
│ ├── docusaurus-plugin-css-cascade-layers/ ← CSS 层级管理
|
||
│ └── docusaurus-plugin-debug/ ← 调试页面
|
||
│
|
||
├── 📁 node_modules/ ← npm 安装的依赖包，不用关心里面
|
||
│
|
||
├── 📄 README.md ← GitHub 项目首页显示的说明
|
||
├── 📄 README_tome.md ← 就是你现在看的这份笔记
|
||
└── 📄 .gitignore ← Git 忽略规则
|
||
```
|
||
|
||
---
|
||
|
||
## 各目录一句话速查
|
||
|
||
| 目录 / 文件 | 一句话 |
|
||
|---|---|
|
||
| `docusaurus.config.js` | 站点的全部配置，修改标题、导航、主题都在这 |
|
||
| `sidebars.js` | 文档侧边栏菜单怎么排 |
|
||
| `blog/` | 写博客，Markdown → 自动生成文章页 + RSS + 标签 |
|
||
| `docs/` | 写文档，Markdown → 自动生成带侧边栏的文档站 |
|
||
| `src/pages/` | 自己写 React 页面（首页就在这） |
|
||
| `src/components/` | 自己写 React 组件 |
|
||
| `src/css/custom.css` | 覆盖主题样式（改颜色、字体等） |
|
||
| `static/` | 放图片、favicon 等不需要构建的文件 |
|
||
| `.docusaurus/` | 内部缓存，别动，出问题就删掉重来 |
|
||
| `node_modules/` | 第三方依赖 |
|
||
|
||
---
|
||
|
||
## 常用命令
|
||
|
||
| 命令 | 用途 |
|
||
|---|---|
|
||
| `npm start` | 启动开发服务器，自动打开浏览器，支持热更新 |
|
||
| `npm run build` | 生成生产环境静态文件到 `build/` 目录 |
|
||
| `npm run serve` | 本地预览构建后的产物 |
|
||
| `npm run clear` | 删除 `.docusaurus/` 缓存（出问题先试试这个） |
|
||
| `npm run deploy` | 部署到 GitHub Pages（需额外配置） |
|
||
|
||
---
|
||
|
||
## 数据流概览（简化版）
|
||
|
||
```
|
||
你写的 Markdown（docs/ + blog/）
|
||
↓ Docusaurus 编译
|
||
.docusaurus/ 里面的 JSON
|
||
↓ 浏览器加载
|
||
网站页面渲染
|
||
```
|
||
|
||
- MDX = Markdown + JSX（可以在 Markdown 里直接写 React 组件）
|
||
- 所有页面最终都是 React 组件，但大多数情况下你只需要写 Markdown
|