# zihao_doc

**Repository Path**: homecommunity/zihao_doc

## Basic Information

- **Project Name**: zihao_doc
- **Description**: 梓豪文档生成工具根据抒写markdown转换为html页面，左侧为折叠菜单 右边为内容
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-20
- **Last Updated**: 2026-03-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 文档构建工具

基于 Markdown 的静态文档网站构建工具，支持离线资源自动下载。

文档构建工具 - 支持 create 创建文档项目，build 构建文档，支持离线资源自动下载，支持 run 启动开发服务器。

## 功能特性

- **Markdown 转 HTML**: 将 Markdown 文件转换为静态 HTML 页面
- **离线资源支持**: 自动下载并缓存 Tailwind CSS、Font Awesome、Google Fonts
- **响应式布局**: 移动端友好的侧边栏导航
- **可自定义模板**: 支持自定义 HTML、CSS、JS 模板
- **YAML 菜单配置**: 通过 YAML 文件配置导航菜单

## 效果展示
![效果展示](./doc/example.png)

## 安装

```bash
npm install -g zihaodoc
```

## 使用

### 创建新文档项目

```bash
zihaodoc create api_doc
```

这会创建以下结构：
- `api_doc/docs/` - Markdown 源文件目录
- `api_doc/dist/` - 生成的 HTML 输出目录
- `api_doc/base.html` - HTML 模板
- `api_doc/zihao_doc.css` - 样式文件
- `api_doc/zihao_doc.js` - JavaScript 文件
- `api_doc/menu.yaml` - 菜单配置
- `api_doc/assets/` - 离线资源

### 构建文档

```bash
zihaodoc build api_doc
```

将 `docs/` 目录下的 Markdown 文件转换为 HTML，并输出到 `dist/` 目录。

### 启动开发服务器

```bash
zihaodoc run api_doc
```

启动开发服务器并监听文件变动，自动增量构建。

指定端口：
```bash
zihaodoc run api_doc -p 8080
```

## 功能特性

- Markdown 转 HTML
- 自动下载离线资源（Tailwind CSS、Font Awesome、Google Fonts）
- 实时监听文件变动，自动增量构建
- 内置 HTTP 服务器
- 搜索功能
- 响应式设计
- 图片点击预览

## 离线资源

构建时会自动检查并下载以下离线资源到 dist 目录：
- Tailwind CSS
- Font Awesome
- Google Fonts (Inter)

首次构建时会下载，之后会使用本地缓存。

## 目录结构

```
api_doc/
├── docs/           # Markdown 源文件
│   ├── index.md
│   └── guide/
│       └── getting-started.md
├── dist/           # 生成的 HTML（可部署）
│   ├── index.html
│   ├── zihao_doc.css
│   ├── zihao_doc.js
│   ├── tailwindcss.js
│   ├── font-awesome/
│   └── fonts/
├── assets/         # 离线资源缓存
├── base.html       # HTML 模板（可自定义）
├── zihao_doc.css   # 样式文件（可自定义）
├── zihao_doc.js    # JS 文件（可自定义）
└── menu.yaml       # 菜单配置
```

## 菜单配置 (menu.yaml)

```yaml
site_name: 文档中心
nav:
  - title: 首页
    icon: fa-solid fa-house
    url: index.html
  - title: 快速入门
    icon: fa-solid fa-rocket
    children:
      - title: 产品架构介绍
        url: /guide/architecture.html
      - title: Docker 部署
        url: /guide/docker.html
```

## 模板变量

在 base.html 中可使用以下变量：
- `{{ title }}` - 页面标题
- `{{ site_name }}` - 站点名称
- `{{ breadcrumb }}` - 面包屑导航
- `{{ assets_path }}` - 静态资源路径
- `{{{ menu }}}` - 渲染后的菜单 HTML
- `{{{ content }}}` - 渲染后的 Markdown 内容

## License

MIT