Docusaurus

npx create-docusaurus@latest open-docs classic --typescript
cd open-docs
npm run start

// docusaurus.config.ts
import type {Config} from "@docusaurus/types";
import type * as Preset from "@docusaurus/preset-classic";

const config: Config = {
  title: "Open Docs",
  tagline: "清晰、可维护的项目文档",
  url: "https://docs.example.com",
  baseUrl: "/",
  favicon: "img/favicon.ico",
  organizationName: "open-docs",
  projectName: "website",

  presets: [
    [
      "classic",
      {
        docs: {
          sidebarPath: "./sidebars.ts",
          editUrl: "https://github.com/open-docs/website/edit/main/",
        },
        blog: true,
        theme: {
          customCss: "./src/css/custom.css",
        },
      } satisfies Preset.Options,
    ],
  ],

  themeConfig: {
    navbar: {
      title: "Open Docs",
      items: [
        {type: "docSidebar", sidebarId: "guide", label: "指南"},
        {to: "/blog", label: "博客"},
      ],
    },
  } satisfies Preset.ThemeConfig,
};

export default config;

// sidebars.ts
import type {SidebarsConfig} from "@docusaurus/plugin-content-docs";

const sidebars: SidebarsConfig = {
  guide: [
    "intro",
    {
      type: "category",
      label: "使用指南",
      items: [{type: "autogenerated", dirName: "guide"}],
    },
    "deployment",
  ],
};

export default sidebars;

---
id: intro
title: 项目简介
sidebar_position: 1
description: 从这里开始了解 Open Docs
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

# 欢迎使用 Open Docs

这里是项目的安装、配置和使用文档。

<Tabs>
  <TabItem value="npm" label="npm" default>
    `npm install open-docs`
  </TabItem>
  <TabItem value="pnpm" label="pnpm">
    `pnpm add open-docs`
  </TabItem>
</Tabs>

// src/components/FeatureCard.tsx
import type {ReactNode} from "react";
import styles from "./FeatureCard.module.css";

type Props = {
  title: string;
  children: ReactNode;
};

export function FeatureCard({title, children}: Props) {
  return (
    <section className={styles.card}>
      <h2>{title}</h2>
      <div>{children}</div>
    </section>
  );
}

// 在 MDX 中：
// import {FeatureCard} from "@site/src/components/FeatureCard";
// <FeatureCard title="静态生成">每条路径都会生成 HTML。</FeatureCard>

# 保存 1.0 文档快照
npm run docusaurus docs:version 1.0

# 生成简体中文翻译文件
npm run write-translations -- --locale zh-CN
npm run write-heading-ids -- --locale zh-CN

# 本地预览中文站点
npm run start -- --locale zh-CN

npm run typecheck
npm run build
npm run serve

# 静态构建结果位于 build 目录