linux/Ubuntu安装slatedocs/slate可帮助您创建美观,智能,响应式的 API 文档

Slate：API文档生成器

Slate可帮助您创建美观，智能，响应迅速的API文档。

---

一、Slate是什么？

特征
简洁，直观的设计—使用Slate，API的描述位于文档的左侧，而所有代码示例均位于右侧。受Stripe和PayPal的API文档启发。Slate具有响应能力，因此在平板电脑，手机甚至印刷品上看起来都很棒。

一页上的所有内容—用户不得不搜索一百万个页面以查找所需内容的日子已经一去不复返了。Slate将整个文档放在单个页面上。不过，我们并未牺牲链接能力。滚动时，浏览器的哈希值将更新到最近的标头，因此链接到文档中的特定点仍然很自然且容易。

Slate就是Markdown —使用Slate编写文档时，您只是在编写Markdown，这使得编辑和理解变得简单。一切都以Markdown编写-甚至代码示例也只是Markdown代码块。

用多种语言编写代码示例-如果您的API具有多种编程语言的绑定，则可以轻松地在选项卡中进行切换。在您的文档中，您将通过在每个代码块的顶部指定语言名称来区分不同的语言，就像GitHub Flavored Markdown一样。

外的现成语法高亮的超过100种语言，不需要任何配置。

自动，平滑滚动的目录位于页面最左侧。滚动时，它将显示您在文档中的当前位置。它也很快。我们在TripIt上使用Slate来为新API构建文档，其中目录包含180多个条目。我们确保即使对于较大的文档，其性能也保持出色。

让您的用户为您更新文档-默认情况下，您由Slate生成的文档托管在公共GitHub存储库中。这不仅意味着您可以免费使用GitHub Pages托管文档，而且还使其他开发人员在发现拼写错误或其他问题时向您的文档发出拉取请求变得容易。当然，如果您不想使用GitHub，也欢迎在其他位置托管文档。

RTL支持RTL语言的完整从右到左布局，例如阿拉伯语，波斯语（波斯语），希伯来语等。

---

提示：以下是本篇文章正文内容，下面案例可供参考

示例：pandas 是基于NumPy 的一种工具，该工具是为了解决数据分析任务而创建的。

二、使用步骤

1.准备部署编译环境

源码位置：
1、https://github.com/slatedocs/slate/
2、https://github.com.cnpmjs.org/slatedocs/slate/ （国内快）

git clone https://github.com.cnpmjs.org/slatedocs/slate.git (国内加速）

Gemfile 文件内容如下（master分支）

ruby '>=2.3.1'
source 'https://rubygems.org'

# Middleman
gem 'middleman', '~>4.3'
gem 'middleman-syntax', '~> 3.2'
gem 'middleman-autoprefixer', '~> 2.7'
gem 'middleman-sprockets', '~> 4.1'
gem 'rouge', '~> 3.21'
gem 'redcarpet', '~> 3.5.0'
gem 'nokogiri', '~> 1.10.8'
gem 'sass'

替换source 国内镜像快很多
source ‘https://gems.ruby-china.com’

2.安装ruby >=2.3.1

sudo apt-get install ruby （centos 用yum）
我的环境是Ubuntu 20.04默认安装的是ruby2.7 如果安装失败一般是镜像源问题，更新一下镜像源即可。

安装ruby开发环境，没装大概率后面有报错。
1.Linux Centos 系统下执行 ：sudo yum install ruby-devel
2.Linux Ubuntu 系统下执行：sudo apt-get install ruby-dev

2.安装bundler及相关依赖

cd 到slate目录
注意：slate目录整个路径中请不要有中文，否则可能会报错。

sudo gem install bundler
bundle install

Warning: the running version of Bundler (2.1.2) is older than the version that created the lockfile (2.1.4). We suggest you to upgrade to the version that created the lockfile by running `gem install bundler:2.1.4`.
Fetching gem metadata from https://gems.ruby-china.com/............
Fetching gem metadata from https://gems.ruby-china.com/.
Resolving dependencies...
Using concurrent-ruby 1.1.7
Following files may not be writable, so sudo is needed:
  /var/lib/gems/2.7.0
  /var/lib/gems/2.7.0/build_info
  /var/lib/gems/2.7.0/cache
  /var/lib/gems/2.7.0/doc
  /var/lib/gems/2.7.0/extensions
  /var/lib/gems/2.7.0/gems
  /var/lib/gems/2.7.0/specifications
Using i18n 0.9.5
Using minitest 5.14.2
......
Fetching sass 3.7.4
Installing sass 3.7.4
Bundle complete! 8 Gemfile dependencies, 52 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.
Post-install message from sass:

Ruby Sass has reached end-of-life and should no longer be used.

* If you use Sass as a command-line tool, we recommend using Dart Sass, the new
  primary implementation: https://sass-lang.com/install

* If you use Sass as a plug-in for a Ruby web framework, we recommend using the
  sassc gem: https://github.com/sass/sassc-ruby#readme

* For more details, please refer to the Sass blog:
  https://sass-lang.com/blog/posts/7828841

3.预览md页面

启动服务
bundle exec middleman server

打开浏览器输入 http://127.0.0.1:4567/ 可以看到一个slate示例页面

4.使用md生成静态页面

bundle exec middleman build --clean

总结

如果不行推荐docker部署，详见slate下的Dockerfile

FROM ruby:2.6-slim

WORKDIR /srv/slate

VOLUME /srv/slate/build
VOLUME /srv/slate/source

EXPOSE 4567

COPY Gemfile .
COPY Gemfile.lock .

RUN apt-get update \
    && apt-get install -y --no-install-recommends \
        build-essential \
        nodejs \
    && gem install bundler \
    && bundle install \
    && apt-get remove -y build-essential \
    && apt-get autoremove -y \
    && rm -rf /var/lib/apt/lists/*

COPY . /srv/slate

RUN chmod +x /srv/slate/slate.sh

ENTRYPOINT ["/srv/slate/slate.sh"]
CMD ["build"]