theSlate

theSlate 是一款基于 Ruby 的文档生成工具，它可以帮助程序员快速创建美观、易读、易维护的文档。 theSlate 主张“代码即文档、文档即代码”，通过注释代码自动生成文档，提高开发效率的同时提升文档质量。

特点

• 支持 Markdown 格式的源文档，方便编写和维护。
• 提供丰富的自定义配置选项，可以定制主题、样式、布局等。
• 自动生成 API 文档和页面文档，支持浏览器实时预览和搜索。
• 集成了多种插件和工具，方便扩展和集成。

安装和使用

1. 安装 Ruby 和 Bundler。

   $ sudo apt-get install ruby ruby-dev
   $ gem install bundler
   

2. 下载 theSlate 并安装依赖。

   $ git clone https://github.com/slatedocs/the-slate.git my-docs
   $ cd my-docs
   $ bundle install
   

3. 编辑 source/index.html.md，撰写文档。

4. 生成文档。执行以下命令，将生成的文档保存在 build 目录中。

   $ bundle exec middleman build
   

5. 预览文档。执行以下命令，启动 Web 服务器，访问 http://localhost:4567 可以查看生成的文档。

   $ bundle exec middleman server
   

入门示例

# My API Documentation

This is the documentation for my awesome API. Enjoy!

## Authentication [/auth]

### Login [POST]

+ Request (application/json)

        {
            "username": "foo",
            "password": "bar"
        }

+ Response 200 (application/json)

        {
            "token": "eyJhbGciOiJIUzI1NiJ9.eyJzd...zZUQifQ.6yiheGG_6DvJUK0YO..."
        }

### Logout [DELETE]

+ Request (application/json)

    + Headers

            Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzd...zZUQifQ.6yiheGG_6DvJUK0YO...

+ Response 204

    [No Content]

自定义配置

可以编辑 config.rb 文件，修改参数来定制主题、样式、布局等。

# Set title of the site. Shown in the header.
set :title, 'My Docs Site'

# Set a link to be included in the header, shown in the top right corner of every page.
set :header_link, 'https://example.com/'

# Set a link to be included in the footer, shown in the bottom right corner of every page.
set :footer_link, 'https://example.com/'

# Set the main color for the site. Used in headings, links, buttons, etc.
set :color, '#3498db'

# Set the font for the site. The default is 'Open Sans'.
set :font, 'Roboto'

# Define a custom layout.
page '/*.json', layout: false
page '/*.txt', layout: false
page '/*.xml', layout: false

插件和扩展

theSlate 集成了多种插件和工具，可以进一步扩展和定制化。

• theSlate:API：为 API 文档提供更好的支持。
• theSlate:Apiary：将 Apiary API Blueprint 转换为 theSlate 文档。
• theSlate:Frontmatter：使用 Frontmatter 提供更多自定义选项。
• theSlate:SEO：提供 SEO 优化支持。
• theSlate:Sidebar TOC：生成侧边栏目录。

结语

theSlate 是一款非常好用、强大的文档生成工具，它可以使文档编写和维护变得轻松、高效、愉悦。如果您想提升文档质量和使用体验，不妨试试 theSlate。