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 is a static site generated using Gatsby and documentation written in:
Textile - Held in the ./content folders, enhanced with certain additional features described in ./content/client-lib-development-guide/documentation-formatting-guide.textile
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.
Install node & yarn.
If you use ASDF or compatible tooling to manage your Ruby runtime versions, we have included a .tool-versions
file - where the dependencies within can be installed with asdf install
from the project root.
At the time of writing, this project requires Ruby 3.0.0, which in turn requires openssl@1.1
. Environments with different versions (i.e. openssl@3
) may experience a failing Ruby install, in which case you can do the following (and if this fails, uninstall @openssl@X
first):
brew install openssl@1.1
RUBY_CONFIGURE_OPTS="--with-openssl-dir=$(brew --prefix openssl@1.1)" asdf install ruby
yarn
If Gatsby CLI is not already installed:
yarn global add gatsby-cli
Environment variables setup
If you have not yet set up your local .env.development environment variables, run:
yarn develop:env-setup
Editors:
yarn edit
Developers:
To develop locally run:
yarn develop
Visit localhost:8000
for homepage.
Visit localhost:8000/docs/${relativePath}
for documentation pages, e.g. localhost:8000/docs/client-lib-development-guide/documentation-formatting-guide
.
To build and serve locally:
yarn rebuild
Visit localhost:8000
for homepage.
Redirects are currently implemented using Gatsby's in-built redirect functionality.
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/
You can also add a single redirect, however while this is supported it is not the principal way to add redirects; adding a YAML array, as shown above, is the most stable and predictable way to add a redirect.
redirect_from: /redirect-from-this-single-path/
If a redirect is not already prepended with /docs
, /docs
will be prepended to the redirect source URL; if you need a redirect from the main website to a docs page, Gatsby currently cannot handle this.
Otherwise, the redirect will be left intact.
Redirects added in this way are also added to a file at ./config/nginx-redirects.conf
, and used to create a map of nginx redirects at build time.
Other one-off instances of redirects may be added to additional config files, and imported in a similar way. See:
./config/website-redirects.conf
./config/client-lib-development-guide-redirects.conf
./config/nginx.conf.erb
For how to create and include these redirects.
Wherever possible, images should live in src/images
and not in static/images
. The authors of Gatsby recommend importing images into components. The static
folder in Gatsby is an escape hatch for the rare cases where files cannot be imported.
The benefit of sticking to the Gatsby approach is that our images get processed and optimized during build time. It also allows us to serve our images over a CDN which is much better for our users.
Images in components can be imported and rendered as follows:
import myImage from 'src/path/to/my-image.png';
export default Component => (<img src={myImage} />);
TBD
For rendering images in Textfile we have a special convention.
Firstly, place the image file in src/images/content
. The in the textile files reference it with a special path @content
, for example:
<img src="https://github.com/ably/docs/raw/main/@content/path/to/image.png" />
The above will render the image at src/images/content/path/to/image.png
.
Content images in textile is powered by ContentImagesProvider
and useContentImages
. Templates rendering content need to add the following to their GraphQL queries to get all the images loaded before passing it to the ContentImagesProvider
:
images: allFile(filter: { relativeDirectory: { glob: "content/**" } }) {
nodes {
...ContentImage
}
}
Note that any env variables needed to show in the browser must be prefixed with GATSBY_
in order to appear.
GATSBY_ABLY_MAIN_WEBSITE
can also be changed to point to staging or a local running website instance.
Place these in .env.development to run locally.
Documentation is included throughout this repository in the form of README.md files at folder level. These are intended to:
We have selected folder-level README files instead of the alternative of a dedicated documentation folder because we think it enables points 1
and 4
more directly, especially with the support from GitHub. The aim is to make browsing the repository much more clear even if you have no context for the repository.
If you would like to run linting and tests automatically before every commit and run yarn install automatically after every branch checkout, run yarn repo-githooks
. If you would like to remove this behaviour, run yarn no-githooks
.
To understand the data ingestion and parsing steps, please check the READMEs in the /data folder.
If you have any questions or suggestions, please get in touch.