同步现在的代码

2026-08-14 15:28:57 +08:00
parent 5eab53a777
commit 8b6b8e7ab7
66 changed files with 7248 additions and 1248 deletions
@@ -0,0 +1,8 @@
+{
+  "label": "Docusaurus资料",
+  "position": 99,
+  "link": {
+    "type": "generated-index",
+    "description": "无说明"
+  }
+}
@@ -0,0 +1,250 @@
+---
+title: cms构建说明
+sidebar_position: 10
+---
+
+## cms
+
+### sveltia-cms
+
+```
+1.文件
+新增 static/admin/index.html  sveltia CMS入口页，CDN方式
+新增 static/admin/config.yml  sveltia全部配置
+
+2.访问
+http://localhost:3000/admin/
+```
+
+
+
+### decap-cms(仅本地)
+
+https://decapcms.org/docs/basic-steps/
+
+```
+1.文件
+新增 static/admin/index.html  Decap CMS入口页，CDN方式
+新增 static/admin/config.yml  Decap全部配置
+修改 package.json 增加"cms": "npx decap-server"
+
+2.内容
+docs的文件要增加 title
+
+3.启动
+npx decap-server  或 npm run cms
+
+4.访问
+http://localhost:3000/admin/
+```
+
+#### 已创建的文件
+
+| 文件                                                         | 说明                                   |
+| ------------------------------------------------------------ | -------------------------------------- |
+| [static/admin/index.html](vscode-webview://0ckeaenbrnfu1mc0gmsrksqv66drn38jfo32mrkm9h7l6l40fp43/static/admin/index.html) | Decap CMS 入口，从 CDN 加载            |
+| [static/admin/config.yml](vscode-webview://0ckeaenbrnfu1mc0gmsrksqv66drn38jfo32mrkm9h7l6l40fp43/static/admin/config.yml) | 核心配置：backend、集合、媒体文件路径  |
+| [server.js](vscode-webview://0ckeaenbrnfu1mc0gmsrksqv66drn38jfo32mrkm9h7l6l40fp43/server.js) | Gitee OAuth 认证代理服务（生产环境用） |
+| [.env.example](vscode-webview://0ckeaenbrnfu1mc0gmsrksqv66drn38jfo32mrkm9h7l6l40fp43/.env.example) | 环境变量模板                           |
+
+#### Git 仓库
+
+已本地提交并推送到 `git@gitee.com:lhth/testdecap.git`
+
+有一个新的更改（导航栏链接改到 Gitee）在本地但被拦截了，你需要手动推一下：
+
+```bash
+cd "d:/projects/test/my-websitetest"
+git push origin master
+```
+
+#### 架构说明
+
+**当前配置（开发/测试）：proxy backend**
+
+```
+浏览器 → Decap CMS → proxy:8081 → 本地 git repo → SSH → Gitee
+```
+
+运行方式：
+
+```bash
+# 终端 1：启动 Docusaurus
+npm start
+
+# 终端 2：启动 Decap 代理（在项目根目录）
+npx decap-server
+
+# 访问 http://localhost:3000/admin/ 即可使用 CMS
+```
+
+> **注意**：Docusaurus 开发服务器的 SPA 路由会拦截 `/admin/` 路径。有两个解决办法：
+>
+> 1. 访问 `http://localhost:3000/admin/index.html` （可能仍会被拦截）
+> 2. 用生产模式：`npm run build && npm run serve`，然后访问 `http://localhost:3000/admin/` ✅（已验证可行）
+
+#### 生产环境部署（Gitee OAuth）
+
+当你要部署到远程服务器时，需要：
+
+**1. 在 Gitee 创建 OAuth App**
+
+- 打开 https://gitee.com/oauth/applications
+- 应用名称：`My Decap CMS`
+- 回调地址：`https://你的域名.com/api/auth`
+- 获取 `Client ID` 和 `Client Secret`
+
+**2. 部署认证服务**
+
+```bash
+# 服务器上运行
+GITEE_CLIENT_ID=xxx GITEE_CLIENT_SECRET=xxx node server.js
+```
+
+或者部署到 Vercel/Cloudflare Workers 等 Serverless 平台。
+
+**3. 修改 config.yml** 取消注释文末的生产环境配置，注释掉 proxy backend 部分（文件中已有注释说明）。
+
+#### 内容集合
+
+已配置两个集合：
+
+- **博客文章** (`blog/`) — Docusaurus 标准 `YYYY-MM-DD-title.md` 格式
+- **文档** (`docs/`) — Docusaurus 文档格式
+
+你可以随时在 [static/admin/config.yml](vscode-webview://0ckeaenbrnfu1mc0gmsrksqv66drn38jfo32mrkm9h7l6l40fp43/static/admin/config.yml) 中增删字段或集合。
+
+```
+浏览器                     本地机器                  Gitee
+ ┌─────────┐            ┌──────────────┐         ┌──────────┐
+ │ Decap   │──proxy──→  │ decap-server │──git──→ │ gitee.com│
+ │ CMS UI  │  HTTP:8081 │ (本地Node进程) │  SSH   │ (你的仓库)│
+ │ admin/  │            │ 读写本地git   │         │          │
+ └────┬────┘            └──────────────┘         └──────────┘
+      │
+      └── unpkg.com CDN (加载 decap-cms.js)
+```
+
+
+
+### tina-cms(卡)
+
+https://tina.io/docs/reference/config
+
+```
+1.npm install tinacms @tinacms/cli
+2.tina/config.js
+3.package.json
+	// scripts 里加
+    "tina": "tinacms dev -c \"docusaurus start\"",
+4.npm run tina
+	自动生成tina/__generated__/
+            ├── _graphql.json
+            ├── _lookup.json
+            ├── _schema.json
+            ├── client.ts
+            ├── config.prebuild.jsx
+            ├── frags.gql
+            ├── queries.gql
+            ├── schema.gql
+            ├── static-media.json
+            ├── types.js
+            └── types.ts
+5.npm run tina
+```
+
+
+
+```
+# 官方提供标准版
+const branch =
+  process.env.NEXT_PUBLIC_TINA_BRANCH ||
+  process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_REF ||
+  process.env.HEAD ||
+  'main';
+
+export default defineConfig({
+  branch,
+  // generated by TinaCloud
+  token: '<Your Read Only Token>',
+  // generated by TinaCloud
+  clientId: '<Your Client ID>',
+  build: {
+    publicFolder: 'public',
+    outputFolder: 'admin',
+  },
+  schema: {
+    //Content model definition here...
+  },
+  ui: {
+    previewUrl: (context) => {
+      // Use Vercel preview deployments based on branch names
+      return { url: `https://my-app-git-${context.branch}.vercel.app` };
+    },
+  },
+  media: {
+    tina: {
+      publicFolder: 'public',
+      mediaRoot: 'uploads',
+    },
+  },
+  search: {
+    tina: {
+      indexerToken: process.env.TINA_SEARCH_TOKEN,
+    },
+  },
+});
+```
+
+
+
+```ts
+import { defineConfig } from "tinacms";
+
+export default defineConfig({
+  branch: process.env.TINA_BRANCH || "master",
+  clientId: process.env.TINA_CLIENT_ID || "",
+  token: process.env.TINA_TOKEN || "",
+  build: {
+    publicFolder: "static",
+    outputFolder: "admin",
+  },
+  media: {
+    tina: {
+      mediaRoot: "img",
+      publicFolder: "static",
+      static: true,
+    },
+  },
+  schema: {
+    collections: [
+      {
+        name: "blog",
+        label: "博客",
+        path: "blog",
+        format: "md",
+        fields: [
+          { type: "string", name: "title", label: "标题", isTitle: true, required: true },
+          { type: "datetime", name: "date", label: "发布日期", ui: { dateFormat: "YYYY-MM-DD", timeFormat: false } },
+          { type: "string", name: "tags", label: "标签", list: true, ui: { component: "tags" } },
+          { type: "string", name: "description", label: "描述/摘要" },
+          { type: "rich-text", name: "body", label: "正文", isBody: true },
+        ],
+      },
+      {
+        name: "docs",
+        label: "文档",
+        path: "docs",
+        format: "md",
+        fields: [
+          { type: "string", name: "title", label: "标题", isTitle: true, required: true },
+          { type: "number", name: "sidebar_position", label: "侧边栏位置" },
+          { type: "string", name: "tags", label: "标签", list: true, ui: { component: "tags" } },
+          { type: "rich-text", name: "body", label: "正文", isBody: true },
+        ],
+      },
+    ],
+  },
+});
+```
+
@@ -0,0 +1,234 @@
+---
+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
@@ -0,0 +1,31 @@
+---
+title: 插件
+sidebar_position: 3
+---
+
+## 官方社区提供
+
+https://docusaurus.io/zh-CN/community/resources
+
+### 搜索
+
+- `docusaurus-lunr-search`, `docusaurus-search-local`：它们是 `@easyops-cn` 的前身或同类，但没有明确的中文优化，不推荐。
+- `docusaurus-plugin-lunr`：这只是一个索引生成器，还需要自己集成 Lunr.js，太麻烦。
+- `typesense`, `meilisearch`, `markprompt`, `biel`：这些都是需要外部服务器的方案，对于“自己写笔记用”来说，架构太重了，不推荐。
+- `@orama/plugin-docusaurus`：Orama 也是一个优秀的本地搜索引擎，但 `@easyops-cn` 在 Docusaurus 生态中更成熟，文档和社区支持更好。
+
+### 集成
+
+- [docusaurus-plugin-dhub - 添加编辑链接，在](https://github.com/dhub-dev/docusaurus-plugin-dhub)[Dhub](https://dhub.dev/docusaurus)可视化 MDX 编辑器中打开页面的源文件，并生成一个`dhub.json`清单，将每个路由映射到其源文件。
+
+### 其他
+
+- [docusaurus-theme-github-codeblock](https://github.com/saucelabs/docusaurus-theme-github-codeblock)是一个 Docusaurus 插件，支持引用来自公共 GitHub 仓库的代码示例。
+
+- [docusaurus-plugin-remote-content](https://github.com/rdilweb/docusaurus-plugin-remote-content) - 一个 Docusaurus 插件，允许您从远程源获取内容。
+
+- [plugin-image-zoom](https://github.com/flexanalytics/plugin-image-zoom) - Docusaurus 的图像缩放插件
+- [docusaurus-theme-zoom-image](https://github.com/rmaacario/docusaurus-theme-zoom-image) - 一款零依赖主题，让所有 Markdown 图片都能缩放：悬停放大镜徽章 + 全屏灯箱
+
+- [docusaurus-plugin-native-ideal-image](https://github.com/Legend-Master/docusaurus-plugin-native-ideal-image) - 一个 Docusaurus 插件，用于将图像预处理为多种格式、尺寸和低质量图像占位符，通过现代浏览器原生和[延迟加载取代官方的](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img#loading)[@docusaurus/plugin-ideal-image](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-ideal-image)。
+
@@ -0,0 +1,18 @@
+---
+title: 搜索框
+sidebar_position: 2
+---
+
+
+## 搜索框
+### 搭建流程
+
+```
+1.
+npm install --save @easyops-cn/docusaurus-search-local
+
+2.修改文件后需要build才能查询到最新的
+npm run build
+npm run serve
+```
+