Ably Documentation

Ably is the platform that powers synchronized digital experiences in realtime. Whether attending an event in a virtual venue, receiving realtime financial information, or monitoring live car performance data – consumers simply expect realtime digital experiences as standard. Ably provides a suite of APIs to build, extend, and deliver powerful digital experiences in realtime for more than 250 million devices across 80 countries each month. Organizations like Bloomberg, HubSpot, Verizon, and Hopin depend on Ably’s platform to offload the growing complexity of business-critical realtime data synchronization at global scale.

This repository contains Ably's documentation, which is visible in two locations:

• https://docs.ably.com: A static site which always reflects the latest version of the contents of this repository, being deployed automatically when the main branch is updated.
• https://ably.com/docs: Our official documentation, which points to a specific version of this repository. Changes in this repo are not automatically reflected in the official docs, but require intervention by the Ably website team.

Docs are authored in Textile and rendered using the Ruby-based Nanoc static site generator.

Note: The instructions on this page are intended for general users. If you are a member of Ably staff there is more specific information in the internal README.

Quickstart

To run the static site locally, perform the following steps:

1. Clone or fork this repo
2. Run bundle install to install the required dependencies
3. Execute bundle exec nanoc live -p 4000
4. Visit https://localhost:4000 in your web browser. Any changes you make to the docs should update the static site automatically.

Note: The Ruby version required is shown in the .ruby-version file. If you use ASDF or compatible tooling to manage your Ruby runtime versions, we have included a .tool-versions file.

Contributing to the Docs

We welcome contributions to our documentation. The following resources will help you:

• Writing Style Guide
• Documentation Formatting Guide.

To contribute:

1. Make your changes on a local feature branch.
2. Commit your changes and push your branch.
3. Create a pull request (PR) that summarizes what changes you are proposing and why.
4. The pull request will automatically deploy your changes to a review site that is linked to at the bottom of the PR.
5. The Ably team will review your PR and might suggest changes and improvements that should be made before your PR can be merged. You can make further commits at this stage and the review site will update to reflect them.

Running with Docker

Execute the following command:

• docker-compose up

This starts a web server at http://localhost:4000, builds the static site and allows you to view changes live*.

Notes:

• This has been tested with Docker version 2.10.7. See Docker installation instructions.
• If you are running on Windows you will need to re-run the docker-compose up command to see your changes in the static site, unless you are using WSL.

Managing updated dependencies

Occasionally, the Gemfile or Gemfile.lock files might change and this will cause docker-compose to fail with an error similar to this:

webserver_1  | The Gemfile built for this container does not match the current Gemfile i.e. they have changed
webserver_1  | You must rebuild the container with: $ ./docker-run build
docs_webserver_1 exited with code 2

When this happens, you need to rebuild the containers by running docker-compose up --build.

Running on Heroku

This repo will automatically run on Heroku, but relies on the following buildpacks:

$ heroku buildpacks
=== ably-docs Buildpack URLs
1. https://github.com/heroku/heroku-buildpack-ruby
2. https://github.com/ably-forks/heroku-buildpack-nanoc
3. https://github.com/heroku/heroku-buildpack-static

Redirects

Redirects are implemented using the nanoc-redirector Ruby gem.

To set up a redirect, add the following to the frontmatter of the page that you want to be the destination of the redirect:

redirect_from:
  - /redirect-from-this-path/

Then, when you access /redirect-from-this-path/, you are redirected to the destination page.

IMPORTANT: Do not include the file extension in the redirect_from URLs list. For example:

• general/versions/v0.8/webhooks ✅ Correct!
• general/versions/v0.8/webhooks.textile ❌ Incorrect!

Updating the redirects YAML file

The website uses the redirects YAML file to handle redirects in the documentation. After configuring a redirect, execute one of the following (depending on how you are running the site) to update redirects.yaml:

Local install

$ bundle exec nanoc compile

Docker

docker-compose up

Help and contact

If you have any questions or suggestions, please get in touch.