docdude

English | 中文 | 日本語 | 한국어

一个轻量级的 Node.js 工具，将 Markdown 文件生成为单页文档网站。

功能特性

• ✨ Markdown 转 HTML - 支持 YAML 前置信息的 Markdown
• 🔗 标题锚点 - 自动生成层级锚点链接（如 #section.subsection）
• 💎 语法高亮 - 内置 highlight.js 代码块高亮
• 📱 响应式设计 - 移动设备友好，支持汉堡菜单切换
• 🎨 滚动高亮 - 侧边栏自动显示当前章节
• 📊 统计分析 - 可选 Segment Analytics 和 Google Analytics 注入
• 📝 笔记样式 - "Note:" 开头的段落自动转换为高亮的笔记块

使用

1. 创建文档

编写带有 YAML 前置信息的 Markdown 文件：

---
title: Getting Started
slug: getting-started
---

# 示例文档

2. 生成

npx docdude \
  --title "我的项目" \
  --subtitle "文档" \
  --in ./docs \
  --out ./build

然后在浏览器中打开 build/index.html。

Markdown 格式

前置信息（Frontmatter）

• title (必需) - 页面标题，显示在侧边栏和内容区
• slug (可选) - URL 链接名（省略时自动从 title 生成）
• skip (可选) - 设为 true 可排除该页面

特殊语法

笔记块：

Note: 这段文字会显示为高亮的笔记。

代码块：

function hello() {
  console.log('你好!');
}

编程 API

import { compile } from './src/compile.js';

await compile({
  src: './docs',
  dst: './build',
  title: '我的项目',
  subtitle: '文档',
  theme: 'apex',
  segment: '',
  google: ''
});

项目结构

docdude/
├── bin/static-docs.js    # CLI 入口
├── src/
│   ├── compile.js        # 核心编译逻辑
│   ├── markdown.js       # Markdown → HTML
│   ├── html.js           # HTML 后处理
│   ├── highlight.js      # 语法高亮
│   ├── inject.js         # 统计脚本注入
│   └── theme/apex/       # 默认主题
├── package.json
└── README.zh-CN.md

技术栈

• Markdown: marked
• 前置信息: gray-matter
• 模板引擎: handlebars
• DOM: cheerio
• 高亮: highlight.js
• 命令行: commander

许可证

MIT