docmk 1.0.0

package/my-docs/api/README.md

@@ -0,0 +1,152 @@
+---
+title: API 参考
+description: DocGen API 完整参考文档
+---
+
+# API 参考
+
+DocGen 提供了简洁而强大的 API，用于生成和管理文档站点。
+
+## 核心 API
+
+### scanSkillsDirectory()
+
+扫描指定目录，收集所有 Markdown 文件。
+
+```typescript
+async function scanSkillsDirectory(dirPath: string): Promise<SkillDirectory[]>
+```
+
+**参数：**
+- `dirPath` (string): 要扫描的目录路径
+
+**返回值：**
+- `Promise<SkillDirectory[]>`: 目录结构数组
+
+**示例：**
+
+```typescript
+import { scanSkillsDirectory } from 'docgen'
+
+const directories = await scanSkillsDirectory('./docs')
+console.log(`找到 ${directories.length} 个目录`)
+```
+
+### parseSkillsToConfig()
+
+将扫描的目录结构解析为配置对象。
+
+```typescript
+async function parseSkillsToConfig(
+  directories: SkillDirectory[],
+  siteConfig: SiteConfig
+): Promise<DocGenConfig>
+```
+
+**参数：**
+- `directories` (SkillDirectory[]): 目录结构数组
+- `siteConfig` (SiteConfig): 站点配置对象
+
+**返回值：**
+- `Promise<DocGenConfig>`: 完整的文档配置
+
+**示例：**
+
+```typescript
+const config = await parseSkillsToConfig(directories, {
+  title: '我的文档',
+  description: '项目文档站点',
+  baseUrl: '/',
+  skillsDir: './docs',
+  outputDir: './dist'
+})
+```
+
+## 类型定义
+
+### SkillFile
+
+表示单个 Markdown 文件。
+
+```typescript
+interface SkillFile {
+  path: string           // 文件绝对路径
+  name: string           // 文件名
+  title?: string         // 文档标题
+  description?: string   // 文档描述
+  content: string        // Markdown 内容
+  frontmatter: Record<string, any>  // 前置元数据
+  lastModified: number   // 最后修改时间戳
+}
+```
+
+### SiteConfig
+
+站点配置对象。
+
+```typescript
+interface SiteConfig {
+  title: string          // 站点标题
+  description: string    // 站点描述
+  baseUrl: string        // 基础 URL
+  skillsDir: string      // 源文件目录
+  outputDir: string      // 输出目录
+}
+```
+
+## CLI 命令
+
+### dev
+
+启动开发服务器。
+
+```bash
+docgen dev [options]
+```
+
+**选项：**
+- `--dir <path>`: 源文件目录（默认：`./docs`）
+- `--port <number>`: 端口号（默认：`3000`）
+
+### build
+
+构建静态站点。
+
+```bash
+docgen build [options]
+```
+
+**选项：**
+- `--dir <path>`: 源文件目录（默认：`./docs`）
+- `--output <path>`: 输出目录（默认：`./dist`）
+
+### preview
+
+预览构建后的站点。
+
+```bash
+docgen preview [options]
+```
+
+**选项：**
+- `--output <path>`: 站点目录（默认：`./dist`）
+- `--port <number>`: 端口号（默认：`4173`）
+
+## 错误处理
+
+所有异步函数都会抛出错误，建议使用 try-catch 处理：
+
+```typescript
+try {
+  const directories = await scanSkillsDirectory('./docs')
+} catch (error) {
+  console.error('扫描失败:', error)
+}
+```
+
+## 最佳实践
+
+1. **使用 TypeScript**：获得完整的类型提示
+2. **错误处理**：始终捕获异步操作的错误
+3. **路径规范**：使用绝对路径避免路径问题
+4. **配置验证**：构建前验证配置对象的完整性

package/my-docs/api/advanced.md

@@ -0,0 +1,260 @@
+---
+title: 高级用法
+description: DocGen 高级功能和自定义选项
+---
+
+# 高级用法
+
+深入了解 DocGen 的高级功能和自定义选项。
+
+## 自定义主题
+
+### CSS 变量
+
+DocGen 使用 CSS 变量系统，可以轻松自定义主题：
+
+```css
+:root {
+  --color-primary: #0a0a0a;
+  --color-background: #ffffff;
+  --font-sans: -apple-system, sans-serif;
+  --spacing-md: 1rem;
+  --radius-lg: 0.75rem;
+}
+```
+
+### 深色模式
+
+系统自动支持深色模式，基于用户系统偏好：
+
+```css
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-background: #0a0a0a;
+    --color-foreground: #fafafa;
+  }
+}
+```
+
+## 插件系统
+
+### Vite 插件集成
+
+DocGen 基于 Vite 构建，可以使用任何 Vite 插件：
+
+```typescript
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import markdown from 'vite-plugin-markdown'
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    markdown()
+  ]
+})
+```
+
+### Markdown-it 扩展
+
+自定义 Markdown 渲染器：
+
+```typescript
+import MarkdownIt from 'markdown-it'
+import anchor from 'markdown-it-anchor'
+import toc from 'markdown-it-toc-done-right'
+
+const md = new MarkdownIt({
+  html: true,
+  linkify: true,
+  typographer: true
+})
+  .use(anchor)
+  .use(toc)
+```
+
+## 性能优化
+
+### 代码分割
+
+使用动态导入优化加载性能：
+
+```typescript
+const Home = () => import('./pages/Home.vue')
+const SkillPage = () => import('./pages/SkillPage.vue')
+```
+
+### 图片优化
+
+建议使用 WebP 格式和响应式图片：
+
+```markdown
+![示例图片](./image.webp)
+```
+
+### 懒加载
+
+对大型文档启用懒加载：
+
+```typescript
+const observer = new IntersectionObserver((entries) => {
+  entries.forEach(entry => {
+    if (entry.isIntersecting) {
+      // 加载内容
+    }
+  })
+})
+```
+
+## 部署选项
+
+### Netlify
+
+```toml
+[build]
+  command = "docgen build --dir ./docs --output ./dist"
+  publish = "dist"
+
+[[redirects]]
+  from = "/*"
+  to = "/index.html"
+  status = 200
+```
+
+### Vercel
+
+```json
+{
+  "buildCommand": "docgen build --dir ./docs --output ./dist",
+  "outputDirectory": "dist",
+  "rewrites": [
+    { "source": "/(.*)", "destination": "/index.html" }
+  ]
+}
+```
+
+### GitHub Pages
+
+```yaml
+name: Deploy
+on:
+  push:
+    branches: [main]
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - run: npm install
+      - run: docgen build --dir ./docs --output ./dist
+      - uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./dist
+```
+
+## 搜索优化
+
+### 全文搜索
+
+实现基于 Fuse.js 的全文搜索：
+
+```typescript
+import Fuse from 'fuse.js'
+
+const fuse = new Fuse(files, {
+  keys: ['title', 'content', 'description'],
+  threshold: 0.3
+})
+
+const results = fuse.search(query)
+```
+
+### SEO 优化
+
+生成 sitemap 和 robots.txt：
+
+```typescript
+// sitemap.xml
+const urls = files.map(file => ({
+  loc: `${baseUrl}${getFileRoute(file)}`,
+  lastmod: new Date(file.lastModified).toISOString()
+}))
+```
+
+## 国际化
+
+### 多语言支持
+
+组织多语言文档：
+
+```
+docs/
+  en/
+    getting-started/
+      README.md
+  zh/
+    getting-started/
+      README.md
+```
+
+### 语言切换
+
+```typescript
+const locale = ref('zh')
+
+function switchLocale(newLocale: string) {
+  locale.value = newLocale
+  // 重新加载文档
+}
+```
+
+## 安全性
+
+### 内容安全策略
+
+配置 CSP 头：
+
+```html
+<meta http-equiv="Content-Security-Policy" 
+      content="default-src 'self'; script-src 'self' 'unsafe-inline'">
+```
+
+### XSS 防护
+
+Markdown 渲染时自动转义 HTML：
+
+```typescript
+const md = new MarkdownIt({
+  html: false  // 禁用原始 HTML
+})
+```
+
+## 监控和分析
+
+### Google Analytics
+
+```html
+<script async src="https://www.googletagmanager.com/gtag/js?id=GA_ID"></script>
+<script>
+  window.dataLayer = window.dataLayer || [];
+  function gtag(){dataLayer.push(arguments);}
+  gtag('js', new Date());
+  gtag('config', 'GA_ID');
+</script>
+```
+
+### 错误追踪
+
+集成 Sentry：
+
+```typescript
+import * as Sentry from '@sentry/vue'
+
+Sentry.init({
+  app,
+  dsn: 'YOUR_DSN',
+  integrations: [new Sentry.BrowserTracing()],
+  tracesSampleRate: 1.0
+})
+```

package/my-docs/getting-started/README.md

@@ -0,0 +1,24 @@
+---
+title: 快速开始
+description: DocGen 快速入门指南
+---
+
+# 快速开始
+
+欢迎使用 DocGen！这是一个用于生成文档网站的工具。
+
+## 安装
+
+```bash
+npm install -g docgen
+```
+
+## 基本使用
+
+创建你的文档目录结构，然后运行：
+
+```bash
+docgen dev --dir ./my-docs
+```
+
+就这么简单！

package/my-docs/tutorials/README.md

@@ -0,0 +1,272 @@
+---
+title: 教程指南
+description: 从零开始学习使用 DocGen
+---
+
+# 教程指南
+
+通过实际示例学习如何使用 DocGen 构建文档站点。
+
+## 第一步：创建项目
+
+### 1. 安装 DocGen
+
+首先安装 DocGen CLI 工具：
+
+```bash
+npm install -g docgen
+```
+
+验证安装：
+
+```bash
+docgen --version
+```
+
+### 2. 创建文档目录
+
+创建你的文档项目结构：
+
+```bash
+mkdir my-documentation
+cd my-documentation
+mkdir docs
+```
+
+### 3. 编写第一个文档
+
+创建 `docs/getting-started/README.md`：
+
+```markdown
+---
+title: 快速开始
+description: 开始使用我们的产品
+---
+
+# 快速开始
+
+欢迎使用我们的产品！
+
+## 安装
+
+\`\`\`bash
+npm install my-product
+\`\`\`
+
+## 基本用法
+
+\`\`\`javascript
+import { MyProduct } from 'my-product'
+
+const product = new MyProduct()
+product.start()
+\`\`\`
+```
+
+## 第二步：启动开发服务器
+
+### 实时预览
+
+启动开发服务器查看效果：
+
+```bash
+docgen dev --dir ./docs
+```
+
+访问 `http://localhost:3000` 查看你的文档站点。
+
+### 热更新
+
+修改任何 Markdown 文件，浏览器会自动刷新显示最新内容。
+
+### 调试技巧
+
+1. **检查控制台**：打开浏览器开发者工具查看错误
+2. **验证路径**：确保文件路径正确
+3. **清理缓存**：遇到问题时清理 `node_modules/.vite`
+
+## 第三步：组织文档结构
+
+### 推荐目录结构
+
+```
+docs/
+├── getting-started/
+│   ├── README.md
+│   ├── installation.md
+│   └── quick-start.md
+├── guides/
+│   ├── README.md
+│   ├── basic-usage.md
+│   └── advanced-features.md
+├── api/
+│   ├── README.md
+│   ├── core-api.md
+│   └── utilities.md
+└── faq/
+    └── README.md
+```
+
+### 文件命名规范
+
+- 使用小写字母和连字符
+- `README.md` 作为目录首页
+- 描述性文件名：`user-authentication.md`
+
+### Frontmatter 最佳实践
+
+每个文档都应包含 frontmatter：
+
+```yaml
+---
+title: 页面标题
+description: 页面描述（用于 SEO）
+author: 作者名称
+date: 2026-01-19
+tags: [tutorial, beginner]
+---
+```
+
+## 第四步：添加代码示例
+
+### 语法高亮
+
+使用语言标识符启用语法高亮：
+
+````markdown
+```javascript
+function hello() {
+  console.log('Hello, World!')
+}
+```
+
+```python
+def hello():
+    print("Hello, World!")
+```
+
+```bash
+echo "Hello, World!"
+```
+````
+
+### 代码注释
+
+添加注释说明关键代码：
+
+```javascript
+// 初始化应用
+const app = createApp()
+
+// 配置路由
+app.use(router)
+
+// 启动应用
+app.mount('#app')
+```
+
+### 可运行示例
+
+提供完整的可运行代码：
+
+```javascript
+// 完整示例：用户认证
+import { authenticate } from './auth'
+
+async function login(username, password) {
+  try {
+    const user = await authenticate(username, password)
+    console.log('登录成功:', user)
+    return user
+  } catch (error) {
+    console.error('登录失败:', error)
+    throw error
+  }
+}
+
+// 使用示例
+login('user@example.com', 'password123')
+```
+
+## 第五步：构建生产版本
+
+### 构建站点
+
+生成静态文件：
+
+```bash
+docgen build --dir ./docs --output ./dist
+```
+
+### 验证构建
+
+预览构建后的站点：
+
+```bash
+docgen preview --output ./dist
+```
+
+### 优化建议
+
+1. **压缩图片**：使用 WebP 格式
+2. **代码分割**：大型文档分成多个文件
+3. **缓存策略**：配置适当的缓存头
+
+## 第六步：部署上线
+
+### 部署到 Netlify
+
+1. 连接 Git 仓库
+2. 配置构建命令：`docgen build --dir ./docs --output ./dist`
+3. 设置发布目录：`dist`
+4. 点击部署
+
+### 部署到 Vercel
+
+```bash
+npm install -g vercel
+vercel --prod
+```
+
+### 自定义域名
+
+在部署平台配置自定义域名：
+
+1. 添加 CNAME 记录
+2. 配置 SSL 证书
+3. 等待 DNS 生效
+
+## 常见问题
+
+### 样式不显示？
+
+清理缓存并重新构建：
+
+```bash
+rm -rf node_modules/.vite
+docgen build --dir ./docs --output ./dist
+```
+
+### 路由 404 错误？
+
+确保服务器配置了 SPA 回退：
+
+```nginx
+location / {
+  try_files $uri $uri/ /index.html;
+}
+```
+
+### 搜索不工作？
+
+检查文件是否正确扫描：
+
+```bash
+docgen build --dir ./docs --output ./dist --verbose
+```
+
+## 下一步
+
+- 阅读 [API 参考](../api/README.md)
+- 查看 [配置选项](../configuration/README.md)
+- 浏览 [FAQ](../faq/README.md)