Slate: API Documentation Generator
Build Status

Slate helps you create beautiful, intelligent, responsive API documentation.

Screenshot of Example Documentation created with Slate

The example above was created with Slate. Check it out at lord.github.io/slate.

Features

  • Clean, intuitive design — With Slate, the description of your API is on the left side of your documentation, and all the code examples are on the right side. Inspired by Stripe's and Paypal's API docs. Slate is responsive, so it looks great on tablets, phones, and even in print.

  • Everything on a single page — Gone are the days when your users had to search through a million pages to find what they wanted. Slate puts the entire documentation on a single page. We haven't sacrificed linkability, though. As you scroll, your browser's hash will update to the nearest header, so linking to a particular point in the documentation is still natural and easy.

  • Slate is just Markdown — When you write docs with Slate, you're just writing Markdown, which makes it simple to edit and understand. Everything is written in Markdown — even the code samples are just Markdown code blocks.

  • Write code samples in multiple languages — If your API has bindings in multiple programming languages, you can easily put in tabs to switch between them. In your document, you'll distinguish different languages by specifying the language name at the top of each code block, just like with Github Flavored Markdown.

  • Out-of-the-box syntax highlighting for over 100 languages, no configuration required.

  • Automatic, smoothly scrolling table of contents on the far left of the page. As you scroll, it displays your current position in the document. It's fast, too. We're using Slate at TripIt to build documentation for our new API, where our table of contents has over 180 entries. We've made sure that the performance remains excellent, even for larger documents.

  • Let your users update your documentation for you — By default, your Slate-generated documentation is hosted in a public Github repository. Not only does this mean you get free hosting for your docs with Github Pages, but it also makes it simple for other developers to make pull requests to your docs if they find typos or other problems. Of course, if you don't want to use GitHub, you're also welcome to host your docs elsewhere.

Getting started with Slate is super easy! Simply fork this repository and follow the instructions below. Or, if you'd like to check out what Slate is capable of, take a look at the sample docs.

Getting Started with Slate

Prerequisites

You're going to need:

  • Linux or OS X — Windows may work, but is unsupported.
  • Ruby, version 2.2.5 or newer
  • Bundler — If Ruby is already installed, but the bundle command doesn't work, just run gem install bundler in a terminal.

Getting Set Up

  1. Fork this repository on Github.
  2. Clone your forked repository (not our original one) to your hard drive with git clone https://github.com/YOURUSERNAME/slate.git
  3. cd slate
  4. Initialize and start Slate. You can either do this locally, or with Vagrant:
# either run this to run locally
bundle install
bundle exec middleman server

# OR run this to run with vagrant
vagrant up

You can now see the docs at http://localhost:4567. Whoa! That was fast!

Now that Slate is all set up on your machine, you'll probably want to learn more about editing Slate markdown, or how to publish your docs.

If you'd prefer to use Docker, instructions are available in the wiki.

Companies Using Slate

You can view more in the list on the wiki.

Need Help? Found a bug?

Submit an issue to the Slate Github if you need any help. And, of course, feel free to submit pull requests with bug fixes or changes.

Contributors

Slate was built by Robert Lord while interning at TripIt.

Thanks to the following people who have submitted major pull requests:

Also, thanks to Sauce Labs for helping sponsor the project.

Special Thanks



     
   建立状态

Slate可帮助您创建美丽,智能,响应式的API文档。

截图与板岩

上面的示例是使用Slate创建的。请查看 lord.github.io/slate

功能

  • 清晰,直观的设计 - 使用Slate,您的API的描述位于文档的左侧,所有代码示例位于右侧。灵感来源于条纹 Paypal的 API文档。 Slate是敏感的,所以它在平板电脑,手机甚至印刷中看起来很棒。

  • 单一页面上的所有内容 - 您的用户不得不搜索百万页面以找到自己想要的日子。 Slate将整个文档放在一个页面上。尽管如此,我们并没有牺牲可链接性。滚动浏览器的哈希将会更新到最近的标题,因此链接到文档中的特定点仍然是自然而且容易的。

  • Slate只是Markdown - 当您使用Slate编写文档时,您只需编写Markdown,从而使编辑和理解变得简单。一切都是用Markdown写的 - 即使代码示例只是Markdown代码块。

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

  • > 100多种语言,无需配置。

  • 在页面最左侧自动平滑滚动目录。滚动时,会在文档中显示当前的位置。它也很快。我们在TripIt使用Slate为我们的新API构建文档,其中我们的目录中有180多个条目。我们确保性能保持优异,即使是较大的文档。

  • 让您的用户更新您的文档 - 默认情况下,您的Slate生成的文档托管在公共Github信息库中。这不仅意味着您可以使用Github Pages免费托管您的文档,而且还让其他开发人员简单的将拉请求发送到您的文档(如果他们找到打字错误或其他问题)。当然,如果您不想使用GitHub,也欢迎您在其他地方托管您的文档。

开始使用Slate是非常简单的!简单地分叉这个仓库,并按照以下说明。或者,如果您想查看Slate是否有能力,请查看示例文档

Slate入门

前提条件

您将需要:

  • Linux或OS X - Windows可能正常工作,但不受支持。
  • Ruby,版本2.2.5或更新
  • Bundler - 如果已经安装了Ruby,但是 bundle 命令不起作用,只需在终端中运行 gem install bundler 即可。

设置

  1. Fork this repository on Github.
  2. Clone your forked repository (not our original one) to your hard drive with git clone https://github.com/YOURUSERNAME/slate.git
  3. cd slate
  4. Initialize and start Slate. You can either do this locally, or with Vagrant:
# either run this to run locally
bundle install
bundle exec middleman server

# OR run this to run with vagrant vagrant up

现在,您可以在 http:// localhost:4567 查看文档。哇!那很快!

现在,Slate全部设置在您的机器上,您可能想要了解有关编辑Slate markdown的更多信息如何发布文档

如果您希望使用Docker,可以在wiki中 获取说明。

使用石板的公司

您可以在维基上的列表中查看更多内容

需要帮助?发现了一个错误?

如果您需要任何帮助,请将问题提交给Slate Github。而且,当然,请随时提交错误修正或更改的提交请求。

贡献者

Slate由 Robert Lord 构建,同时在 TripIt

感谢以下提交主要提请请求的人员:

此外,感谢酱汁实验室帮助赞助项目。

特别感谢




相关问题推荐