slatedocs/slate

Slate Docker镜像文档

镜像概述

Slate是一款API文档生成工具，旨在帮助开发者创建美观、智能且响应式的API文档。其设计灵感来源于Stripe和***的API文档，采用左侧文档描述、右侧代码示例的布局，支持单页展示、自动滚动目录和多语言代码切换，所有内容通过Markdown编写，简单易用。

!https://raw.githubusercontent.com/slatedocs/img/main/screenshot-slate.png
示例文档效果可查看 https://slatedocs.github.io/slate

核心功能与特性

• 简洁直观的设计：左侧文档描述与右侧代码示例分离，响应式布局适配平板、手机及打印场景。
• 单页文档架构：完整文档集中于单页，滚动时自动更新浏览器哈希，支持精准链接定位。
• 基于Markdown编写：所有内容（包括代码示例）均通过Markdown编写，易于编辑和维护。
• 多语言代码示例：支持通过标签切换不同编程语言的代码示例，使用GitHub Flavored Markdown语法标识语言。
• 内置语法高亮：支持超过100种语言的语法高亮，无需额外配置。
• 自动滚动目录：左侧固定目录随内容滚动实时显示当前位置，即使包含180+条目仍保持高性能。
• 用户协作支持：默认支持GitHub Pages托管，开发者可通过Pull Request贡献文档修改。
• RTL语言支持：完整支持阿拉伯语、波斯语、希伯来语等从右到左语言的布局。

使用场景与适用范围

• API开发者需要为接口生成专业、易读的文档
• 团队协作编写和维护API文档
• 需要展示多语言代码示例的技术文档
• 希望通过Markdown简化文档编写流程的场景
• 需要响应式设计以适配多设备访问的文档需求

使用方法与配置说明

依赖要求

• Docker（推荐使用Docker Desktop，安装指南见Docker官方文档）

快速开始

1. Fork代码仓库
   在GitHub上Fork https://github.com/slatedocs/slate

2. 克隆仓库
   将你的Fork仓库克隆到本地：

   bash
   git clone https://github.com/YOURUSERNAME/slate.git
   cd slate
   

3. 获取Docker镜像
   可直接拉取预构建镜像或本地构建：

   bash
   # 拉取预构建镜像
   docker pull slatedocs/slate
   
   # 或本地构建镜像
   docker build . -t slatedocs/slate
   

构建文档

使用Docker构建静态文档：

bash
docker run --rm --name slate \
  -v $(pwd)/build:/srv/slate/build \
  -v $(pwd)/source:/srv/slate/source \
  slatedocs/slate

构建结果将输出到本地build目录。

运行开发服务器

启动开发服务器实时预览文档（访问 http://localhost:4567）：

bash
docker run --rm --name slate \
  -p 4567:4567 \
  -v $(pwd)/source:/srv/slate/source \
  slatedocs/slate serve

服务器将持续运行直至手动停止容器。

高级用法

可通过挂载特定文件自定义文档内容，而不覆盖默认JS、CSS等资源：

bash
docker run --rm --name slate \
  -v $(pwd)/source/index.html.md:/srv/slate/source/index.html.md \
  -v $(pwd)/source/includes:/srv/slate/source/includes \
  slatedocs/slate

后续步骤

1. 编辑source/index.md修改文档内容（详见Markdown语法）
2. 文档完成后，参考https://github.com/slatedocs/slate/wiki/Deploying-Slate%E5%8F%91%E5%B8%83%E6%96%87%E6%A1%A3

支持与反馈

• 问题咨询、功能实现或讨论：https://github.com/slatedocs/slate/discussions
• 发现Bug：https://github.com/slatedocs/slate/issues
• 贡献代码：提交Pull Request至dev分支