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](https://stripe.com/docs/api) and [Paypal's](https://developer.paypal.com/webapps/developer/docs/api/) API docs. Slate is responsive, so it looks great on tablets, phones, and even print.
+* **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](https://stripe.com/docs/api) and [PayPal's](https://developer.paypal.com/webapps/developer/docs/api/) 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 where 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.
+* **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!
+* **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 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!
+* **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 [almost 60 languages](http://rouge.jayferd.us/demo), no configuration required.
+* **Out-of-the-box syntax highlighting** for [over 100 languages](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers), 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's 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, you're welcome to not use Github and host your docs elsewhere!
+* **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 ], you're also welcome to host your docs elsewhere.
-Getting starting with Slate is super easy! Simply fork this repository, and then follow the instructions below. Or, if you'd like to check out what Slate is capable of, take a look at the [sample docs](http://tripit.github.io/slate).
+* **RTL Support** Full right-to-left layout for RTL languages such as Arabic, Persian (Farsi), Hebrew etc.
-
+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](http://lord.github.io/slate).
Getting Started with Slate
------------------------------
@@ -37,59 +38,79 @@ Getting Started with Slate
You're going to need:
- - **Ruby, version 1.9.3 or newer**
+ - **Linux or OS X** — Windows may work, but is unsupported.
+ - **Ruby, version 2.3.1 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. Install all dependencies: `bundle install`
- 5. Start the test server: `bundle exec middleman server`
+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:
-You can now see the docs at . And as you edit `source/index.md`, your server should automatically update! Whoa! That was fast!
+```shell
+# either run this to run locally
+bundle install
+bundle exec middleman server
-Now that Slate is all set up your machine, you'll probably want to learn more about [editing Slate markdown](https://github.com/tripit/slate/wiki/Markdown-Syntax), or [how to publish your docs](https://github.com/tripit/slate/wiki/Deploying-Slate).
+# OR run this to run with vagrant
+vagrant up
+```
-Examples of Slate in the Wild
----------------------------------
+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](https://github.com/lord/slate/wiki/Markdown-Syntax), or [how to publish your docs](https://github.com/lord/slate/wiki/Deploying-Slate).
+
+If you'd prefer to use Docker, instructions are available [in the wiki](https://github.com/lord/slate/wiki/Docker).
-* [Travis-CI's API docs](http://docs.travis-ci.com/api/)
-* [Mozilla's localForage docs](http://mozilla.github.io/localForage/)
-* [Mozilla Recroom](http://mozilla.github.io/recroom/)
-* [ChaiOne Gameplan API docs](http://chaione.github.io/gameplanb2b/#introduction)
-* [Drcaban's Build a Quine tutorial](http://drcabana.github.io/build-a-quine/#introduction)
-* [PricePlow API docs](https://www.priceplow.com/api/documentation)
-* [Emerging Threats API docs](http://apidocs.emergingthreats.net/)
-* [Appium docs](http://appium.io/slate/en/master)
-* [Golazon Developer](http://developer.golazon.com)
-* [Dwolla API docs](https://docs.dwolla.com/)
+### Note on JavaScript Runtime
-(Feel free to add your site to this list in a pull request!)
+For those who don't have JavaScript runtime or are experiencing JavaScript runtime issues with ExecJS, it is recommended to add the [rubyracer gem](https://github.com/cowboyd/therubyracer) to your gemfile and run `bundle` again.
+
+Companies Using Slate
+---------------------------------
+
+* [NASA](https://api.nasa.gov)
+* [IBM](https://docs.cloudant.com/api.html)
+* [Sony](http://developers.cimediacloud.com)
+* [Best Buy](https://bestbuyapis.github.io/api-documentation/)
+* [Travis-CI](https://docs.travis-ci.com/api/)
+* [Greenhouse](https://developers.greenhouse.io/harvest.html)
+* [Woocommerce](http://woocommerce.github.io/woocommerce-rest-api-docs/)
+* [Appium](http://appium.io/slate/en/master)
+* [Dwolla](https://docs.dwolla.com/)
+* [Clearbit](https://clearbit.com/docs)
+* [Coinbase](https://developers.coinbase.com/api)
+* [Parrot Drones](http://developer.parrot.com/docs/bebop/)
+* [Fidor Bank](http://docs.fidor.de/)
+* [Scale](https://docs.scaleapi.com/)
+
+You can view more in [the list on the wiki](https://github.com/lord/slate/wiki/Slate-in-the-Wild).
Need Help? Found a bug?
--------------------
-Just [submit a issue](https://github.com/tripit/slate/issues) to the Slate Github if you need any help. And, of course, feel free to submit pull requests with bug fixes or changes.
-
+[Submit an issue](https://github.com/lord/slate/issues) 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](http://lord.io) while at [TripIt](http://tripit.com).
+Slate was built by [Robert Lord](https://lord.io) while interning at [TripIt](https://www.tripit.com/).
Thanks to the following people who have submitted major pull requests:
- [@chrissrogers](https://github.com/chrissrogers)
- [@bootstraponline](https://github.com/bootstraponline)
+- [@realityking](https://github.com/realityking)
+- [@cvkef](https://github.com/cvkef)
-Also, thanks to [Sauce Labs](http://saucelabs.com) for helping sponsor the project.
+Also, thanks to [Sauce Labs](http://saucelabs.com) for sponsoring the development of the responsive styles.
Special Thanks
--------------------
- [Middleman](https://github.com/middleman/middleman)
- [jquery.tocify.js](https://github.com/gfranko/jquery.tocify.js)
- [middleman-syntax](https://github.com/middleman/middleman-syntax)
-- [middleman-gh-pages](https://github.com/neo/middleman-gh-pages)
+- [middleman-gh-pages](https://github.com/edgecase/middleman-gh-pages)
- [Font Awesome](http://fortawesome.github.io/Font-Awesome/)
diff --git a/Rakefile b/Rakefile
deleted file mode 100644
index d6af6474b1d..00000000000
--- a/Rakefile
+++ /dev/null
@@ -1,3 +0,0 @@
-require 'middleman-gh-pages'
-
-task :default => [:build]
diff --git a/Vagrantfile b/Vagrantfile
new file mode 100644
index 00000000000..2fccb7c4b9a
--- /dev/null
+++ b/Vagrantfile
@@ -0,0 +1,41 @@
+Vagrant.configure(2) do |config|
+ config.vm.box = "ubuntu/trusty64"
+ config.vm.network :forwarded_port, guest: 4567, host: 4567
+
+ config.vm.provision "bootstrap",
+ type: "shell",
+ inline: <<-SHELL
+ sudo apt-add-repository ppa:brightbox/ruby-ng
+ sudo apt-get update
+ sudo apt-get install -yq ruby2.4 ruby2.4-dev
+ sudo apt-get install -yq pkg-config build-essential nodejs git libxml2-dev libxslt-dev
+ sudo apt-get autoremove -yq
+ gem2.4 install --no-ri --no-rdoc bundler
+ SHELL
+
+ # add the local user git config to the vm
+ config.vm.provision "file", source: "~/.gitconfig", destination: ".gitconfig"
+
+ config.vm.provision "install",
+ type: "shell",
+ privileged: false,
+ inline: <<-SHELL
+ echo "=============================================="
+ echo "Installing app dependencies"
+ cd /vagrant
+ bundle config build.nokogiri --use-system-libraries
+ bundle install
+ SHELL
+
+ config.vm.provision "run",
+ type: "shell",
+ privileged: false,
+ run: "always",
+ inline: <<-SHELL
+ echo "=============================================="
+ echo "Starting up middleman at http://localhost:4567"
+ echo "If it does not come up, check the ~/middleman.log file for any error messages"
+ cd /vagrant
+ bundle exec middleman server --watcher-force-polling --watcher-latency=1 &> ~/middleman.log &
+ SHELL
+end
\ No newline at end of file
diff --git a/config.rb b/config.rb
index c69665926c8..e0f2479edb4 100644
--- a/config.rb
+++ b/config.rb
@@ -1,39 +1,57 @@
-require './lib/redcarpet_header_fix'
+# Unique header generation
+require './lib/unique_head.rb'
+# Markdown
+set :markdown_engine, :redcarpet
+set :markdown,
+ fenced_code_blocks: true,
+ smartypants: true,
+ disable_indented_code_blocks: true,
+ prettify: true,
+ tables: true,
+ with_toc_data: true,
+ no_intra_emphasis: true,
+ renderer: UniqueHeadCounter
+
+# Assets
set :css_dir, 'stylesheets'
-
set :js_dir, 'javascripts'
-
set :images_dir, 'images'
-
set :fonts_dir, 'fonts'
-set :markdown_engine, :redcarpet
-
-set :markdown, :fenced_code_blocks => true, :smartypants => true, :disable_indented_code_blocks => true, :prettify => true, :tables => true, :with_toc_data => true, :no_intra_emphasis => true
-
# Activate the syntax highlighter
activate :syntax
+ready do
+ require './lib/multilang.rb'
+end
+
+activate :sprockets
-# This is needed for Github pages, since they're hosted on a subdomain
+activate :autoprefixer do |config|
+ config.browsers = ['last 2 version', 'Firefox ESR']
+ config.cascade = false
+ config.inline = true
+end
+
+# Github pages require relative links
activate :relative_assets
set :relative_links, true
-# Build-specific configuration
+# Build Configuration
configure :build do
- # For example, change the Compass output style for deployment
+ # If you're having trouble with Middleman hanging, commenting
+ # out the following two lines has been known to help
activate :minify_css
-
- # Minify Javascript on build
activate :minify_javascript
-
- # Enable cache buster
+ # activate :relative_assets
# activate :asset_hash
+ # activate :gzip
+end
- # Use relative URLs
- # activate :relative_assets
+# Deploy Configuration
+# If you want Middleman to listen on a different port, you can set that below
+set :port, 4567
- # Or use a different image path
- # set :http_prefix, "/Content/images/"
+helpers do
+ require './lib/toc_data.rb'
end
-
diff --git a/deploy.sh b/deploy.sh
new file mode 100755
index 00000000000..95fd1843d48
--- /dev/null
+++ b/deploy.sh
@@ -0,0 +1,215 @@
+#!/usr/bin/env bash
+set -o errexit #abort if any command fails
+me=$(basename "$0")
+
+help_message="\
+Usage: $me [-c FILE] []
+Deploy generated files to a git branch.
+
+Options:
+
+ -h, --help Show this help information.
+ -v, --verbose Increase verbosity. Useful for debugging.
+ -e, --allow-empty Allow deployment of an empty directory.
+ -m, --message MESSAGE Specify the message used when committing on the
+ deploy branch.
+ -n, --no-hash Don't append the source commit's hash to the deploy
+ commit's message.
+ --source-only Only build but not push
+ --push-only Only push but not build
+"
+
+
+run_build() {
+ bundle exec middleman build --clean
+}
+
+parse_args() {
+ # Set args from a local environment file.
+ if [ -e ".env" ]; then
+ source .env
+ fi
+
+ # Parse arg flags
+ # If something is exposed as an environment variable, set/overwrite it
+ # here. Otherwise, set/overwrite the internal variable instead.
+ while : ; do
+ if [[ $1 = "-h" || $1 = "--help" ]]; then
+ echo "$help_message"
+ return 0
+ elif [[ $1 = "-v" || $1 = "--verbose" ]]; then
+ verbose=true
+ shift
+ elif [[ $1 = "-e" || $1 = "--allow-empty" ]]; then
+ allow_empty=true
+ shift
+ elif [[ ( $1 = "-m" || $1 = "--message" ) && -n $2 ]]; then
+ commit_message=$2
+ shift 2
+ elif [[ $1 = "-n" || $1 = "--no-hash" ]]; then
+ GIT_DEPLOY_APPEND_HASH=false
+ shift
+ else
+ break
+ fi
+ done
+
+ # Set internal option vars from the environment and arg flags. All internal
+ # vars should be declared here, with sane defaults if applicable.
+
+ # Source directory & target branch.
+ deploy_directory=build
+ deploy_branch=gh-pages
+
+ #if no user identity is already set in the current git environment, use this:
+ default_username=${GIT_DEPLOY_USERNAME:-deploy.sh}
+ default_email=${GIT_DEPLOY_EMAIL:-}
+
+ #repository to deploy to. must be readable and writable.
+ repo=origin
+
+ #append commit hash to the end of message by default
+ append_hash=${GIT_DEPLOY_APPEND_HASH:-true}
+}
+
+main() {
+ parse_args "$@"
+
+ enable_expanded_output
+
+ if ! git diff --exit-code --quiet --cached; then
+ echo Aborting due to uncommitted changes in the index >&2
+ return 1
+ fi
+
+ commit_title=`git log -n 1 --format="%s" HEAD`
+ commit_hash=` git log -n 1 --format="%H" HEAD`
+
+ #default commit message uses last title if a custom one is not supplied
+ if [[ -z $commit_message ]]; then
+ commit_message="publish: $commit_title"
+ fi
+
+ #append hash to commit message unless no hash flag was found
+ if [ $append_hash = true ]; then
+ commit_message="$commit_message"$'\n\n'"generated from commit $commit_hash"
+ fi
+
+ previous_branch=`git rev-parse --abbrev-ref HEAD`
+
+ if [ ! -d "$deploy_directory" ]; then
+ echo "Deploy directory '$deploy_directory' does not exist. Aborting." >&2
+ return 1
+ fi
+
+ # must use short form of flag in ls for compatibility with OS X and BSD
+ if [[ -z `ls -A "$deploy_directory" 2> /dev/null` && -z $allow_empty ]]; then
+ echo "Deploy directory '$deploy_directory' is empty. Aborting. If you're sure you want to deploy an empty tree, use the --allow-empty / -e flag." >&2
+ return 1
+ fi
+
+ if git ls-remote --exit-code $repo "refs/heads/$deploy_branch" ; then
+ # deploy_branch exists in $repo; make sure we have the latest version
+
+ disable_expanded_output
+ git fetch --force $repo $deploy_branch:$deploy_branch
+ enable_expanded_output
+ fi
+
+ # check if deploy_branch exists locally
+ if git show-ref --verify --quiet "refs/heads/$deploy_branch"
+ then incremental_deploy
+ else initial_deploy
+ fi
+
+ restore_head
+}
+
+initial_deploy() {
+ git --work-tree "$deploy_directory" checkout --orphan $deploy_branch
+ git --work-tree "$deploy_directory" add --all
+ commit+push
+}
+
+incremental_deploy() {
+ #make deploy_branch the current branch
+ git symbolic-ref HEAD refs/heads/$deploy_branch
+ #put the previously committed contents of deploy_branch into the index
+ git --work-tree "$deploy_directory" reset --mixed --quiet
+ git --work-tree "$deploy_directory" add --all
+
+ set +o errexit
+ diff=$(git --work-tree "$deploy_directory" diff --exit-code --quiet HEAD --)$?
+ set -o errexit
+ case $diff in
+ 0) echo No changes to files in $deploy_directory. Skipping commit.;;
+ 1) commit+push;;
+ *)
+ echo git diff exited with code $diff. Aborting. Staying on branch $deploy_branch so you can debug. To switch back to master, use: git symbolic-ref HEAD refs/heads/master && git reset --mixed >&2
+ return $diff
+ ;;
+ esac
+}
+
+commit+push() {
+ set_user_id
+ git --work-tree "$deploy_directory" commit -m "$commit_message"
+
+ disable_expanded_output
+ #--quiet is important here to avoid outputting the repo URL, which may contain a secret token
+ git push --quiet $repo $deploy_branch
+ enable_expanded_output
+}
+
+#echo expanded commands as they are executed (for debugging)
+enable_expanded_output() {
+ if [ $verbose ]; then
+ set -o xtrace
+ set +o verbose
+ fi
+}
+
+#this is used to avoid outputting the repo URL, which may contain a secret token
+disable_expanded_output() {
+ if [ $verbose ]; then
+ set +o xtrace
+ set -o verbose
+ fi
+}
+
+set_user_id() {
+ if [[ -z `git config user.name` ]]; then
+ git config user.name "$default_username"
+ fi
+ if [[ -z `git config user.email` ]]; then
+ git config user.email "$default_email"
+ fi
+}
+
+restore_head() {
+ if [[ $previous_branch = "HEAD" ]]; then
+ #we weren't on any branch before, so just set HEAD back to the commit it was on
+ git update-ref --no-deref HEAD $commit_hash $deploy_branch
+ else
+ git symbolic-ref HEAD refs/heads/$previous_branch
+ fi
+
+ git reset --mixed
+}
+
+filter() {
+ sed -e "s|$repo|\$repo|g"
+}
+
+sanitize() {
+ "$@" 2> >(filter 1>&2) | filter
+}
+
+if [[ $1 = --source-only ]]; then
+ run_build
+elif [[ $1 = --push-only ]]; then
+ main "$@"
+else
+ run_build
+ main "$@"
+fi
diff --git a/font-selection.json b/font-selection.json
new file mode 100755
index 00000000000..5e78f5d8621
--- /dev/null
+++ b/font-selection.json
@@ -0,0 +1,148 @@
+{
+ "IcoMoonType": "selection",
+ "icons": [
+ {
+ "icon": {
+ "paths": [
+ "M438.857 73.143q119.429 0 220.286 58.857t159.714 159.714 58.857 220.286-58.857 220.286-159.714 159.714-220.286 58.857-220.286-58.857-159.714-159.714-58.857-220.286 58.857-220.286 159.714-159.714 220.286-58.857zM512 785.714v-108.571q0-8-5.143-13.429t-12.571-5.429h-109.714q-7.429 0-13.143 5.714t-5.714 13.143v108.571q0 7.429 5.714 13.143t13.143 5.714h109.714q7.429 0 12.571-5.429t5.143-13.429zM510.857 589.143l10.286-354.857q0-6.857-5.714-10.286-5.714-4.571-13.714-4.571h-125.714q-8 0-13.714 4.571-5.714 3.429-5.714 10.286l9.714 354.857q0 5.714 5.714 10t13.714 4.286h105.714q8 0 13.429-4.286t6-10z"
+ ],
+ "attrs": [],
+ "isMulticolor": false,
+ "tags": [
+ "exclamation-circle"
+ ],
+ "defaultCode": 61546,
+ "grid": 14
+ },
+ "attrs": [],
+ "properties": {
+ "id": 100,
+ "order": 4,
+ "prevSize": 28,
+ "code": 58880,
+ "name": "exclamation-sign",
+ "ligatures": ""
+ },
+ "setIdx": 0,
+ "iconIdx": 0
+ },
+ {
+ "icon": {
+ "paths": [
+ "M585.143 786.286v-91.429q0-8-5.143-13.143t-13.143-5.143h-54.857v-292.571q0-8-5.143-13.143t-13.143-5.143h-182.857q-8 0-13.143 5.143t-5.143 13.143v91.429q0 8 5.143 13.143t13.143 5.143h54.857v182.857h-54.857q-8 0-13.143 5.143t-5.143 13.143v91.429q0 8 5.143 13.143t13.143 5.143h256q8 0 13.143-5.143t5.143-13.143zM512 274.286v-91.429q0-8-5.143-13.143t-13.143-5.143h-109.714q-8 0-13.143 5.143t-5.143 13.143v91.429q0 8 5.143 13.143t13.143 5.143h109.714q8 0 13.143-5.143t5.143-13.143zM877.714 512q0 119.429-58.857 220.286t-159.714 159.714-220.286 58.857-220.286-58.857-159.714-159.714-58.857-220.286 58.857-220.286 159.714-159.714 220.286-58.857 220.286 58.857 159.714 159.714 58.857 220.286z"
+ ],
+ "attrs": [],
+ "isMulticolor": false,
+ "tags": [
+ "info-circle"
+ ],
+ "defaultCode": 61530,
+ "grid": 14
+ },
+ "attrs": [],
+ "properties": {
+ "id": 85,
+ "order": 3,
+ "name": "info-sign",
+ "prevSize": 28,
+ "code": 58882
+ },
+ "setIdx": 0,
+ "iconIdx": 2
+ },
+ {
+ "icon": {
+ "paths": [
+ "M733.714 419.429q0-16-10.286-26.286l-52-51.429q-10.857-10.857-25.714-10.857t-25.714 10.857l-233.143 232.571-129.143-129.143q-10.857-10.857-25.714-10.857t-25.714 10.857l-52 51.429q-10.286 10.286-10.286 26.286 0 15.429 10.286 25.714l206.857 206.857q10.857 10.857 25.714 10.857 15.429 0 26.286-10.857l310.286-310.286q10.286-10.286 10.286-25.714zM877.714 512q0 119.429-58.857 220.286t-159.714 159.714-220.286 58.857-220.286-58.857-159.714-159.714-58.857-220.286 58.857-220.286 159.714-159.714 220.286-58.857 220.286 58.857 159.714 159.714 58.857 220.286z"
+ ],
+ "attrs": [],
+ "isMulticolor": false,
+ "tags": [
+ "check-circle"
+ ],
+ "defaultCode": 61528,
+ "grid": 14
+ },
+ "attrs": [],
+ "properties": {
+ "id": 83,
+ "order": 9,
+ "prevSize": 28,
+ "code": 58886,
+ "name": "ok-sign"
+ },
+ "setIdx": 0,
+ "iconIdx": 6
+ },
+ {
+ "icon": {
+ "paths": [
+ "M658.286 475.429q0-105.714-75.143-180.857t-180.857-75.143-180.857 75.143-75.143 180.857 75.143 180.857 180.857 75.143 180.857-75.143 75.143-180.857zM950.857 950.857q0 29.714-21.714 51.429t-51.429 21.714q-30.857 0-51.429-21.714l-196-195.429q-102.286 70.857-228 70.857-81.714 0-156.286-31.714t-128.571-85.714-85.714-128.571-31.714-156.286 31.714-156.286 85.714-128.571 128.571-85.714 156.286-31.714 156.286 31.714 128.571 85.714 85.714 128.571 31.714 156.286q0 125.714-70.857 228l196 196q21.143 21.143 21.143 51.429z"
+ ],
+ "width": 951,
+ "attrs": [],
+ "isMulticolor": false,
+ "tags": [
+ "search"
+ ],
+ "defaultCode": 61442,
+ "grid": 14
+ },
+ "attrs": [],
+ "properties": {
+ "id": 2,
+ "order": 1,
+ "prevSize": 28,
+ "code": 58887,
+ "name": "icon-search"
+ },
+ "setIdx": 0,
+ "iconIdx": 7
+ }
+ ],
+ "height": 1024,
+ "metadata": {
+ "name": "slate",
+ "license": "SIL OFL 1.1"
+ },
+ "preferences": {
+ "showGlyphs": true,
+ "showQuickUse": true,
+ "showQuickUse2": true,
+ "showSVGs": true,
+ "fontPref": {
+ "prefix": "icon-",
+ "metadata": {
+ "fontFamily": "slate",
+ "majorVersion": 1,
+ "minorVersion": 0,
+ "description": "Based on FontAwesome",
+ "license": "SIL OFL 1.1"
+ },
+ "metrics": {
+ "emSize": 1024,
+ "baseline": 6.25,
+ "whitespace": 50
+ },
+ "resetPoint": 58880,
+ "showSelector": false,
+ "selector": "class",
+ "classSelector": ".icon",
+ "showMetrics": false,
+ "showMetadata": true,
+ "showVersion": true,
+ "ie7": false
+ },
+ "imagePref": {
+ "prefix": "icon-",
+ "png": true,
+ "useClassSelector": true,
+ "color": 4473924,
+ "bgColor": 16777215
+ },
+ "historySize": 100,
+ "showCodes": true,
+ "gridSize": 16,
+ "showLiga": false
+ }
+}
diff --git a/lib/multilang.rb b/lib/multilang.rb
new file mode 100644
index 00000000000..36fbe5b1f07
--- /dev/null
+++ b/lib/multilang.rb
@@ -0,0 +1,16 @@
+module Multilang
+ def block_code(code, full_lang_name)
+ if full_lang_name
+ parts = full_lang_name.split('--')
+ rouge_lang_name = (parts) ? parts[0] : "" # just parts[0] here causes null ref exception when no language specified
+ super(code, rouge_lang_name).sub("highlight #{rouge_lang_name}") do |match|
+ match + " tab-" + full_lang_name
+ end
+ else
+ super(code, full_lang_name)
+ end
+ end
+end
+
+require 'middleman-core/renderers/redcarpet'
+Middleman::Renderers::MiddlemanRedcarpetHTML.send :include, Multilang
diff --git a/lib/redcarpet_header_fix.rb b/lib/redcarpet_header_fix.rb
deleted file mode 100644
index 72883ce1404..00000000000
--- a/lib/redcarpet_header_fix.rb
+++ /dev/null
@@ -1,9 +0,0 @@
-module RedcarpetHeaderFix
- def header(text, level)
- clean_id = text.downcase.gsub(/( +|\.+)/, '-').gsub(/[^a-zA-Z0-9\-_]/, '')
- "#{text}"
- end
-end
-
-require 'middleman-core/renderers/redcarpet'
-Middleman::Renderers::MiddlemanRedcarpetHTML.send :include, RedcarpetHeaderFix
diff --git a/lib/toc_data.rb b/lib/toc_data.rb
new file mode 100644
index 00000000000..f4663cd2655
--- /dev/null
+++ b/lib/toc_data.rb
@@ -0,0 +1,30 @@
+require 'nokogiri'
+
+def toc_data(page_content)
+ html_doc = Nokogiri::HTML::DocumentFragment.parse(page_content)
+
+ # get a flat list of headers
+ headers = []
+ html_doc.css('h1, h2, h3').each do |header|
+ headers.push({
+ id: header.attribute('id').to_s,
+ content: header.children,
+ level: header.name[1].to_i,
+ children: []
+ })
+ end
+
+ [3,2].each do |header_level|
+ header_to_nest = nil
+ headers = headers.reject do |header|
+ if header[:level] == header_level
+ header_to_nest[:children].push header if header_to_nest
+ true
+ else
+ header_to_nest = header if header[:level] < header_level
+ false
+ end
+ end
+ end
+ headers
+end
\ No newline at end of file
diff --git a/lib/unique_head.rb b/lib/unique_head.rb
new file mode 100644
index 00000000000..c5dc2790e0b
--- /dev/null
+++ b/lib/unique_head.rb
@@ -0,0 +1,17 @@
+# Unique header generation
+require 'middleman-core/renderers/redcarpet'
+class UniqueHeadCounter < Middleman::Renderers::MiddlemanRedcarpetHTML
+ def initialize
+ super
+ @head_count = {}
+ end
+ def header(text, header_level)
+ friendly_text = text.parameterize
+ @head_count[friendly_text] ||= 0
+ @head_count[friendly_text] += 1
+ if @head_count[friendly_text] > 1
+ friendly_text += "-#{@head_count[friendly_text]}"
+ end
+ return "#{text}"
+ end
+end
diff --git a/source/CNAME b/source/CNAME
new file mode 100644
index 00000000000..b022b3638b3
--- /dev/null
+++ b/source/CNAME
@@ -0,0 +1 @@
+docs.oauth.io
\ No newline at end of file
diff --git a/source/fonts/icomoon.eot b/source/fonts/icomoon.eot
deleted file mode 100755
index 212835a5243..00000000000
Binary files a/source/fonts/icomoon.eot and /dev/null differ
diff --git a/source/fonts/icomoon.svg b/source/fonts/icomoon.svg
deleted file mode 100755
index 24493587d38..00000000000
--- a/source/fonts/icomoon.svg
+++ /dev/null
@@ -1,18 +0,0 @@
-
-
-
\ No newline at end of file
diff --git a/source/fonts/icomoon.ttf b/source/fonts/icomoon.ttf
deleted file mode 100755
index 360b3d75162..00000000000
Binary files a/source/fonts/icomoon.ttf and /dev/null differ
diff --git a/source/fonts/icomoon.woff b/source/fonts/icomoon.woff
deleted file mode 100755
index 9a213b11266..00000000000
Binary files a/source/fonts/icomoon.woff and /dev/null differ
diff --git a/source/fonts/slate.eot b/source/fonts/slate.eot
new file mode 100644
index 00000000000..13c4839a197
Binary files /dev/null and b/source/fonts/slate.eot differ
diff --git a/source/fonts/slate.svg b/source/fonts/slate.svg
new file mode 100644
index 00000000000..5f34982306b
--- /dev/null
+++ b/source/fonts/slate.svg
@@ -0,0 +1,14 @@
+
+
+
diff --git a/source/fonts/slate.ttf b/source/fonts/slate.ttf
new file mode 100644
index 00000000000..ace9a46a7e1
Binary files /dev/null and b/source/fonts/slate.ttf differ
diff --git a/source/fonts/slate.woff b/source/fonts/slate.woff
new file mode 100644
index 00000000000..1e72e0ee001
Binary files /dev/null and b/source/fonts/slate.woff differ
diff --git a/source/fonts/slate.woff2 b/source/fonts/slate.woff2
new file mode 100644
index 00000000000..7c585a72737
Binary files /dev/null and b/source/fonts/slate.woff2 differ
diff --git a/source/images/logo.png b/source/images/logo.png
index 24e509952c5..dce4478c6ca 100644
Binary files a/source/images/logo.png and b/source/images/logo.png differ
diff --git a/source/images/navbar.png b/source/images/navbar.png
index 32e70e14fb4..df38e90d87e 100644
Binary files a/source/images/navbar.png and b/source/images/navbar.png differ
diff --git a/source/includes/_contribute.md b/source/includes/_contribute.md
new file mode 100644
index 00000000000..9a638d85e59
--- /dev/null
+++ b/source/includes/_contribute.md
@@ -0,0 +1,55 @@
+
+# Contribute
+
+You can contribute by cloning our [oauthd repository](https://github.com/oauth-io/oauthd), or any of our SDK's repositories on GitHub (please check [this repository list](https://github.com/oauth-io)) and making a pull request.
+
+## Issues
+
+If you have any issue using OAuth.io, you can:
+
+* Open a QA on [StackOverflow](http://stackoverflow.com/) (with the mention of OAuth.io in the title).
+
+* Open a [GitHub issue](https://github.com/oauth-io) on the appropriate repository.
+
+* If the content is private, feel free to send us an email on [support@oauth.io](mailto:support@oauth.io)
+
+* You can ping us on Twitter with the mention [@oauth_io](https://twitter.com/oauth_io)
+
+We try to be as reactive as possible on every channel, according to the support questions load, and to the chosen plan (paying customers have the priority on support).
+
+## Adding Providers to OAuth.io
+
+You can easily add new OAuth providers in OAuth.io by using our configuration file format.
+
+The format is [explained here](https://github.com/oauth-io/oauthd/wiki/Specs:-Provider's-configuration) and you can find all the existing OAuth providers on our [GitHub repository](https://github.com/oauth-io/oauthd/tree/master/providers).
+
+Once you've implemented your provider, you can test it using [oauthd](https://github.com/oauth-io/oauthd), the opensource version of OAuth.io and then, just make a pull request and we'll merge it into OAuth.io as soon as we can.
+
+A provider contains 4 simple files:
+
+* __conf.json__ The OAuth provider's JSON file (e.g. facebook.json)
+* __settings.json__ - Some settings for users who want to add the OAuth provider in OAuth.io (e.g. the link and screenshot where developers can create an application with your provider)
+* __logo.png__ - The logo of the OAuth provider
+* __me.js__ (optional) - A file used to retrieve the user information in a unified way.
+
+## Pull request (bug fixes / providers / typos)
+
+You're welcome to fork our repositories on GitHub to make pull requests. We'll review each of them, and integrate all the relevant changes in a future release.
+
+In every repository, we have included notes in the README.md file to show you how to test your feature.
+
+### oauthd
+
+Fork [the repository](https://github.com/oauth-io/oauthd) to implement your feature / bug fixes.
+
+You can use `npm link` to use the `oauthd` command anywhere in your console, and create test instances.
+
+OAuth.io is an oauthd instance, so if you find and fix bugs in oauthd, the changes will also be on OAuth.io.
+
+### SDKs
+
+You can fork all the SDKs from GitHub in your favorite language. Every SDK (except iOS for the moment) has a test suite than can be launched in a standard way to try your feature / bug fixes.
+
+### Documentation
+
+You can fork all the [documentation from GitHub](https://github.com/oauth-io/docs). The content is in the `source` folder. The main file is `index.md`
diff --git a/source/includes/_errors.md b/source/includes/_errors.md
deleted file mode 100644
index eeefbb5b777..00000000000
--- a/source/includes/_errors.md
+++ /dev/null
@@ -1,20 +0,0 @@
-# Errors
-
-
-
-The Kittn API uses the following error codes:
-
-
-Error Code | Meaning
----------- | -------
-400 | Bad Request -- Your request sucks
-401 | Unauthorized -- Your API key is wrong
-403 | Forbidden -- The kitten requested is hidden for administrators only
-404 | Not Found -- The specified kitten could not be found
-405 | Method Not Allowed -- You tried to access a kitten with an invalid method
-406 | Not Acceptable -- You requested a format that isn't json
-410 | Gone -- The kitten requested has been removed from our servers
-418 | I'm a teapot
-429 | Too Many Requests -- You're requesting too many kittens! Slown down!
-500 | Internal Server Error -- We had a problem with our server. Try again later.
-503 | Service Unavailable -- We're temporarially offline for maintanance. Please try again later.
\ No newline at end of file
diff --git a/source/includes/_install.md b/source/includes/_install.md
new file mode 100644
index 00000000000..184c3506a3a
--- /dev/null
+++ b/source/includes/_install.md
@@ -0,0 +1,142 @@
+# Installation
+
+## Download the SDK
+
+
+
npm install oauthio
+
+
+
+
+You can use CocoaPods to install OAuth.io in your iOS project
+
+
+
+
+
Download the android library:
+
+wget https://github.com/oauth-io/oauth-android/archive/master.zip
+
+or clone it from github:
+
+git clone git@github.com:oauth-io/oauth-android
+
+and import the oauthio folder into your project folder as a module.
+
+If you are not using Android Studio, you need to add this persmission into your `AndroidManifest.xml` file:
+
+<uses-permission android:name="android.permission.INTERNET" />
+
+
+
+
+# add this line to your Podfile:
+pod 'OAuth.io'
+
+
+# run this command in your project directory
+$ pod install
+
+
+You can also install the framework manually. To do so, please follow the following steps:
+
+The framework is available in [https://github.com/oauth-io/oauth-ios](https://github.com/oauth-io/oauth-ios) as the Dist/OAuthiOS.framework file. To add it as a dependency in your projet in XCode, follow this procedure:
+
+- click on the project name in the Documents explorer
+go to Build phases
+- open the Link Binary with Libraries section
+- click on the + button
+- click on Add other...
+- Select the OAuthiOS.framework
+- Click on Add
+
+
+
+
+
You can use Composer to install the SDK in your PHP project.
+
+
+# Add this line to require object of your composer.json file:
+"oauth-io/oauth": "0.3.0"
+# Run this command in your folder directory
+$ composer update
+
+
+
+
+
#For Web app
+bower install oauth.io
+
+#Or for mobile app (using Phonegap)
+phonegap plugin install https://github.com/oauth-io/oauth-phonegap
+
+
+To ease your integration, SDKs are available in lots of language:
+
+- [Javascript](https://github.com/oauth-io/oauth-js)
+- [Phonegap/Cordova](https://github.com/oauth-io/oauth-phonegap)
+- [iOS](https://github.com/oauth-io/oauth-ios)
+- [Android](https://github.com/oauth-io/oauth-android)
+- [PHP](https://github.com/oauth-io/sdk-php)
+- [Node.js](https://github.com/oauth-io/sdk-node)
+- [Go](https://github.com/oauth-io/sdk-go)
+
+## Install the SDK
+
+
+
var OAuth = require('oauthio');
+// Initialize the SDK
+OAuth.initialize('Your-public-key', 'Your-secret-key');
+
+To install the SDK, you just need to load it in your source code.
+
+
+
// Initialize the SDK
+OAuth.initialize('Your-public-key')
+
+
+
+
You need to create a class implementing the OAuthIODelegate. This delegate needs you to add the following methods:
+
+- "didReceiveOAuthIOResponse": called when a popup call is successful
+- "didFailWithOAuthIOError": called when a popup call is not successful
+- "didAuthenticateServerSide": when using the server-side mode, called on a successful authentication
+- "didFailAuthenticationServerSide": when using the server-side mode, called on an unsuccessful authentication
+
+
+// Then in the class implementing OAuthIODelegate, you can initialize the SDK
+// Initialize the SDK
+_oauthioModal = [[OAuthIOModal alloc] initWithKey:@"Your-public-key" delegate:self];
+
+
+
+
+use OAuth_io\OAuth;
+
+$oauth = new OAuth();
+// Initialize the SDK
+$oauth->initialize('Your-public-key', 'Your-secret-key');
+
+
+
+
+
+import io.oauth.OAuth;
+
+...
+
+oauth = new OAuth(getActivity());
+// Initialize the SDK
+oauth.initialize("Your-public-key");
+
+
+
+
+When you create an OAuth.io application in your dashboard, a pair of public key, private key is generated. You will need this pair to initialize the SDK later on.
+
+
diff --git a/source/includes/_request.md b/source/includes/_request.md
new file mode 100644
index 00000000000..e27c8d75571
--- /dev/null
+++ b/source/includes/_request.md
@@ -0,0 +1,386 @@
+
+# Request API
+
+
+
OAuth.auth(provider, req.session).then(function(oauthResult) {
+ return oauthResult.get('/me')
+}).then(function(data) {
+ //data is the result of the request to /me
+}).fail(function(err) {
+ //handle an error
+});
+
+
+
+
+ $me = $request_object->get('/me');
+
+
+
+
+
OAuth.popup(provider).then(function(oauthResult) {
+ return oauthResult.get('/me');
+}).then(function(data) {
+ // data is the result of the request to /me
+}).fail(function(err) {
+ // handle an error
+});
+
+
+
+
+// In a
+- (void)didReceiveOAuthIOResponse:(OAuthIORequest *)request
+{
+ // The request object
+ _request_object = request;
+
+ // Making a request
+ [_request_object get:@"/me" success:^(NSDictionary *output, NSString *body, NSHTTPURLResponse *httpResponse)
+ {
+ // logs the the user's information
+ NSLog(@"%@", body);
+ }];
+}
+
+
+
+
+
data.http("/me", new OAuthRequest() {
+ @Override
+ public void onSetURL(String _url) {
+ // This method is called once the final url is returned.
+ }
+
+ @Override
+ public void onSetHeader(String header, String value) {
+ // This method is called for each header to add to the request.
+ }
+
+ @Override
+ public void onReady() {
+ // This method is called once url and headers are set.
+ }
+
+ @Override
+ public void onError(String message) {
+ // This method is called if an error occured
+ }
+});
+
+
+
+The Request API allows you to easily perform authorized API calls to the OAuth provider from which you got a request object or credentials with the Token API. You can perform classic HTTP calls using GET, POST, PUT, DELETE, PATCH. OAuth.io will automatically fill all authorization parameters for you (OAuth1 signature, nonce, timestamp, access_token, oauth_token etc...). All the parameters in the request will be sent to the provider thanks to the oauth.io proxy.
+
+
+
data.http(new OAuthJSONRequest(OAuthJSONRequest.HTTP_GET, "/me"), new OAuthJSONCallback() {
+ @Override
+ public void onFinished(JSONObject data) {
+ // data is the result of the request to /me
+ }
+
+ @Override
+ public void onError(String message) {
+ // handle an error
+ }
+});
+
+
+
+
+
+## GET
+
+
+
oauthResult.get(url).then(function(data) {
+ //todo with data
+}).fail(function(err) {
+ //todo with err
+});
+
+
+
+
oauthResult.get(url).done(function(data) {
+ //todo with data
+}).fail(function(err) {
+ //todo with err
+});
+
+
+
+
+$me = $request_object->get('/me');
+
+
+
+
+
+// Making a request
+[_request_object get:@"/me" success:^(NSDictionary *output, NSString *body, NSHTTPURLResponse *httpResponse)
+{
+ // logs the the user's information
+ NSLog(@"%@", body);
+}];
+
+
+
+
// See http method
+
+Allows you to perform `GET` request to an API endpoint
+
+Argument|Description|Type|Example value
+--------|-----------|----|-------------
+url|The URL of the endpoint, it can be an absolute URL or just the endpoint (after the domain) as for most provider, the domain is already known|string|/api/endpoint?param=value
+
+## POST
+
+
+
oauthResult.post(url, params).done(function(data) {
+ //todo with data
+}).fail(function(err) {
+ //todo with err
+});
+
+// params has the same syntaxe as jQuery.ajax (http://api.jquery.com/jquery.ajax/)
+//e.g Post a tweet on Twitter
+oauthResult.post('/1.1/statuses/update.json', {
+ data: {
+ status: "hello world!"
+ }
+})
+
+
+
+
oauthResult.post(url, params).done(function(data) {
+ //todo with data
+}).fail(function(err) {
+ //todo with err
+});
+
+//e.g Post a tweet on Twitter
+oauthResult.post('/1.1/statuses/update.json', {
+ status: "hello world!"
+});
+
+Allows you to perform `POST` request to an API endpoint
+
+Argument|Description|Type|Example value
+--------|-----------|----|-------------
+url|The URL of the endpoint, it can be an absolute URL or just the endpoint (after the domain) as for most provider, the domain is already known|string|/api/endpoint
+params|The parameters of the HTTP request|Object|
+
+## PUT
+
+
+
oauthResult.put(url, params).done(function(data) {
+ //todo with data
+}).fail(function(err) {
+ //todo with err
+});
+
+//e.g Merge a pull request on Github
+oauthResult.put('/repos/oauth-io/oauthd/pulls/5/merge')
+
+
+
+
oauthResult.put(url, params).done(function(data) {
+ //todo with data
+}).fail(function(err) {
+ //todo with err
+});
+
+//e.g Merge a pull request on Github
+oauthResult.put('/repos/oauth-io/oauthd/pulls/5/merge');
+
+
+Allows you to perform `PUT` request to an API endpoint
+
+Argument|Description|Type|Example value
+--------|-----------|----|-------------
+url|The URL of the endpoint, it can be an absolute URL or just the endpoint (after the domain) as for most provider, the domain is already known|string|/api/endpoint
+params|The parameters of the HTTP request|Object|
+
+## DELETE
+
+
+
oauthResult.del(url).then(function(data) {
+ //todo with data
+}).fail(function(err) {
+ //todo with err
+});
+
+//e.g Delete a status on Facebook
+oauthResult.del('/v2.2/:status_id')
+
+
+Allows you to perform `DELETE` request to an API endpoint
+
+Argument|Description|Type|Example value
+--------|-----------|----|-------------
+url|The URL of the endpoint, it can be an absolute URL or just the endpoint (after the domain) as for most provider, the domain is already known|string|/api/endpoint
+
+## PATCH
+
+
+
oauthResult.patch(url, params).done(function(data) {
+ //todo with data
+}).fail(function(err) {
+ //todo with err
+});
+
+// params has the same syntaxe as jQuery.ajax (http://api.jquery.com/jquery.ajax/)
+//e.g Edit a Gist on Github
+oauthResult.patch('/gists/1', {
+ data: {
+ "description": "the description for this gist",
+ "files": {
+ "file1.txt": {
+ "content": "updated file contents"
+ },
+ "new_file.txt": {
+ "content": "a new file"
+ }
+ }
+ }
+})
+
+
+
+
oauthResult.put(url, params).done(function(data) {
+ //todo with data
+}).fail(function(err) {
+ //todo with err
+});
+
+//e.g Merge a pull request on Github
+oauthResult.patch('/gists/1', {
+ "description": "the description for this gist",
+ "files": {
+ "file1.txt": {
+ "content": "updated file contents"
+ },
+ "new_file.txt": {
+ "content": "a new file"
+ }
+ }
+});
+
+
+Allows you to perform `PATCH` request to an API endpoint
+
+Argument|Description|Type|Example value
+--------|-----------|----|-------------
+url|The URL of the endpoint, it can be an absolute URL or just the endpoint (after the domain) as for most provider, the domain is already known|string|/api/endpoint
+params|The parameters of the HTTP request|Object|
+
+## USING REST
+
+
+
#Example with twitter on /1.1/account/verify_credentials.json
+
+GET /request/twitter/%2F1.1%2Faccount%2Fverify_credentials.json HTTP/1.1
+Host: oauth.io
+oauthio: k=OAUTHIO_PUBLIC_KEY&oauthv=1&oauth_token=TWITTER_PUBLIC_TOKEN&oauth_token_secret=TWITTER_SECRET_TOKEN
+Referer: https://whitelisted_domain_in_oauthio/
+
+
+`GET|POST|PUT|DELETE|PATCH https://oauth.io/request/:provider/:url`
+
+Field|Description
+-----|-----------
+provider|The provider's name (e.g. "facebook")
+url|The api request's url, can be relative to the main api domain (e.g `api.facebook.com`) or absolute. This url must be urlencoded.
+
+You must include the `oauthio` HTTP header inside your request, which is a application/x-www-form-urlencoded hash containing:
+
+Field|Description
+-----|-----------
+k|The public OAuth.io key of your app. If the http header Origin or Referer is set, this will be checked against your app's whitelist. If none are present, you must accept the "localhost" domain in your OAuthio's app.
+oauth_token|OAuth1 public token.
+oauth_secret_token|OAuth1 secret token.
+access_token|OAuth2 token.
+oauthv *(optional)*|when a provider supports both OAuth1 and OAuth2, this can be set to "1" or "2" to desambiguate the version of OAuth to use.
diff --git a/source/includes/_token.md b/source/includes/_token.md
new file mode 100644
index 00000000000..061b93fec72
--- /dev/null
+++ b/source/includes/_token.md
@@ -0,0 +1,485 @@
+# Token API - Client side
+
+The Token API lets you authorize your app on behalf of your users on one of our 120+ API providers. The best known example is to add a Facebook connect to your website to ease the user's onboarding.
+
+You can perform this authorization either client-side or server-side, depending your needs.
+
+
The Client side section is not available for this SDK
+
+
+
+## Configuration
+
+To authorize your app using OAuth.io, you just need to add a provider to your OAuth.io app, copy/paste your provider's API Keys (usually client_id and client_secret), and specify a permission scope. Then, you can directly try a connection to the provider, by clicking on the `Try auth` button.
+
+## Authorize with a popup
+
+
//Example with Facebook
+OAuth.popup('facebook').done(function(facebook) {
+ //make API calls with `facebook`
+}).fail(function(err) {
+ //todo when the OAuth flow failed
+});
+
//Example with Twitter with the cache option enabled
+OAuth.popup('twitter', {cache: true}).done(function(twitter) {
+ //make API calls with `twitter`
+}).fail(function(err) {
+ //todo when the OAuth flow failed
+})
+
+
+
+
In the OAuthIODelegate class, you can call the showWithProvider method, which shows a popup.
+
+
+//Example with Twitter with no cache options
+[_oauthioModal showWithProvider:@"twitter"];
+
+//On success, the didReceiveOAuthIOResponde delegate method is called:
+- (void)didReceiveOAuthIOResponse:(OAuthIORequest *)request
+{
+ // Here you can use the request object to make requests directly
+ // or store it for later use (e.g. when a button is pressed)
+ _request_object = request;
+}
+
+
+
+
+
+oauth.popup("facebook", new OAuthCallback() {
+ @Override
+ public void onFinished(OAuthData data) {
+ if (data.status.equals("error"))
+ activity.displayError(data.error);
+ else {
+ // Do API calls with data
+ }
+ }
+});
+
+
+
+This mode asks the user's authorization in a simple popup.
+This gives you a request object, which allows you to perform API calls, or to retrieve the credentials (i.e. access or oauth tokens).
+
+You can send multiple options to customize it.
+
+Options|Description|Type|Default value
+-------|-----------|----|-------------
+cache|If set to true, when the popup is called, the SDK will directly return the cached credentials (if available) through a "request object" instead of showing a popup everytime the user logs in. That is to say, once the user has seen the popup on his browser, his credentials are kept in the local storage.|boolean|false
+authorize|Some OAuth providers let developers send parameters to customize the authorization popup|Object|null
+
+## Authorize with redirection
+
+
+
//Example with Google
+OAuth.redirect('google', 'http://localhost/callback');
+
//in your callback page (can be the same page)
+OAuth.callback('google').done(function(google) {
+ //make API calls with `google`
+}).fail(function(err) {
+ //todo when the OAuth flow failed
+})
+
+
+Redirects to the provider's login page, where the user can accept your app's permissions. Once he/she accepts them, he/she is redirected to the callback URL.
+
+
+
+## Caching the request object
+
+Client-side SDKs allow you to cache the credentials (i.e. access tokens) to not have to show the popup everytime you need the access token.
+
+
+
//Example with Twitter with the cache option enabled
+OAuth.popup('twitter', {cache: true}).done(function(twitter) {
+ //make API calls with `twitter`
+}).fail(function(err) {
+ //todo when the OAuth flow failed
+})
+
+
+
+
//Example with Twitter with the cache option enabled
+NSMutableDictionary *options = [[NSMutableDictionary alloc] init];
+[options setObject:@"true" forKey:@"cache"];
+[options setObject:@"true" forKey:@"clear-popup-cache"]; // prevents the webview from keeping cookies
+[_oauthioModal showWithProvider:@"twitter" options:options];
+
+
+### Save your user's authorization in the cache
+
+If the cache option is enabled, when the popup is called, it will directly create a request object from the cached credentials (if available) instead of showing a popup everytime the user logs in. That is to say, once the user has seen the popup once, his credentials are kept in the browser local storage for Javascript/Phonegap SDK and in the mobile with iOS and Android.
+
+
+
var twitter = OAuth.create('twitter');
+//`twitter` is a request object.
+//`twitter` can be `null` if the request object has not been created yet.
+
+
+
+
var twitter = OAuth.create('twitter');
+//`twitter` is a request object.
+//`twitter` can be `null` if the request object has not been created yet.
+
+
+### Creating a request object from Cache
+
+Once credentials have been cached, you can re-create the request object from them (later or in another page for instance).
+
+Note that you can also create a request object from existing credentials if needed.
+
+### Clearing the cache
+
+
+
//clear the cache for all providers
+[oauthioModal clearCache];
+//clear the cache for facebook
+[oauthioModal clearCacheForProvider:@"facebook"];
+
+
+
+
//clears the cache for Facebook
+OAuth.clearCache('facebook');
+//removes cache for all providers
+OAuth.clearCache();
+
+
+You can of course partially or totally remove the cache generated by OAuth.io. Note that it can be used when you want to logout your users to be sure it will open the popup the next time they try to login.
+
+# Token API - Server side
+
+The server side authorization is mostly used to get a refresh token and perform actions on behalf of your user when they are not online and connected on your website / app (for instance, crawl your user's feed and update it everyday even if the user is not connected).
+
+## Configuration
+
+In the same way as for the client-side authorization, you need to add a provider to your OAuth.io app and copy paste your provider's API keys. But this time, you have to select a backend in your oauth.io app. This way, only server side authorization will be allowed.
+
+You can also set the both mode to get a copy of the access_token client side too (and use all of the results method).
+
+## Simple server-side authorization
+
+
+//Syntaxe
+//in the Authorize endpoint
+$oauth->redirect(provider, urlToRedirect);
+
+//in the Redirect endpoint
+$oauth->auth(provider, array('redirect' => true));
+
+
+// Exemple with Google (using ZendFramwork, Controller /oauth)
+// Action /signin (url: /oauth/authorize)
+public function signinAction() {
+ try {
+ $this->oauth->redirect('google', '/oauth/redirect');
+ } catch (\Exception $e) {
+ echo $e->getMessage();
+ }
+}
+
+// Action /redirect (url: /oauth/redirect)
+public function redirectAction() {
+ try {
+ $request_object = $this->oauth->auth('google', array(
+ 'redirect' => true
+ ));
+ } catch (\Exception $e) {
+ die($e->getMessage());
+ }
+ //Your user is authorized by Google
+ //You can use $request_object to make API calls on behalf of your user
+}
+
+
+
+<!-- In your html -->
+<a href="http://github.com/oauth/signin"></a>
+
+
+
+
+
This feature is not supported by this SDK
+
+
+This method is the simplest way to achieve a server-side authorization.
+
+You need to define 2 endpoints:
+
+- the first endpoint (`authorizeEndpoint`) is where you will redirect your users to authorize them to one of our 120+ OAuth `provider`
+
+- then they will be redirected to the second endpoint (`redirectEndpoint`) with the `result` of the authorization in the callback.
+
+In the HTML of your webapp, you just have to create a link to the first endpoint to start the authorization flow `Signin`
+
+If an error occured, the error is placed in the `result`.
+
+
+
+## Authorizing the user with both front-end and back-end SDKs
+
+
+
+This method is a bit longer than the redirect one but can be used by any backend. This can be done in 3 steps:
+
+
+// Example with Zend - /state action, called from the frontend
+// to get a code
+public function tokenAction() {
+
+ // This generates a token and stores it in the session
+ $token = $this->oauth->generateStateToken();
+
+ $array = array(
+ 'token' => $token
+ );
+ $json = new JsonModel($array);
+ return $json;
+}
+
+
+
+* Generating a state token in your backend. Basically, it generates a unique id, stores it in session and sends it to the front.
+
+
+
POST https://oauth.io/auth/access_token
+Body:
+ code=ePLi3...EQfdq
+ key=public_key
+ secret=secret_key
+
+
+* Finally, from your backend, send the code to OAuth.io to get the access_token and refresh_token. OAuth.io will also send back the state token that you have to manually check. It must be the same state token as the one stored in session in the 1st step -- **This is automatically done using a server-side SDK**.
+
+## Request object from session
+
+
+
This feature is not supported by this SDK
+
+
+
+
OAuth.auth('facebook', req.session)
+ .then(function (request_object) {
+ // call endpoints with request_object here, or save it for later use
+ });
+});
+
+
+
+
+// Uses the $_SESSION array by default
+$request_object = $this->oauth->auth('facebook');
+
+
+// Note that you can specify another session array at initialization, for example:
+$_SESSION['some_array'] = array();
+$oauth->setSession($_SESSION['some_array']);
+// Beware, the array is passed by reference, so you need to have a real grasp on the stored array
+
+
+
+Once a user has been authorized by a provider, he is stored in session by the SDK. This means you can recreate the request object from the session. If the request object has an `expires_in` field and the access token has expired, the SDK will automatically refresh the `access_token`.
+
+## Building a request object from saved credentials
+
+
+
+// Retrieve the credentials and save them
+$credentials = $old_request_object->getCredentials();
+
+// Later use these credentials to rebuild the request_object object
+$new_request_object = $oauth->auth('twitter', array(
+ 'credentials' => $credentials
+));
+
+
+
+
+
+// Retrieve the credentials and save them
+var credentials = request_object.getCredentials();
+
+// Later use these credentials to rebuild the request_object object
+request_object = oauth.auth('twitter', {
+ credentials: credentials
+});
+
+
+
+
+
Not available for this SDK
+
+
+For back end SDKs you can to rebuild the request object after having saved the credentials (set of access token, refresh tokens, etc.) manually.
+
+## Refreshing the tokens
+
+
+
# Using a backend
+https://oauth.io/auth/refresh_token/:provider
+Body:
+ token: REFRESH_TOKEN
+ key: PUBLIC_OAUTHIO_KEY
+ secret: SECRET_OAUTHIO_KEY
//or from session
+OAuth.auth('facebook', req.session, {
+ force_refresh: true
+})
+
+
+
+
+ // The auth method automatically refreshes the tokens if needed
+ $request_object = $oauth->auth('facebook', array(
+ 'credentials' => $credentials
+ ));
+
+
+
+For most providers, the server side authorization sends back a refresh token without any specific configuration. The refresh token is added to the result on a server-side authorization only.
+
+This refresh token can be used when an access token expires to regenerate one without having to open a popup and ask your user for permissions (as the user has already accepted them).
+
+In all our server-side SDK, a method is available to manually refresh the access token. It gives back a new request object containing a fresh access token.
+
+For the Google provider, it's a bit more complex. To get a refresh token, please follow this Stackoverflow link: [http://stackoverflow.com/questions/23759138/getting-refresh-tokens-from-google-with-oauth-io](http://stackoverflow.com/questions/23759138/getting-refresh-tokens-from-google-with-oauth-io)
+
+# Request objects
+
+
with Google using the server side flow with a frontend SDK
+{
+ "code": "XsrpW...leE3",
+ "provider": "google"
+}
+
with Github using the server side flow in a backend SDK
+{
+ "provider": "github",
+ "access_token": "akpWg0...QEof",
+ "refresh_token": "HvOiruf...Zriv",
+ "expires_in": 5183561
+}
+
+
+We call **request object** the result object you get after an authorization. It lets you access the tokens, expiry date etc. but also gives you simple methods to access others OAuth.io API (Make authorized API call to the provider, retrieve unified user data, and more). The request object will contains these fields:
+
+Field|Description|Type|Example value
+-----|-----------|----|-------------
+access_token|**OAuth 2** -- The authorization key to access the OAuth2 API|string|CAAHv...aAWy
+oauth_token|**OAuth 1** -- The authorization key to access the OAuth1 API|string|XVQpX...WR0K
+oauth_token_secret|**OAuth 1** -- The second authorization key to access OAuth1 API|string|PHQD2...V7xw
+expires_in|*Optional depending the provider* -- The expiration of the `access_token`|integer|5184000
+code|**Client side only** -- The code to be exchanged against the access token **server side authorization**|string|XsrpW...leE3
+refresh_token|**Server side only** -- The refresh token is used to refresh the access_token to extend the expiration.|string|Tgfgso|...Geo4e5
+provider|The provider your user is connected with|string|facebook
+
+The access token can be sent to your backend to make API calls but, you can't be sure that the access token is a real one (as the user could fake a request with a wrong access token) so you need to make a test API call and see if it returns 200 (OK) or 401 (UNAUTHORIZED).
+
+As you can see, using the client side authorization, you won't have a `refresh_token`. For this, please take a look at the `Server side authorization` section.
+
+
diff --git a/source/includes/_userdata.md b/source/includes/_userdata.md
new file mode 100644
index 00000000000..3bd1080fa36
--- /dev/null
+++ b/source/includes/_userdata.md
@@ -0,0 +1,78 @@
+
+# User Data API
+
+## Usage
+
+
+
res = OAuth.create('facebook');
+res.me().done(function(me) {
+ alert('Hello ' + me.name);
+}).fail(function(err) {
+ //todo when the OAuth flow failed
+});
+
+This API allows you to retrieve your user's data in a unified way. This means you don't have to make a bridge between APIs to retrieve user's info, all fields sent are unified and described here. Filters can be added to retrieve a subset of these unified fields.
+
+The endpoint is accessible using REST
+
+`GET https://oauth.io/auth/:provider/me`
+
+## Fields
+
+
+
+
+Field|Description|Type|Example value
+-----|-----------|----|-------------
+id|The user id -- This id is unique for a provider|string|"1234"
+name|The user's name|string|John Doe
+firstname|The user's firstname|string|John
+lastname|The user's lastname|string|Doe
+alias|The user's alias (or login)|string|john87
+email|The user's email address|string|john@doe.com
+birthdate|The user's birthday|Object|{day: 27, month: 11, year: 1987}
+gender|The user's gender. 0: male; 1: female|integer|0
+location|The user's last location|string|San Francisco
+local|The user's local|string|FR
+company|The user's company|string|Webshell
+occupation|The user's job occupation|string|developer
+raw|The unmodified provider's response with non unified field|Object|
diff --git a/source/includes/_usermanagement.md b/source/includes/_usermanagement.md
new file mode 100644
index 00000000000..ac716522470
--- /dev/null
+++ b/source/includes/_usermanagement.md
@@ -0,0 +1,427 @@
+
+# User Management API
+
+## Installation
+
+You need to click 'Enable the User Management' button in your OAuth.io dashboard in the `Users Overview` tab.
+
+
+
+
users = new OAuthUsers(oauth);
+
+
+
User.signup(data).done(function(user) {
+ //todo with `user`
+});
+
+User.signup({
+ email: 'john.doe@gmail.com',
+ password: 'St0ngP4ssw0rd!',
+ firstname: 'John',
+ lastname: 'Doe',
+ company: 'X Corp',
+ age: 47
+}).done(function(user) {
+ //here, your user is logged in
+ console.log(user.data.firstname);
+}).fail(function(err) {
+ //todo with `err`
+});
+
+
+
Hashtableinfos = new Hashtable<>();
+infos.put("firstname", "John");
+infos.put("lastname", "Doe");
+infos.put("email", "john.doe@gmail.com");
+infos.put("password", "St0ngP4ssw0rd!");
+// ...
+
+users.signup(infos, new OAuthUserCallback() {
+ @Override
+ public void onFinished() {
+ // receive your identity
+ OAuthUser id = users.getIdentity();
+ }
+
+ @Override
+ public void onError(String message) {
+ displayError(message);
+ }
+});
+
+
+### With email/password
+
+You can sign up your users using their email/password.
+
+`data` is an object that must contains:
+
+* email
+* password
+* firstname
+* lastname
+
+You can add other pieces of data if you wish (the structure is free).
+
+
+
OAuth.popup(provider).then(function(res) {
+ return User.signup(res)
+}).done(function(user) {
+ //here, your user is logged in
+ console.log(user.data.firstname);
+}).fail(function(err) {
+ //todo with `err`
+});
+
+
+
// Callback from oauth.popup
+public void onFinished(OAuthData data) {
+ if (data.status.equals("error"))
+ displayError(data.error);
+ else {
+ users.signup(data, new OAuthUserCallback() {
+ @Override
+ public void onFinished() {
+ // receive your identity
+ OAuthUser id = users.getIdentity();
+ }
+
+ @Override
+ public void onError(String message) {
+ displayError(message);
+ }
+ });
+ }
+}
+
+### With social logins
+
+You can also use the Token API to sign up your users with their social identity. `provider` is the name of a provider on OAuth.io as `facebook`, `twitter`, `google` and 100+ others.
+
+The provider needs to have the User API enabled to work properly (you can see it when you add a new provider in your OAuth.io Dashbaord).
+
+
+
// Callback from oauth.popup
+public void onFinished(OAuthData data) {
+ if (data.status.equals("error"))
+ displayError(data.error);
+ else {
+ Hashtable infos = new Hashtable<>();
+ infos.put("email", "john.doe@gmail.com");
+ // ...
+ users.signup(data, infos, new OAuthUserCallback() {
+ @Override
+ public void onFinished() {
+ // receive your identity
+ OAuthUser id = users.getIdentity();
+ }
+ @Override
+ public void onError(String message) {
+ displayError(message);
+ }
+ });
+ }
+}
+
+
+### Handling errors
+
+Some providers don't give their user's email in their API (it's the case of Twitter for instance). So, you have to ask your user for their email manually and setup the email.
+
+## Signin your users
+
+Once your user has signed up, you can log them in with their email password or with one of the social identity the user attached to their account.
+
+OAuth.io manages your user's session for you and gives a simple API to let you know if the user is still logged in or not.
+
+In this version, the session expires after 6 hours of inactivity but we are working on making this expiration configurable.
+
+
// Callback from oauth.popup
+public void onFinished(OAuthData data) {
+ if (data.status.equals("error"))
+ displayError(data.error);
+ else
+ users.signin(data, new OAuthUserCallback() {
+ @Override
+ public void onFinished() {
+ // receive your identity
+ OAuthUser id = users.getIdentity();
+ }
+
+ @Override
+ public void onError(String message) {
+ displayError(message);
+ }
+ });
+}
+
+
+### With social logins
+
+Note: For social logins, the signin and signup steps are exactly the same feature. If the user doesn't exist, it will automatically sign them up before signing them in.
+
+## Get the connected user
+
+
var user = User.getIdentity();
+
+
OAuthUser id = users.getIdentity();
+
+
+### From cache
+
+When a user logs in, we store their identity (information, providers linked etc.) in a cookie. You can access this cached version instantly using the SDK with `User.getIdentity()`.
+
+It returns the same data structure as the API version: `User.refreshIdentity()`.
+
+
+
User.refreshIdentity().done(function(user) {
+ //todo with `user`
+})
+
OAuthUser user;
+// ...
+user.refreshIdentity(new OAuthUserCallback() {
+ @Override
+ public void onFinished() {
+ // user data updated
+ }
+ @Override
+ public void onError(String message) {
+ displayError(message);
+ }
+});
+
+
+### From the API
+
+Retrieve the latest change done to your user.
+
+## Know if the user is authenticated
+
+
if (User.isLogged()) {
+ //todo with authenticated user
+}
+else {
+ //todo with unauthenticated user
+}
+
if (users.isLogged()) {
+ //todo with authenticated user
+}
+else {
+ //todo with unauthenticated user
+}
+
+This method will check if the authorization cookie has been detected in the user's browser. It returns `true` or `false`
+
+## Update your user data
+
+
var user = User.getIdentity()
+user.data.firstname = 'Thomas';
+user.data.someData = {
+ a: 42,
+ b: "some string"
+}
+user.save().done(function() {
+ //todo when saved
+}).fail(function(err) {
+ //handle `err``
+});
+
OAuthUser user = users.getIdentity();
+user.data.put("firstname", "Thomas");
+user.data.put("someData", "some string");
+user.saveIdentity(new OAuthUserCallback() {
+ @Override
+ public void onFinished() {
+ // user data saved
+ }
+
+ @Override
+ public void onError(String message) {
+ displayError(message);
+ }
+});
+
+You can update all your user's data. Once you are done, just use the `save()` method to save your changes. Fields are freely structurable so you can name them as you wish (just a few fields name are protected for our use: `_provider_*`).
+
+## Reset password (or lost password)
+
+
User.resetPassword(email).done(function() {
+ //email sent to the user containing a key
+});
+
+//then...
+User.confirmResetPassword(newPassword, key);
+
+
users.resetPassword(email, new OAuthUserCallback() {
+ @Override
+ public void onFinished() {
+ // reset email sent
+ }
+
+ @Override
+ public void onError(String message) {
+ displayError(message);
+ }
+});
+
+
+The reset flow is used when a user tries to login and can't remember their password. It will send an email to the user with a `key` (to check their identity using their email). If the user is able to input the code on another page, they can change their password using this `key`.
+
+## Change password
+
+> Coming soon
+
+This feature is not released yet but will be used to change the password of the user (this option is often in the setting page of an account). The user can use it if they knows their current password to confirm their identity.
+
+
var user = User.getIdentity();
+user.changePassword(oldPassword, newPassword);
+
+
+
+## Attach social identity to an account
+
+
var user = User.getIdentity();
+OAuth.popup('google').then(function(google) {
+ return user.addProvider(google);
+}).done(function() {
+ //provider attached
+ //Your user is now able to signin with Google
+});
+
// Callback from oauth.popup
+public void onFinished(OAuthData data) {
+ if (data.status.equals("error"))
+ displayError(data.error);
+ else {
+ OAuthUser user = users.getIdentity();
+ user.addProvider(data.provider, new OAuthUserCallback() {
+ @Override
+ public void onFinished() {
+ // provider attached
+ // Your user is now able to signin with data.provider
+ }
+
+ @Override
+ public void onError(String message) {
+ displayError(message);
+ }
+ });
+ }
+}
+
+
+You can attach a social identity to an account easily. That means at the next signin, they will be able to signin with another configured provider. This way a user can securely connect with more than one provider.
+
+## Remove social identity to an account
+
+
var user = User.getIdentity();
+user.removeProvider('google').done(function() {
+ //provider detached
+});
+
OAuthUser user = users.getIdentity();
+user.removeProvider("google", new OAuthUserCallback() {
+ @Override
+ public void onFinished() {
+ // provider detached from google
+ }
+
+ @Override
+ public void onError(String message) {
+ displayError(message);
+ }
+});
+
+
+A user can detach a social identity from their account. Once a provider is detached, the user won't be able to login with it again, they needs to re-attach it again to be able to login with it.
+
+## The list of providers attached to an account
+
+
var user = User.getIdentity();
+console.log(user.providers)
+
+
OAuthUser user = users.getIdentity();
+// providers list is available in user.providers
+
+
+### From cache
+
+When a user logs in, we store a local version of the providers list attached to their account so you can access it directly in the `user` object.
+
+
+
var user = User.getIdentity();
+user.getProviders().done(function(providers) {
+ console.log(providers);
+});
+
OAuthUser user;
+// ...
+user.getProviders(new OAuthUserCallback() {
+ @Override
+ public void onFinished() {
+ // providers list is available in user.providers
+ }
+ @Override
+ public void onError(String message) {
+ displayError(message);
+ }
+});
+
+
+### From the API
+
+You can also get this list from the API to be sure it's synchronized with the backend.
+
+## Logout
+
+
var user = User.getIdentity();
+user.logout().done(function() {
+ //todo when logout
+});
+
OAuthUser user = users.getIdentity();
+user.logout(new OAuthUserCallback() {
+ @Override
+ public void onFinished() {
+ // user is logout and their token is expired
+ }
+ @Override
+ public void onError(String message) {
+ displayError(message);
+ }
+});
+
+You can log your user out from your application using the `logout()` method. It will clear the session and the associated cache.
diff --git a/source/index.html.md b/source/index.html.md
new file mode 100644
index 00000000000..0856474c917
--- /dev/null
+++ b/source/index.html.md
@@ -0,0 +1,46 @@
+---
+title: OAuth.io API Reference
+
+language_tabs:
+- javascript: Javascript
+- objectivec: iOS
+- php: PHP
+- javascript: Node
+- java: Android
+
+toc_footers:
+- Back to OAuth.io
+- Sign Up for a Developer Key
+- Documentation Powered by Slate
+
+includes:
+- install
+- token
+- request
+- userdata
+- usermanagement
+- contribute
+search: true
+---
+
+# Introduction
+
+
+
+OAuth.io helps you to onboard your users with a suite of services easy to use.
+
+- **Token API**: Authorize your client apps on one of our [120+ OAuth provider](https://oauth.io/providers).
+
+- **Request API**: Make authorized API calls to those OAuth providers in a simple way.
+
+- **User Data API**: Get the authenticated user's unified information.
+
+- **User Management API**: Signup/signin your user without any backend using multiple social identity.
+
+
diff --git a/source/index.md b/source/index.md
deleted file mode 100644
index 401ece5fcd9..00000000000
--- a/source/index.md
+++ /dev/null
@@ -1,168 +0,0 @@
----
-title: API Reference
-
-language_tabs:
- - shell
- - ruby
- - python
-
-toc_footers:
- - Sign Up for a Developer Key
- - Documentation Powered by Slate
-
-includes:
- - errors
-
-search: true
----
-
-# Introduction
-
-Welcome to the Kittn API! You can use our API to access Kittn API endpoints, which can get information on various cats, kittens, and breeds in our database.
-
-We have language bindings in Shell, Ruby, and Python! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.
-
-This example API documentation page was created with [Slate](http://github.com/tripit/slate). Feel free to edit it and use it as a base for your own API's documentation.
-
-# Authentication
-
-> To authorize, use this code:
-
-```ruby
-require 'kittn'
-
-api = Kittn::APIClient.authorize!('meowmeowmeow')
-```
-
-```python
-import kittn
-
-api = kittn.authorize('meowmeowmeow')
-```
-
-```shell
-# With shell, you can just pass the correct header with each request
-curl "api_endpoint_here"
- -H "Authorization: meowmeowmeow"
-```
-
-> Make sure to replace `meowmeowmeow` with your API key.
-
-Kittn uses API keys to allow access to the API. You can register a new Kittn API key at our [developer portal](http://example.com/developers).
-
-Kittn expects for the API key to be included in all API requests to the server in a header that looks like the following:
-
-`Authorization: meowmeowmeow`
-
-
-
-# Kittens
-
-## Get All Kittens
-
-```ruby
-require 'kittn'
-
-api = Kittn::APIClient.authorize!('meowmeowmeow')
-api.kittens.get
-```
-
-```python
-import kittn
-
-api = kittn.authorize('meowmeowmeow')
-api.kittens.get()
-```
-
-```shell
-curl "http://example.com/api/kittens"
- -H "Authorization: meowmeowmeow"
-```
-
-> The above command returns JSON structured like this:
-
-```json
-[
- {
- "id": 1,
- "name": "Fluffums",
- "breed": "calico",
- "fluffiness": 6,
- "cuteness": 7
- },
- {
- "id": 2,
- "name": "Isis",
- "breed": "unknown",
- "fluffiness": 5,
- "cuteness": 10
- }
-]
-```
-
-This endpoint retrieves all kittens.
-
-### HTTP Request
-
-`GET http://example.com/kittens`
-
-### Query Parameters
-
-Parameter | Default | Description
---------- | ------- | -----------
-include_cats | false | If set to true, the result will also include cats.
-available | true | If set to false, the result will include kittens that have already been adopted.
-
-
-
-## Get a Specific Kitten
-
-```ruby
-require 'kittn'
-
-api = Kittn::APIClient.authorize!('meowmeowmeow')
-api.kittens.get(2)
-```
-
-```python
-import kittn
-
-api = kittn.authorize('meowmeowmeow')
-api.kittens.get(2)
-```
-
-```shell
-curl "http://example.com/api/kittens/3"
- -H "Authorization: meowmeowmeow"
-```
-
-> The above command returns JSON structured like this:
-
-```json
-{
- "id": 2,
- "name": "Isis",
- "breed": "unknown",
- "fluffiness": 5,
- "cuteness": 10
-}
-```
-
-This endpoint retrieves a specific kitten.
-
-
-
-### HTTP Request
-
-`GET http://example.com/kittens/`
-
-### URL Parameters
-
-Parameter | Description
---------- | -----------
-ID | The ID of the cat to retrieve
-
diff --git a/source/javascripts/all.js b/source/javascripts/all.js
index 534eae93090..5f5d4067ba6 100644
--- a/source/javascripts/all.js
+++ b/source/javascripts/all.js
@@ -1,2 +1,2 @@
-//= require_tree ./lib
-//= require_tree ./app
+//= require ./all_nosearch
+//= require ./app/_search
diff --git a/source/javascripts/all_nosearch.js b/source/javascripts/all_nosearch.js
index 4610cabe62d..b18c1d833d4 100644
--- a/source/javascripts/all_nosearch.js
+++ b/source/javascripts/all_nosearch.js
@@ -1,4 +1,16 @@
-//= require_tree ./lib
-//= require_tree ./app
-//= stub ./app/search.js
-//= stub ./lib/lunr.js
+//= require ./lib/_energize
+//= require ./app/_toc
+//= require ./app/_lang
+
+$(function() {
+ loadToc($('#toc'), '.toc-link', '.toc-list-h2', 10);
+ setupLanguages($('body').data('languages'));
+ $('.content').imagesLoaded( function() {
+ window.recacheHeights();
+ window.refreshToc();
+ });
+});
+
+window.onpopstate = function() {
+ activateLanguage(getLanguageFromQueryString());
+};
diff --git a/source/javascripts/app/_lang.js b/source/javascripts/app/_lang.js
new file mode 100644
index 00000000000..4dcbe49e181
--- /dev/null
+++ b/source/javascripts/app/_lang.js
@@ -0,0 +1,178 @@
+/*
+Copyright 2008-2013 Concur Technologies, Inc.
+Licensed under the Apache License, Version 2.0 (the "License"); you may
+not use this file except in compliance with the License. You may obtain
+a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+License for the specific language governing permissions and limitations
+under the License.
+*/
+;(function () {
+ 'use strict';
+
+ var languages = [];
+ var languagesHash = {}
+
+ window.setupLanguages = setupLanguages;
+ window.activateLanguage = activateLanguage;
+ window.getLanguageFromQueryString = getLanguageFromQueryString;
+
+ function activateLanguage(language) {
+ if (!language) return;
+ if (language === "") return;
+
+ console.group('Activate Language')
+ console.log('languages', languages);
+ console.log('language', language);
+ console.groupEnd();
+
+ $(".lang-selector a").removeClass('active');
+ $(".lang-selector a[data-language-id='" + language + "']").addClass('active');
+ for (var i=0; i < languages.length; i++) {
+ $(".code-block." + languages[i]).hide();
+ }
+ $(".code-block." + language).show();
+
+ // scroll to the new location of the position
+ if ($(window.location.hash).get(0)) {
+ $(window.location.hash).get(0).scrollIntoView(true);
+ }
+ }
+
+ // parseURL and stringifyURL are from https://github.com/sindresorhus/query-string
+ // MIT licensed
+ // https://github.com/sindresorhus/query-string/blob/7bee64c16f2da1a326579e96977b9227bf6da9e6/license
+ function parseURL(str) {
+ if (typeof str !== 'string') {
+ return {};
+ }
+
+ str = str.trim().replace(/^(\?|#|&)/, '');
+
+ if (!str) {
+ return {};
+ }
+
+ return str.split('&').reduce(function (ret, param) {
+ var parts = param.replace(/\+/g, ' ').split('=');
+ var key = parts[0];
+ var val = parts[1];
+
+ key = decodeURIComponent(key);
+ // missing `=` should be `null`:
+ // http://w3.org/TR/2012/WD-url-20120524/#collect-url-parameters
+ val = val === undefined ? null : decodeURIComponent(val);
+
+ if (!ret.hasOwnProperty(key)) {
+ ret[key] = val;
+ } else if (Array.isArray(ret[key])) {
+ ret[key].push(val);
+ } else {
+ ret[key] = [ret[key], val];
+ }
+
+ return ret;
+ }, {});
+ };
+
+ function stringifyURL(obj) {
+ return obj ? Object.keys(obj).sort().map(function (key) {
+ var val = obj[key];
+
+ if (Array.isArray(val)) {
+ return val.sort().map(function (val2) {
+ return encodeURIComponent(key) + '=' + encodeURIComponent(val2);
+ }).join('&');
+ }
+
+ return encodeURIComponent(key) + '=' + encodeURIComponent(val);
+ }).join('&') : '';
+ };
+
+ // gets the language set in the query string
+ function getLanguageFromQueryString() {
+ if (location.search.length >= 1) {
+ var language = parseURL(location.search).language;
+ if (language) {
+ return language;
+ } else if (jQuery.inArray(location.search.substr(1), languages) != -1) {
+ return location.search.substr(1);
+ }
+ }
+
+ return false;
+ }
+
+ // returns a new query string with the new language in it
+ function generateNewQueryString(language) {
+ var url = parseURL(location.search);
+ if (url.language) {
+ url.language = language;
+ return stringifyURL(url);
+ }
+ return language;
+ }
+
+ // if a button is clicked, add the state to the history
+ function pushURL(language) {
+ if (!history) { return; }
+ var hash = window.location.hash;
+ if (hash) {
+ hash = hash.replace(/^#+/, '');
+ }
+ history.pushState({}, '', '?' + generateNewQueryString(language) + '#' + hash);
+
+ // save language as next default
+ localStorage.setItem("language", language);
+ }
+
+
+ function setupLanguages(l) {
+ console.log(l);
+ for (var i in l) {
+ languagesHash[Object.keys(l[i])[0]] = l[i][Object.keys(l[i])[0]];
+ languages.push(l[i][Object.keys(l[i])[0]]);
+ }
+
+ var currentLanguage = languages[0];
+ var defaultLanguage = localStorage.getItem("language");
+
+ console.log(languages, languagesHash, currentLanguage, defaultLanguage);
+
+ if ((location.search.substr(1) !== "") && (jQuery.inArray(location.search.substr(1), languages)) != -1) {
+ // the language is in the URL, so use that language!
+ console.log('in the list');
+ activateLanguage(location.search.substr(1));
+
+ localStorage.setItem("language", location.search.substr(1));
+ } else if ((defaultLanguage !== null) && (jQuery.inArray(defaultLanguage, languages) != -1)) {
+ // the language was the last selected one saved in localstorage, so use that language!
+ console.log("in localstorage");
+ activateLanguage(defaultLanguage);
+ } else {
+ // no language selected, so use the default
+ console.log("no language in localstorage, using default language");
+ activateLanguage(languages[0]);
+ }
+ }
+
+ // if we click on a language tab, activate that language
+ $(function() {
+ $('.code-block pre code').each(function(i, block) {
+ hljs.highlightBlock(block);
+ });
+ $(".lang-selector a").on("click", function() {
+ var language = $(this).data("language-name");
+ var languageId = $(this).data("language-id");
+ pushURL(languageId);
+ activateLanguage(languageId);
+ return false;
+ });
+ window.onpopstate = function(event) {
+ activateLanguage(window.location.search.substr(1));
+ };
+ });
+})(window);
\ No newline at end of file
diff --git a/source/javascripts/app/search.js b/source/javascripts/app/_search.js
similarity index 53%
rename from source/javascripts/app/search.js
rename to source/javascripts/app/_search.js
index 8c527c715da..9ff4233c18a 100644
--- a/source/javascripts/app/search.js
+++ b/source/javascripts/app/_search.js
@@ -1,8 +1,13 @@
-(function (global) {
+//= require ../lib/_lunr
+//= require ../lib/_jquery
+//= require ../lib/_jquery.highlight
+;(function () {
+ 'use strict';
- var $global = $(global);
- var content, darkBox, searchResults;
+ var content, searchResults;
var highlightOpts = { element: 'span', className: 'search-highlight' };
+ var searchDelay = 0;
+ var timeoutHandle = 0;
var index = new lunr.Index();
@@ -24,37 +29,57 @@
body: body.text()
});
});
+
+ determineSearchDelay();
+ }
+ function determineSearchDelay() {
+ if(index.tokenStore.length>5000) {
+ searchDelay = 300;
+ }
}
function bind() {
content = $('.content');
- darkBox = $('.dark-box');
searchResults = $('.search-results');
- $('#input-search').on('keyup', search);
+ $('#input-search').on('keyup',function(e) {
+ var wait = function() {
+ return function(executingFunction, waitTime){
+ clearTimeout(timeoutHandle);
+ timeoutHandle = setTimeout(executingFunction, waitTime);
+ };
+ }();
+ wait(function(){
+ search(e);
+ }, searchDelay );
+ });
}
function search(event) {
+
+ var searchInput = $('#input-search')[0];
+
unhighlight();
searchResults.addClass('visible');
// ESC clears the field
- if (event.keyCode === 27) this.value = '';
+ if (event.keyCode === 27) searchInput.value = '';
- if (this.value) {
- var results = index.search(this.value).filter(function(r) {
+ if (searchInput.value) {
+ var results = index.search(searchInput.value).filter(function(r) {
return r.score > 0.0001;
});
if (results.length) {
searchResults.empty();
$.each(results, function (index, result) {
- searchResults.append("
+ 
+
-
-*The example above was created with Slate. Check it out at [tripit.github.io/slate](http://tripit.github.io/slate).*
+