Docusaurus 技术文档站点搭建指南

# Docusaurus 技术文档站点搭建指南 ## 快速初始化 ```bash npx create-docusaurus@latest my-docs classic --typescript cd my-docs npm start ``` ## 项目结构 ``` my-docs/ docs/ # 文档 Markdown 文件 intro.md tutorial/ getting-started.md advanced.md blog/ # 博客文章 src/ components/ # React 组件 css/ # 自定义样式 pages/ # 自定义页面 docusaurus.config.ts # 主配置 sidebars.ts # 侧边栏配置 ``` ## 配置文件 ```typescript // docusaurus.config.ts import type { Config } from '@docusaurus/types' const config: Config = { title: 'My Project', tagline: 'Documentation for developers', url: 'https://docs.example.com', baseUrl: '/', i18n: { defaultLocale: 'en', locales: ['en', 'zh-CN'] }, presets: [ ['classic', { docs: { sidebarPath: './sidebars.ts', editUrl: 'https://github.com/org/repo/edit/main/', showLastUpdateTime: true, showLastUpdateAuthor: true, versions: { current: { label: '3.0.0-beta', path: 'next' } } }, blog: { showReadingTime: true, blogSidebarCount: 'ALL' }, theme: { customCss: './src/css/custom.css' } }] ], themeConfig: { navbar: { title: 'My Project', items: [ { type: 'docVersionDropdown', position: 'left' }, { type: 'localeDropdown', position: 'right' }, { href: 'https://github.com/org/repo', label: 'GitHub', position: 'right' } ] }, algolia: { appId: 'YOUR_APP_ID', apiKey: 'YOUR_SEARCH_KEY', indexName: 'my-project' } } } export default config ``` ## Markdown 增强 ````markdown --- sidebar_position: 1 tags: [getting-started, tutorial] --- # Getting Started :::tip Pro Tip Use `npx` to always get the latest version. ::: :::danger Warning This action is irreversible! ::: import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; ```bash npm install my-package ``` ```bash yarn add my-package ``` ```` ## 版本化文档 ```bash # 创建版本快照 npm run docusaurus docs:version 2.0.0 # 会创建 versioned_docs/version-2.0.0/ 和 versioned_sidebars/ ``` Docusaurus 是 Meta 开源的文档框架，被 React、Jest、Redux 等知名项目采用，社区生态和插件非常丰富。