ByteNote

本文介绍 idoc，一个基于 Node.js 的轻量级文档生成工具。它可以将 Markdown 文件快速转换为静态页面，适合构建项目文档、教程网站和产品官网。该工具由 jaywcjlove 开发维护，在 GitHub 上已获得 305+ stars。

项目简介

idoc 是一个简单易用的静态文档生成器，专注于将 Markdown 文件转换为美观的静态网页。它采用 TypeScript 和 JavaScript 开发，遵循 MIT 开源协议。作者使用 idoc 成功构建了 30+ 个 macOS 应用官网和多个技术教程网站，包括知名的 Awesome Mac 项目。

核心特性

一键初始化：通过 npx idoc init 快速创建项目结构
Markdown 原生支持：自动将文件夹中的 Markdown 文件转换为静态页面
主题定制：支持自定义主题，内置默认主题
实时监听：--watch 模式支持开发时自动重新编译
HTML 压缩：内置 --minify 选项优化输出文件体积
CI/CD 友好：提供 GitHub Actions 集成示例，方便自动化部署

技术栈

TypeScript (49.0%) - 主要开发语言
JavaScript (32.5%) - 辅助功能实现
CSS (10.3%) - 样式和主题
EJS (8.2%) - 模板引擎

安装指南

前置要求

Node.js >= 14
npm 或 pnpm

安装方式

方式一：使用 npx（推荐，无需全局安装）

bash

npx idoc init myapp

方式二：全局安装

bash

npm install idoc -g
idoc init myapp

快速开始

1. 初始化项目

bash

npx idoc init my-docs

生成的目录结构：

text

my-docs/
├── docs/
│   ├── README.md      # 首页内容
│   └── about.md       # 关于页面
├── package.json
└── idoc.yml           # 配置文件

2. 启动开发服务器

bash

cd my-docs
idoc --watch --output="www"

3. 构建生产版本

bash

idoc --minify --output="dist"

使用示例

创建新文档

bash

# 创建单篇文档
idoc new introduce/README.md

# 创建文档并添加标题
idoc new introduce/README.md "Hello World" -f

使用自定义主题

bash

idoc --theme="default"

bash

# 指定 Markdown 源目录
idoc --dir="docs"

# 指定输出目录
idoc --output="dist"

完整构建命令

bash

# 强制重新生成并压缩 HTML
idoc --force --minify --output="www"

配置文件

idoc 使用 idoc.yml 作为配置文件，示例如下：

yaml

site: "我的文档站点 {{version}}"
menus:
  Home: index.html
  About: about.html

GitHub Actions 集成

在 CI/CD 流程中使用 idoc：

yaml

name: Deploy Docs

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Create idoc config
        run: |
          cat > idoc.yml << EOF
          site: "项目文档 {{version}}"
          menus:
            Home: index.html
          EOF

      - name: Install idoc
        run: npm install idoc -g

      - name: Build docs
        run: idoc --output="www"

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./www

命令行选项

选项	说明
`-v, --version`	显示版本号
`-h, --help`	显示帮助信息
`-f, --force`	强制重新生成文件
`-s, --site`	设置网站名称
`-d, --dir <dir-path>`	Markdown 文件目录，默认 docs
`-o, --output <dir-path>`	输出目录，默认 dist
`-w, --watch`	监听并编译 Markdown文件
`-t, --theme`	自定义主题设置，默认 default
`-m, --minify`	压缩 HTML

知名使用案例

作者使用 idoc 构建的知名项目：

Awesome Mac - macOS 应用精选列表
MySQL Tutorial - MySQL 教程
Docker Tutorial - Docker 教程
Nginx Tutorial - Nginx 教程
Swift Tutorial - Swift 教程
GitHub Actions Tutorial - GitHub Actions 使用教程
30+ 个 macOS 应用官网

项目链接

GitHub 仓库：https://github.com/jaywcjlove/idoc
npm 包：https://www.npmjs.com/package/idoc
作者主页：https://github.com/jaywcjlove

总结

idoc 是一个轻量级、易用的静态文档生成工具，特别适合需要快速搭建文档站点或产品官网的开发者。它的一键初始化、实时监听和 CI/CD 友好特性，使得文档维护和部署变得简单高效。如果你正在寻找一个简单可靠的 Markdown 转静态网站工具，idoc 值得一试。

字节笔记本

idoc - 轻量级 Markdown 文档生成工具

项目简介

核心特性

技术栈

安装指南

前置要求

安装方式

快速开始

1. 初始化项目

2. 启动开发服务器

3. 构建生产版本

使用示例

创建新文档

使用自定义主题

指定源目录和输出目录

完整构建命令

配置文件

GitHub Actions 集成

命令行选项

知名使用案例

项目链接

总结