ArangoDB Documentation

This is the ArangoDB documentation repository containing all documentation for all versions as published on arangodb.com/docs/.

The documentation uses the static site generator Jekyll.

View the latest successful preview build of the main branch.

Contributing

To suggest a concrete change to the documentation, you may edit files directly on GitHub. It will fork the repository automatically if necessary. Commit the changes to a new branch, give it a succinct name, and open a pull request (PR).

To add more changes to a PR, click on the branch name below the headline of the PR (the latter link of "<User> wants to merge <n> commits into main from branch-name"). Then locate and edit the next file. Commit the changes directly to your PR branch.

For general suggestions, feel free to create an issue.

Automatic Previews

In every pull request, there is a number of so-called checks (above the text field for entering a comment). The last entry should be netlify/zealous-morse-14392b/deploy-preview with a Details link. Whenever you push a change to the PR branch, Netlify will build a preview. While it is doing that or if it fails building the docs, then the Details link will get you to the build log. If it succeeded, then it gets you to the hosted preview of that PR. If no checks show up at all, then Netlify is probably busy with another build (or down). The checks should eventually appear, however.

Contributor License Agreement

To accept external contributions, we need you to fill out and sign our Contributor License Agreement (CLA). We use an Apache 2 CLA for ArangoDB, which can be found here: https://www.arangodb.com/documents/cla.pdf You can scan and email the CLA PDF file to cla@arangodb.com or send it via fax to +49-221-2722999-88.

Building the Documentation

The following section describes how you can build the documentation locally. This is not strictly necessary when contributing. You can also rely on automatic previews.

Symlink Support Required

Make sure that symlink support is enabled before you clone the repository with Git. It is turned off by default in Git for Windows. Start a terminal as administrator and run:

git config --system core.symlinks true

Options for Building

To work locally on the documentation you can:

• install Jekyll and dependencies
• or use the Docker container arangodb/arangodb-docs

Docker is generally easier, but may also be slower (at least under Windows).

Note that the Algolia plugin has a dependency which does not support Ruby 2.6+.

Jekyll

If you want to build the docs the first time, run bundle install to ensure that all dependencies (gems / plugins) are installed.

For local development, start Jekyll in watch mode:

bundle exec jekyll serve

This will build the documentation, rebuild it if you change files, and serve the documentation site locally using Jekyll's built-in web server.

You can then browse the docs in a browser at http://127.0.0.1:4000/docs/stable/. Note that it has to be /docs/stable/ (or another version than stable). Both paths / and /docs do not work (404 Page not found) because of the configured baseurl in _config.yml, and /docs/ redirects you to the online version of the documentation.

To let Jekyll build the static site without serving it or watching for file changes, use:

bundle exec jekyll build

The generated content will be stored in the _site/docs/ folder.

To serve the content from a previous build without watching for changes, use:

bundle exec jekyll serve --skip-initial-build --no-watch

Docker Container

In the docs directory, execute:

docker run --rm -v $(pwd):/docs -p 4000:4000 arangodb/arangodb-docs

This will watch for file changes and you will be able to see the resulting static site on http://127.0.0.1:4000/docs/stable/.

Note that Jekyll's --incremental build option is enabled. In addition, DocuBlocks are parsed once per invocation and then cached in memory. If you encounter stale content, then stop the container and run:

docker run --rm -v $(pwd):/docs -p 4000:4000 arangodb/arangodb-docs bundler exec jekyll serve -H 0.0.0.0 --trace

Alternatively, you may stop the container, execute either of the following commands, and run the normal Docker command again (without additional arguments).

• rm -rf .jekyll-cache/ .jekyll-metadata _site/
• docker run --rm -v $(pwd):/docs arangodb/arangodb-docs bundler exec jekyll clean

To build the documentation without watch mode or serving the resulting site, you can execute:

docker run --rm -v $(pwd):/docs arangodb/arangodb-docs bundler exec jekyll build --trace

After that the HTML files in _site/ are ready to be served by a webserver:

cd _site
python3 -m http.server

To check for broken references (e.g. internal links), you can run htmltest:

docker run --rm -v $(pwd):/docs arangodb/arangodb-docs htmltest

Performance

A full build (all versions) will take quite a while. You can use Jekyll's watch mode to let it continuously rebuild the pages you change after an initial build. For simple documentation changes this process normally works perfect.

However there are cases where Jekyll won't detect changes. This is especially true when changing plugins and configuration (including the navigation YAML when adding a new page). To be sure you have an up-to-date version remove the _site directory and then abort and restart the watch mode.

To speed up the build process you may disable certain versions from being built by changing the _config.yml:

exclude:
# - 3.12/
# - 3.11/
# - 3.10/
  - 3.9/
  - 3.8/

Above example disables versions 3.8 and 3.9, so that only 3.10 through 3.12 are built. Do not commit these changes of the configuration!

Note that building may fail if you disable certain versions that contain the files that other versions refer to with symlinks, or required versions as defined in _config.yml:

versions:
  stable: "3.8"
  devel: "3.9"

Documentation Structure

Versions

In the root directory, the directories 3.8, 3.9 etc. represent the individual ArangoDB versions and their documentation. We only maintain one version of the documentation for every minor and major version (3.9, 4.0, etc.) but not for every patch release (e.g. 3.8.2).

The content for different documentation versions used to be in version branches (2.7, devel, etc.) in the arangodb/arangodb repository, but now all documentation versions live in the main branch of this repository. This has the advantage that all versions can be built at once, but the drawback of Git cherry-picking not being available and therefore requiring to manually apply changes to different versions as necessary (copy-pasting text or files).

Books (Parts)

The documentation is split into different parts, called "books" for historical reasons. The core book (Manual) of a version does not have an own folder for its content, but the files are found in the version directory, e.g. 3.8/*.md. Other books (AQL, HTTP) have subfolders in the version folder, e.g. 3.8/aql/.

There are also books (Drivers, ArangoGraph) that are not directly couple to ArangoDB versions, that have their files in an own folders in the root directory, e.g. arangograph/*.md. These folders are symlinked in multiple version folders. Some files, like release notes, are also symlinked to reduce maintenance costs.

The organization of documents is flat, namely there are no subdirectories per book (as opposed to the previous documentation system). For example, all files of the AQL part are in the aql/ folder. It does not have any subfolders like aql/examples/. Instead, the file name reflects which files belong together, e.g. aql/examples-counting.md.

Special Folders

Content folders aside, there are the following other directories:

| Name | Description |:------------|:----------- | _data | data files which are used by plugins and layouts, including the navigation definitions | _includes | templates for custom tags and layout partials | _layouts | layout definitions that can be used in YAML frontmatter like layout: default | _plugins | Jekyll extensions for the navigation, version switcher, custom tags / blocks etc. | _site | default output directory (not committed) | assets | files not directly related to the documentation content that also need to be served (e.g. the ArangoDB logo) | js | JavaScript files used by the documentation site | scripts | Scripts which were used in the migration process from Gitbook to Jekyll (not really needed anymore) | styles | CSS files for the site, including a lot of legacy from Gitbook

Working with the Documentation Content

Markup Overview

The documentation is written in the light-weight markup language Markdown. There are different flavors of Markdown and it is further extended by Liquid, Jekyll's templating language, as well as our own customization.

Below is a list of the most commonly used markup, and an approximation of how it gets rendered:

<table> <thead> <tr> <th align="left">Element</th> <th align="left">Markdown</th> <th align="left">Preview</th> <th align="left">HTML</th> </tr> </thead> <tbody> <tr> <td>Text line</td> <td><pre><cod