Create API docs using Slate

Simple tutorial

1. Fork slate github

https://github.com/slatedocs/slate

2. Clone to your local project

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

3. Setup local

cd slate
bundle install
bundle exec middleman server

if running ok, you will get a success message:

== The Middleman is loading
== View your site at "http://MFSs-MacBook-Pro.local:4567", "http://127.0.0.1:4567"
== Inspect your site configuration at "http://MFSs-MacBook-Pro.local:4567/__middleman", "http://127.0.0.1:4567/__middleman"

if you got an error, you can check which module should have to install with the right version by open Gemfile.

ruby '>=2.3.1'
source 'https://rubygems.org'
# Middleman
gem 'middleman', '~>4.2.1'
gem 'middleman-syntax', '~> 3.0.0'
gem 'middleman-autoprefixer', '~> 2.7.0'
gem "middleman-sprockets", "~> 4.1.0"
gem 'rouge', '~> 2.0.5'
gem 'redcarpet', '~> 3.4.0'
gem 'nokogiri', '~> 1.6.8.1'

• if you got an error about bundler version, check version for bundler using bundler -v . For example, i got an error because of bundler version is too high 1.2 and should downgrade by install version 1.1

sudo gem install bundler -v '~>1.1'

• when you run bundle exec middleman server and got an error about module nokogiri, you can install manually and change Gemfile based on your installed version

sudo gem install nokogiri -- --use-system-libraries

after installing you should change Gemfile, because its not the same version

#gem 'nokogiri', '~> 1.6.8.1'
gem 'nokogiri', '~> 1.10.7'

• if you got an internal error in web

brew uninstall --ignore-dependencies node icu4c

4. Deployment

because it just static files, deployment can be using any server platform. to produce this static file, we can use this command

sudo bundle exec middleman build --clean

then it will produce folder build under root folder. this folder is what we can put in poruction as docs online.

using Apache

Same result under /slate/build

5. Customization

After basic installation, you can customize by editing files under source index.html.md, using markdown style. You can learn markdown syntax in this site https://github.com/slatedocs/slate/wiki/Markdown-Syntax

Thanks for reading. I hope this article benefits for readers or at least for my documentations 😊