Repository files navigation

This repository contains the source files of the Arango documentation aspublished ondocs.arango.ai.

The Arango documentation is licensed under Apache-2.0.SeeLICENSE for details.

To suggest a concrete change to the documentation, you mayedit files directly on GitHub.It will fork the repository automatically if necessary. Commit the changes to anew 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 headlineof the PR (the latter link of "<User> wants to merge <n> commitsintomain frombranch-name"). Then locate and edit the next file.Commit the changes directly to your PR branch.

For general suggestions, feel free tocreate an issue.

In every pull request, thearangodb-docs-automation bot comments with a deploypreview link. Whenever you push a change to the PR branch, a preview is built.If it succeeds, then you can view the preview hosted on Netlify by followingthe link.

Note that the automatic previews runplain builds, which meansthatgenerated content is not updated. The Arangodocumentation team takes of regenerating this content if necessary.

To accept external contributions, we need you to fill out and sign ourContributor License Agreement (CLA):

• Individual Contributor License Agreement
• Corporate Contributor License Agreement

You can scan and email the CLA PDF file tocla@arango.ai or send it viafax to +49-221-2722999-88.

The following section describes how you can build the documentation locally.This is not strictly necessary when contributing. You can also rely onautomatic previews for basic changes.

At the core, docs are generated with the static site generatorHugo. Thehugo build command generates static HTMLcontent from the Markdown, data, and theme files.

The documentation toolchain is containerized and uses Docker Compose toorchestrate builds. The following containers are created:

• toolchain - contains the code for controlling the toolchain and thegenerated content, spawning the other containers
• docs_arangoproxy - contains the arangoproxy web server written in Go thathandles generated content using arangosh to run examples against a server andassemble the OpenAPI descriptions
• docs_site - contains Hugo and the logic to start it
• docs_server_<version> - an ArangoDB single server
• docs_server_<version>_cluster - an ArangoDB cluster

For headlines, links, images, and fenced code blocks in Markdown, Hugo can runtemplate files that are calledRender Hooks to trigger special processing.This is used to extract and execute examples against actual ArangoDB servers andplace the output into the rendered documentation, for example.

• Heading render hook

  Defined insite/themes/arangodb-docs-theme/layouts/_default/_markup/render-heading.html

  Checks that there is no level 1# Headline in the content, as this isreserved for thetitle defined in the front matter. Also injects the widgetto copy anchor links to the clipboard.

• Link render hook

  Defined insite/themes/arangodb-docs-theme/layouts/_default/_markup/render-link.html

  Scans all the hrefs in a file and tries to retrieve the page from that link.If the page is not found, the build fails because of a broken link.

• Image render hook

  Defined insite/themes/arangodb-docs-theme/layouts/_default/_markup/render-image.html

  Transforms the style attributes defined in the image link as{path.png?{attribute1=value1&attribute2=value2&..}} in a style attributeinside theimg HTML tag.

• Codeblock render hook

  Defined insite/themes/arangodb-docs-theme/layouts/_default/_markup/render-codeblock-*.html

  Triggers a remote call to thearangoproxy web server for assembling theOpenAPI descriptions as well as to run the example generation if the codestarts with a front matter block surrounded by---, like this:

  ```aql---name: the_answerdescription: AQL block with front matter---RETURN 42```

  The following codeblocks are supported:

  • ```js for arangosh / JavaScript API examples
  • ```aql for AQL query examples
  • ```openapi for REST HTTP API descriptions
  • ```curl for REST HTTP API examples

The hooks trigger aPOST call to the dedicatedarangoproxy endpoint(/js,/aql,/curl,openapi) with the entire codeblock as request body.

Thearangoproxy endpoint parses the request, checks if the examples is cached,otherwise executes the code against the ArangoDB instance with the version asdetermined from the version folder name and saves the example output in the cache.

The input/output (as defined in the YAML render option) is returned as JSON toHugo in the render hook, which generates HTML replacing the codeblock in thefile with the input/output of the example.

The following build workflows exist:

• Plain build workflow

  Build docs without re-generating examples (using a committed cache file).

  Includes the assembly of the REST HTTP API descriptions (OpenAPI) withvalidation at each run.```curl examples require a different workflow.

  You may need to specify upstream branches.

• Scheduled workflow

  The following generated content is re-generated periodically using CircleCI:

  • Metrics
  • Error codes and meanings
  • AQL optimizer rules
  • Startup options
  • oasisctl documentation

• Example generation workflow

  Build docs including re-generating examples for AQL, arangosh (JavaScript API),and cURL (HTTP API).

  Specifying upstream branches is required for all versions in which you modifiedexample code and thus require a re-generation. These can be a Docker Hub imagesor GitHub pull request links.

Go to thetoolchain/docker/<architecture> folder, with<architecture> beingeitheramd64 for x86-64 CPUs andarm64 for 64-bit ARM CPUs (includingApple silicon like M1).

Run thedocker compose services using thedocker-compose.pain-build.yml file.

docs-hugo/toolchain/docker/amd64> docker compose -f docker-compose.plain-build.yml up --abort-on-container-exit

The site will be available athttp://localhost:1313.

To make the documentation tooling not start a live server in watch mode butrather create a static build and exit, set the environment variableENV toany value other thanlocal before callingdocker compose ...:

export ENV=static# Bashset -xg ENV static# Fish$Env:ENV='static'# PowerShell

The output files will be written tosite/public/.

Configuration

The toolchain container needs to be set up via config file intoolchain/docker/config.yaml:

generators:# Generators to trigger - empty string defaults to all generatorsservers:# Array to define arangodb servers to be used by the toolchain  -image:# arangodb docker image to be used, can be arangodb/enterprise-preview:... or a branch nameversion:# docs branch to put the generated content into  -...# Additional images and versions as needed

Available generators

• examples
• metrics
• error-codes
• exit-codes
• optimizer
• options
• oasisctl

The generators entry is a space-separated string.

Ifmetrics,error-codes, orexit-coddes is in thegenerators string,the following environment variable has to be exported:

export ARANGODB_SRC_{VERSION}=path/to/arangodb/source

Substitute{VERSION} with a version number like3_11.

On Windows using PowerShell, use a Unix-like path:

$Env:ARANGODB_SRC_3_11="/Drive/path/to/arangodb"

Configuration example

generators:examples oasisctl options optimizerservers:  -image:arangodb/enterprise-preview:3.11-nightlyversion:"3.11"  -image:arangodb/enterprise-preview:devel-nightlyversion:"3.12"

Run the toolchain

Go to thetoolchain/docker/<architecture> folder, with<architecture> beingeitheramd64 for x86-64 CPUs andarm64 for 64-bit ARM CPUs (includingApple silicon like M1).

Run thedocker compose services without specifying a file:

docs-hugo/toolchain/docker/arm64> docker compose up --abort-on-container-exit

The site will be available athttp://localhost:1313

In thesite/content directory, the directories3.10,3.11 etc. representthe individual ArangoDB versions and their documentation. There is only onemaintained version of the documentation for every minor and major version (3.12,4.0, etc.) but not for every patch release (e.g. 3.12.1).

Having a folder per version has the advantage that all versions can be built atonce, but the drawback of Git cherry-picking not being available and thereforerequiring to manually apply changes to different versions as necessary.

• site/ - Folder with all files that Hugo needs to generate the site
  • config/ - The base Hugo configuration in_default/ as well as additionalconfigurations for different build workflows
  • content/ - The Markdown source files in version folders as well as ashared folder for images
  • data/ - Contains JSON and YAML files for the documentation versions,the OpenAPI tag list, the example cache, etc.
  • public/ - Default output directory for the generated site (not committed)
  • resources/ - Holds the various cached resources that are generated by Hugowhen usinghugo serve
  • themes/ - Folder for Hugo themes, containing the customized Arango docs theme
• toolchain/ - Folder for the docs toolchain tools and scripts
  • arangoproxy/ - Source code of the arangoproxy web server
  • docker/ - The Docker container and compose files, with two sets ofconfigurations for theamd64 andarm64 architectures that are needed forthe scheduled and example generation build workflows
  • scripts/ - The toolchain scripts

The documentation is written in the light-weight markup languageMarkdown, using the GitHubflavor, and further extended by Hugoshortcodes for advanced templating needs.

For an overview over the basic markup, see theCommonMark help.

The following extensions are available:

You can use admonitions for hints and callouts that render in a colored box withan icon, highlighting useful or important information.

{{< danger >}}Critical information to prevent data loss or similarly impactful events.{{< /danger >}}

{{< warning >}}Be careful and mind restrictions to avoid issues.{{< /warning >}}

{{< security >}}Mind this information to keep the system and your data safe.{{< /security >}}

{{< info >}}Helpful information to have.{{< /info >}}

{{< tip >}}Follow best practices and utilize features to set yourself up for success.{{< /tip >}}

Admonitions can also be used indescription fields inside of```openapicode blocks but the syntax then needs to be like this:

```openapipaths:  /_api/endpoint:    post:      description: |        {{</* warning */>}}        Admonition inside of REST HTTP API description.        {{</* /warning */>}}        ...```

For the OpenAPI JSON output, this is rendered as> **WARNING:** ...(a blockquote with the admonition type in bold and uppercase).Only a single paragraph is properly supported by the toolchain. Additionalparagraphs will not be part of the blockquote.

Admonitions inside of other shortcodes need to use the special syntax, too:

{{< details summary="Outer shortcode" >}}{{</* tip*/>}}Inner shortcode{{</* /tip*/>}}{{< /details >}}

Tags let you display badges, usually below a headline.

This is mainly used for pointing out if a feature is only available in theAI Suite, the Data Platform, the Arango Managed Platform (AMP), or multipleof them. SeeEnvironment remarks for details.

It is also used forEdition remarks in content beforeversion 3.12.5.

Display content with a tabbed interface, like for code examples using differentlanguages or if there are multiple ways of achieving a goal like configuringArangoDB.

{{< tabs "startup-options" >}}{{< tab "Command-line" >}}Start`arangod` with the startup option`--log.level startup=trace`.{{< /tab >}}{{< tab "Configuration file" >}}Include the following startup option setting in your`arangod.conf`:```conf[log]level = startup=trace```{{< /tab >}}{{< /tabs >}}

The parameter for thetabs shortcode is a group identifier. If there aremultiple tab groups in one page, changing the active tab of one of them alsochanges the active tabs of all other groups with the same identifier whilegroups with different identifiers are unaffected. The browser remembers the lastactive tab of each group.

The parameter for thetab shortcode is the label to display for the tab in thetab panel. Tab groups using the same identifier should use the same tab labels.

Use the native Markdown syntax for including images, using a relative file path:

![Description](../images/file.png)

If you need more control over the styling of a specific image, you can use theimage shortcode:

{{< image src="../images/file.png" alt="Description" >}}

Available attributes:

• src: location of the image file
• alt: image description for accessibility
• class: CSS classes to apply
• style: CSS inline styles to apply

If a web interface uses icons, especially as buttons without labels, usetheicon shortcode to inline an SVG file for a visual reference asdemonstrated below:

Select all nodes ({{< icon "select-all" >}}), then right-click.

Icons are supposed to supplement the text, i.e. not be embedded in sentences.They are hidden from screen readers.

To add new icons to the toolchain, save them tosite/content/images/icons/.They are referenced by file name (without extension) in the shortcode.

SVG icon files should not define the attributeswidth,height,aria-hidden,andfocusable on the<svg> tag.

To document hotkeys and key combinations to press in a terminal or graphicaluser interface, use thekbd shortcode:

Press {{< kbd "Ctrl Return" >}} respectively {{< kbd "Cmd Return" >}} to run the query.

To prominently link to other content, you may use cards:

{{< cards >}}{{% card title="Graphs" link="graphs/" icon="/images/file.png" %}}Learn everything about graphs.{{% /card %}}{{% card title="Data science" link="data-science/" icon="/images/file.png" %}}Read about ArangoDB's features for analytics.{{% /card %}}{{< /cards >}}

If you want to place a remark in the source files that should not end up in thegenerated output, you can use a comment as follows:

{{% comment %}}Content or reminder that should not be rendered.{{% /comment %}}

The following shortcodes also exist but are rarely used:

• {{< details summary="A short description" >}}Content that is collapsed by default but can be expanded.{{< /details >}}

• {{< youtube >}} can be used to embed a single YouTube video,and{{< youtube-playlist >}}for a YouTube playlist.

• {{% optimizer-rules %}} is used once to render the list of AQL optimizerrules from a JSON source file.

• {{% program-options name="arangod" %}} renders the startup options of acomponent like the ArangoDB server (arangod) or shell (arangosh).

• {{% error-codes %}} renders the ArangoDB server error codes and their meaning.

• {{% exit-codes %}} renders the ArangoDB client and server exit codes and their meaning.

• {{% metrics %}} renders the list of ArangoDB server metrics.

• Use American English spelling, e.g.behavior instead ofbehaviour.

• Use inclusive language, e.g.work-hours instead ofman-hours.

• Get to point quickly on every page.Add lead paragraphsthat summarizes what the page is about.

• Target end-users and focus on the outcome. It should be about solutions, notfeatures.

• Do not use jargon or technical abbreviations in headlines or the navigation.Define the meaning if you use it in the content.

• Do not add too many admonitions or everything ends up being a callout.

• Wrap text at 80 characters where possible. This helps tremendously in versioncontrol. Pre-wrap lines if necessary.

• Put Markdown links on a single line[link label](target.md#hash),even if it violates the guideline of 80 characters per line.

• Avoid breaking lines of code blocks and where Markdown does not allow linebreaks, e.g. in Markdown table rows (you can use<br> if really necessary).

• Avoid usinghere as link label. Describe what the link points to instead.

• Avoid overly long link labels, such as entire sentences.

• Use relative links for cross-references to other documentation pages, e.g.../../data-platform/_index.md instead of/data-platform/_index.md orhttps://docs.arango.ai/data-platform/.

• Avoidbold anditalic markup in headlines. If you have to use it, thenprefer**bold** and*italic* over__bold__ and_italic_ because theunderscores are preserved in anchor links but asterisks are removed!

• Inline`code` in headlines is acceptable for code values, and requiredfor startup options because-- otherwise gets turned into an n-dash.

• - is preferred for bullet points in unordered lists over*

• Don't use# or=== for level 1 headlines. Every page should only havea single<h1> headline, and this is automatically generated from thetitle front matter parameter.

• Use## for level 2 headlines, not--- underlines.

• There should be a blank line above and below fenced code blocks and headlines(except if it is at the top of the document, right after the end of thefront matter---).

• Use all lowercase languages in fenced code blocks without whitespace beforeor after the language, and use the following languages in favor of the ones inparentheses for consistency:

  • ```py (instead of```python)
  • ```yaml (instead of```yml)
  • ```sh (instead of```shell)
  • ```js (instead of```javascript)
  • ``` (instead of```plain or```text)

• Use the exact spelling of Enterprise Edition and its features, as well as forall other terms coined by ArangoDB:

  • EnterpriseGraphs
  • SmartGraphs,Disjoint SmartGraphs
  • SmartGraphs using SatelliteCollection, notHybrid SmartGraphs
  • SmartJoins
  • OneShard
  • Community Edition
  • Enterprise Edition
  • DB-Server, notdbserver,db-server,DBserver (unless it is a code value)
  • Coordinator (uppercase C)
  • Agent,Agency (uppercase A)
  • Arango Managed Platform (AMP) andAMP for short, but notOasis,ArangoDB Oasis,ArangoDB Cloud,ArangoGraph Insights Platform, orArangoGraph
  • Arango Data Platform,Arango AI Data Platform, andAI Suite, but notArango AI Services Data Platform,Arango AI Suite Data Platform,AI Services, orGenAI Suite
  • Deployment mode (single server, cluster, etc.), notdeployment type

• Never capitalize the names of executables or code values, e.g. writearangosh instead ofArangosh.

• Do not write TODOs right into the content and avoid using<!-- HTML comments -->. Use{{< comment >}}...{{< /comment >}} instead.

For external links, use standard Markdown. Clicking these links automaticallyopens them in a new tab:

[Arango Managed Platform (AMP)](https://dashboard.arangodb.cloud)

For internal links, use relative paths to the Markdown files. Always link tofiles, not folders (e.g.../graphs/_index.md instead of../graphs/).This way, links can be followed in tools like Visual Studio Code and on GitHub.

[Graphs](../graphs/_index.md)

For anchor links, append#fragment-identifier to the path if the content isin a different file, or use the fragment ID only to link to a headline in thesame file:

See[Named Graphs](#named-graphs)

The main page about a new feature should indicate the version the feature wasadded in, as shown below:

---title:New feature...---<small>Introduced in: v3.12.0</small>...

Similarly, the remark should be added if only a section is added to an existingpage, as shown below:

##Existing feature...###New feature section<small>Introduced in: v3.12.0</small>...

The valuev3.12.0 implies that all later versions also have this feature(3.12.1, 3.12.2, etc., as well as 4.0.0 and later). If this is not the case,then also mention the other relevant versions. For example, if a feature isadded to 3.11.5 and 3.12.2, then write the following in the 3.12 documentation:

<small>Introduced in: v3.11.5, v3.12.2</small>

All later documentation versions should use a copy of the content, as thus the4.0 documentation would contain the same.

In the 3.11 documentation, only mention versions up to this documentation version(excluding 3.12 and later in this example), pretending no later version existsto be consistent with the rest of the 3.11 documentation and to avoid additionalmaintenance burdens:

<small>Introduced in: v3.11.5</small>

New options in the JavaScript and HTTP APIs are covered by the release notes,but if new options are added mid-release (not in thex.x.0 release but a laterbugfix version), then this should be pointed out as follows:

-`existingOption` (number,_optional_): ...-`newOption` (string,_optional_): ... (introduced in v3.11.5, v3.12.2).

You may also add a remark if an existing feature or option is significantlyextended by a new (sub-)option in ax.x.0 release.

While version remarks are mostlyIntroduced in: ..., you can also markdeprecated features in the same manner withDeprecated in: ....

Pages and sections about features that are only available in certain environmentssuch as in ArangoDB Shell should indicate where they are available using thetag shortcode.

Features exclusive to the Data Platform, AI Data Platform,Arango Managed Platform (AMP), and ArangoDB generally don't need to be taggedbecause they are in dedicated parts of the documentation. However, if there aresubsections with different procedures, each can be tagged accordingly.

In the AI Data Platform only:

{{< tag "AI Data Platform" >}}

In the Arango Managed Platform (AMP) only:

{{< tag "AMP" >}}

In the ArangoDB Shell but not the server-side JavaScript API:

{{< tag "arangosh" >}}

This shortcode should be placed immediately after a headline, before any versionremarks (<small>Introduced in: ...</small>).

You can define a tooltip for each tag in thetag.html template.

From version 3.12.5 onward, all features formerly exclusive to theEnterprise Edition are also included in the Community Edition.Therefore, using tags and other kinds of remarks to indicate what featuresrequire the Enterprise Edition should not be necessary.

In the contentbefore version 3.12.5, pages and sections aboutEnterprise Edition features should indicate that the Enterprise Edition isrequired using a tag. Use the following include in the general case:

{{< tag "ArangoDB Enterprise Edition" "AMP" >}}

Features that are available for testing but may still change or get removed andshould thus not be used in production can be tagged as follows:

{{< tag "Experimental" >}}

A lead paragraph is the opening paragraph of a written work that summarizes itsmain ideas. Only few pages have one so far, but new content should be writtenwith such a brief description. It is supposed to clarify the scope of thearticle so that the reader can quickly assess whether the following informationis of relevance, but also acts as an introduction.

You can set the lead paragraph via thedescription parameter in thefront matter of a page:

---title:Feature Xdescription:>-  You can do this and that with X, and it is ideal to solve problem Y---...

The lead paragraph text should end without a period, contain no links, andusually avoid other markup as well. However,bold,italic, andinline code are acceptable.

Start off by finding a file name. It should be:

• All lower-case
• Use hyphen-minus- instead of spaces
• Be very short but descriptive
• Follow the patterns of existing files

Note that the file name is independent of what will show in the navigation orwhat will be used as headline for that page. The file name will be used aspart of the final URL, however. For example,arangodb/3.12/aql/examples.mdwill becomehttp://docs.arango.ai/arangodb/3.12/aql/examples/.

Create a new file with the file name and a.md file extension. Open the filein a text editor (Visual Studio Code is recommended). Add the followingfront matter:

---title:The level 1 headlinedescription:>-  A meaningful description of the pagemenuTitle:Short navigation menu titleweight:42# controls navigation position within the current section (low to high)---

Add the actual content formatted in Markdown syntax below the front matter.

Netlify supports server-side redirects configured with a text file(documentation).This is helpful when renaming folders with many subfolders and files becausethere is support for splatting and placeholders (but not regular expressions). SeeRedirect optionsfor details. The configuration file issite/static/_redirects.

Otherwise, the following steps are necessary for moving content:

1. Rename file or folder
2. Set upaliases via the front matter as needed
3. Adjustweight of pages in the front matter if necessary
4. Update cross-references in all of the content to use the new file path

The URL of a page is derived from the file name and the parent folders, withspecial handling for sections (folders with a_index.md file).For example,arangodb/3.12/aql/operators.md becomes the URL path/arangodb/3.12/aql/operators/, andarangodb/3.12/aql/functions/_index.mdbecomes/arangodb/3.12/aql/functions/.

If you rename a file, fromsection/old-name.md tosection/new-name.md forinstance, make sure to add a redirect for the old URL by adding the following tothe front matter ofsection/new-name.md:

aliases:  -old-name

Don't forget to update any references to the old file in the content to the newpath.

If you move a file from one folder to another, fromold/file.md tonew/file.mdfor instance, use a relative path as shown below:

aliases:  -../old/file

If you rename a folder, fromold/ tonew/ for instance, add the followingfront matter tonew/_index.md:

aliases:  -old

For aliases in_index.md files, think of the folder they are in as a file.In the above example, the folder isnew/. Treating it like the file thatdefines the page means that the aliasold is relative to its parent folder(here: the root folder of the content,site/content/). Therefore, the aliasneeds to beold, not../old.

Note that you need to set up aliases for all files innew/ so that every URLwhich includes the old folder name redirects to the corresponding new URL.For example, for a filenew/other.md (previouslyold/other.md), add thefollowing:

aliases:  -../old/other

Aliases create HTML files with client-side redirects before any content isrendered to HTML, which means that aliases can get overwritten by content files.If this is not a mistake, the affected aliases should be removed.

The table of contents (ToC) or "On this page" on the right-hand side at the topof a page lists the headlines if there are at least two headlines on the page(excluding the title).

The ToC can be restricted to a maximum headline level to omit the deeper nestedheadlines for less clutter:

---...pageToc:maxHeadlineLevel:3---

A setting of3 means that<h1>,<h2>, and<h3> headlines will be listedin the ToC, whereas<h4>,<h5>, and<h6> will be ignored.

When an ArangoDB version reachesEnd-of-Life,its documentation needs to be marked as such. For the respective version, setthedeprecated attribute totrue in thesite/data/versions.yaml file:

 - name: "3.10"   version: "3.10.9"   alias: "3.10"-  deprecated: false+  deprecated: true

It makes a warning show at the top of every page for that version.

1. In thesite/data/versions.yaml file, add a new entry for the version youwant to add. Example:

   +- name: "4.0"+  version: "4.0.0"+  alias: "4.0"+  deprecated: false+ - name: "3.12"   version: "3.12.0"   alias: "devel"   deprecated: false

2. Near the top of the.circleci/config.yml file underparameters, find thelast entry with the formatarangodb-X_XX whereX_XX is a version numberlike3_12, soarangodb-3_12 for example. Duplicate the block and adjustthe version number. Example:

      arangodb-3_12:     type: string     default: "undefined"++  arangodb-4_0:+    type: string+    default: "undefined"

   Near the end of the file underjobs.generate-config.steps[0].run.command,find the line of code that callspython3 generate_config.py. In one of thefollowing lines, a parameter for every version is passed as argument. Add onefor the new version. Example:

                python3 generate_config.py \               --workflow << pipeline.parameters.workflow >> \-              --arangodb-branches << pipeline.parameters.arangodb-3_11 >> << pipeline.parameters.arangodb-3_12 >> \+              --arangodb-branches << pipeline.parameters.arangodb-3_11 >> << pipeline.parameters.arangodb-3_12 >> << pipeline.parameters.arangodb-4_0 >> \

3. In thetoolchain/docker/amd64/docker-compose.yml file, add an entry underservices.toolchain.volumes for the new version. Simply increment the valueafter:-/tmp/. Example:

          - ${ARANGODB_SRC_3_12:-/tmp/2}:/tmp/3.12+      - ${ARANGODB_SRC_4_0:-/tmp/3}:/tmp/4.0

   Underservices.toolchain.environment, you need to add two different entriesfor the new version. Example:

          ARANGODB_SRC_3_11: ${ARANGODB_SRC_3_11}       ARANGODB_SRC_3_12: ${ARANGODB_SRC_3_12}+      ARANGODB_SRC_4_0: ${ARANGODB_SRC_4_0}       ARANGODB_BRANCH_3_11: ${ARANGODB_BRANCH_3_11}       ARANGODB_BRANCH_3_12: ${ARANGODB_BRANCH_3_12}+      ARANGODB_BRANCH_4_0: ${ARANGODB_BRANCH_4_0}

   The same changes are required in thetoolchain/docker/arm64/docker-compose.yml file.

4. In thetoolchain/docker/config.yaml file, add an entry for the new version.Example:

      - image: ${ARANGODB_BRANCH_3_12_IMAGE}     version: ${ARANGODB_BRANCH_3_12_VERSION}++  - image: ${ARANGODB_BRANCH_4_0_IMAGE}+    version: ${ARANGODB_BRANCH_4_0_VERSION}

5. In thetoolchain/scripts/toolchain.sh file, find the code that accessesenvironment variables with the format$ARANGODB_BRANCH_X_XX whereX_XXis a version number like3_12, so$ARANGODB_BRANCH_3_12 for instance.Duplicate the block of an existing version and adjust all version numbers.Example:

    if [ "$ARANGODB_BRANCH_3_12" != "" ] ; then       export ARANGODB_BRANCH_3_12_IMAGE="$ARANGODB_BRANCH_3_12"       export ARANGODB_BRANCH_3_12_VERSION="3.12" fi+if [ "$ARANGODB_BRANCH_4_0" != "" ] ; then+      export ARANGODB_BRANCH_4_0_IMAGE="$ARANGODB_BRANCH_4_0"+      export ARANGODB_BRANCH_4_0_VERSION="4.0"+fi

6. In thesite/data folder, create a new folder with the short version numberas the name, e.g.4.0. In the newsite/data/4.0 folder, create acache.json file with the following content:

   {}

   Add this untracked file to Git!

7. Duplicate the folder of the most recent version insite/content, e.g.the3.12 folder, and rename the copy to the new version, e.g.4.0.

   ThemenuTitle in the front matter of the version homepage, e.g.site/content/4.0/_index.md, needs to adjusted to the new version,likemenuTitle: '4.0'.

   In the folder for release notes, e.g.site/content/4.0/release-notes/,duplicate the folder of the most recent version, e.g.version-3.12, andrename it, e.g. toversion-4.0. In this folder, rename the files to replacethe old with the new version number, e.g.api-changes-in-3-12.md toapi-changes-in-4-0.md and so on.

   In the_index.md file in the folder, e.g.site/content/4.0/release-notes/version-4.0/_index.md, you need to replacethe version numbers in the front matter and links. You also need to adjusttheweight in the front matter. Decrement the value by one to make the newversion appear before the existing versions, but make sure that it is greaterthan0, which may require adjusting the weights in all of the section files.

   In the other files of the release notes, remove the version-specific contentand only leave the front matter, introductions, and headlines that arecommonly used across different versions in the release notes. Adjust theversion numbers in the front matter and content.

   Search the entire version folder, e.g.site/content/4.0/, for links thatare meant to point to the release notes of the own version, but which arestill pointing to the version the content has been copied from. For example,if you duplicated the3.12 folder, search the4.0 folder forversion-3.12/. You should find links toversion-3.12/known-issues-in-3-12.mdthat need to be updated toversion-4.0/known-issues-in-4-0.md.

   In the release notes root file, e.g.site/content/4.0/release-notes/_index.md,add the links for the new version following the existing pattern. Do thisafter updating the links to the known issues so that you don't accidentallychange the 3.12 link in the release notes root file.

   In theHighlights by Version page, e.g.site/content/4.0/introduction/features/highlights-by-version.md, add asection for the new version including a link to the release notes.

   Add the new, untracked files to Git!

8. In thePULL_REQUEST_TEMPLATE.md file, add a new line for the new version.Example:

    - 3.12:+- 4.0:

   Stage all changes and commit them. Open a pull request (PR) on GitHub. You onlyneed to specify a Docker image or PR link for- 4.0: if you plan to usethe/generate or/generate-commit command to re-generate the examples.If you follow the next step, the example generation is run manually alongwith some other generators, so using the commands shouldn't be necessary.

   Expect the plain build to fail for the time being because of missing data files.

9. You can use CircleCI to initially generate the data files for the new version,like the startup option dumps. You can also populate the example cache at thesame time.

   Before you continue, make sure there are no conflicts in the PR with themain branch. The CircleCI workflow will otherwise create a merge commitfavoring themain branch (in order to update the cache file but alsoaffecting other files), and this can cause e.g. theversions.yaml file toget reverted in case of a conflict. The toolchain would then be unaware ofthe newly added version.

   In CircleCI athttps://app.circleci.com/pipelines/github/arangodb/docs-hugo,select the branch of your PR and clickTrigger Pipeline.Enter the parameters similar to this example:

   Type	Name	Value
   string	workflow	generate
   string	arangodb-4_0	Docker Hub image (e.g.arangodb/enterprise-preview:devel-nightly) or GitHub main repo PR link (e.g.https://github.com/arangodb/arangodb/pull/123456)
   string	generators	examples metrics error-codes exit-codes optimizer options
   string	deploy-url	deploy-preview-{PR-number} with the number of the docs PR
   boolean	commit-generated	true

   Approve the workflow in CircleCI. After a successful run, you should see acommit in the docs PR with the updated data files, as well as an updatedexample cache file. The plain build should no longer fail and provide youwith a Netlify preview.

The process is similar toadding a version but you need toundo the changes.

For example, if the current stable version is 3.11 and the devel version is 3.12,thesite/data/versions.yaml file may look like this:

-name:"4.0"version:"4.0.0"alias:"4.0"deprecated:false-name:"3.12"version:"3.12.0"alias:"devel"deprecated:false-name:"3.11"version:"3.11.4"alias:"stable"deprecated:false

To make 3.12 the new stable version, you need to setalias to"stable" forthe 3.12 entry. As there can only be a single stable version (in thedocumentation sense), thealias value of the former stable version needs to bechanged. In this example, it is the 3.11 entry where you need to changealiasto the versionname, which is"3.11" in this case. Finally, you need tore-assign the"devel" alias to the version that comes after the new stableversion. In this example, you need to adjust thealias of the 4.0 entry.The final configuration would then look lik this:

-name:"4.0"version:"4.0.0"alias:"devel"# was "4.0"deprecated:false-name:"3.12"version:"3.12.0"alias:"stable"# was "devel"deprecated:false-name:"3.11"version:"3.11.4"alias:"3.11"# was "stable"deprecated:false

A complete example:

```js---name: ensureUniquePersistentSingledescription: Create a unique persistent index on a singledocument attribute---~db._create("ids");db.ids.ensureIndex({ type:"persistent", fields: ["myId" ], unique:true });db.ids.save({"myId":123 });db.ids.save({"myId":123});// xpError(ERROR_ARANGO_UNIQUE_CONSTRAINT_VIOLATED)~db._drop("ids");```

Groups of examples should have the same name prefix.

If an example needs to be run against an ArangoDB cluster instead of asingle server (default), then add the following front matter option:

type:cluster

To not render the transcript comprised of input and output but only the inputor output, set therender front matter option:

render:input# or 'output', default 'input/output'

After the front matter, you can write the JavaScript code for arangosh:

db._create("collection");db.collection.save({_key:"foo",value:123});db._query(`FOR doc IN collection RETURN doc.value`).toArray();db._drop("collection");

Statements can span multiple lines:

db.collection.save([{multiple:true},{lines:true}]);

The statements as well as the results will be visible in the example transcript.To hide certain statements from the output, e.g. for setup/teardown that is notrelevant for the example, you can use a leading tilde~ to suppress individuallines:

~db._create("collection");db.collection.save({_key:"foo"});~db._drop("collection");

Examples need to remove the collections and Views they create. Not dropping themwill raise an error unless they are specifically exempt:

~db._create("collection");~db._createView("view","arangosearch",{...});db.collection.save({...});~addIgnoreView("view");~addIgnoreCollection("collection");

This is helpful for creating collections and Views once, using them in multipleexamples, and finally dropping them instead of having to create and drop themin each example.

The last example of the series should undo the ignore to catch unintended leftovers:

~removeIgnoreCollection("collection");~removeIgnoreView("view");~db._dropView("view");~db._drop("collection");

Note that a series of examples needs to be contained within a single file.

If a statement is expected to fail (e.g. to demonstrate the error case), thenthis has to be indicated with a special JavaScript comment:

db._document("collection/does_not_exist");// xpError(ERROR_ARANGO_DOCUMENT_NOT_FOUND)

This will make the example generation continue despite the error. SeeError codes and meaningsfor a list of all error codes and their names. If a unexpected error is raised,then the example generation will abort with an error.

Every backslash in a query needs to be escaped with another backslash, i.e.JSON escape sequences require two backslashes, and literal backslashes four:

db._query(`RETURN REGEX_SPLIT("foo\\t bar\\r baz\\n foob", "\\\\s+|(?:b\\\\b)")`).toArray();

This does not apply to backslashes in bind variables:

db._query(`RETURN REGEX_SPLIT(@t, @r)`,{t:"foo\t bar\r baz\n foob",r:"\\s+|(?:b\\b)"}).toArray();

Complete example:

```aql---name: joinTuplesdescription:bindVars: {  friend: "friend"}dataset: joinSampleDatasetexplain: true---FOR u IN users  FILTER u.active == true  LIMIT 0, 4  FOR f IN relations    FILTER f.type == @friend && f.friendOf == u.userId    RETURN {      "user" : u.name,      "friendId" : f.thisUser    }```

An example can optionally specify adataset in the front matter that will beloaded before the query is run:

dataset:name_of_dataset

Seedatasets.jsonfor the available datasets.

To get the query explain output including the execution plan instead of theactual query result, you can optionally specify theexplain option in thefront matter:

explain:true

Then the actual AQL query follows, e.g.

FOR i IN 1..3  RETURN i

The query can optionally use bind parameters that can be set via thebindVarsoption in the front matter:

---...bindVars:'@coll':productsattr:    -title    -de# or using JSON notation:#bindVars: { "@coll": "products", "attr": ["title", "de"] }---FOR doc IN @@collRETURN doc.@attr

Used to describe an HTTP REST API endpoint using theOpenAPI Specification standard inversion 3.1.0.

The content inside the codeblock is a standard OpenAPI endpoint description inYAML format for a single ArangoDB endpoint. The headline above the code block isalso used as the endpoint summary automatically:

### Get the service README```openapipaths:  /_api/foxx/readme:    get:      operationId: getFoxxReadme      description: |        Fetches the service's README or README.md file's contents if any.      parameters:        - name: mount          in: query          required: true          description: |            Mount path of the installed service.          schema:            type: string      responses:        '200':          description: |            Returned if the request was successful.        '204':          description: |            Returned if no README file was found.      tags:        - Foxx```

Only define a single tag intags as this is used to categorize the endpoints.See theopenapi_tags.yaml file for the availablecategories, or add new ones if necessary.

The REST HTTP API endpoint descriptions are rendered in the documentation, butarangoproxy also converts the YAML to JSON and assembles a singleapi-docs.jsonfile. This file is needed by the web interface forSwagger UI.

Complete example:

```curl---name: HttpAqlToBase64description: Encode example credentials using the HTTP API---var url = "/_api/cursor";var body = { query: `RETURN TO_BASE64("user:pass")` };var response = logCurlRequest('POST', url, body);assert(response.code === 201);logJsonResponse(response);```

If an endpoint requires the_system database as the context, the URL should beset accordingly, e.g.var url = "/_db/_system/_api/database";. This ensuresthat the request is issued correctly as the toolchain may process other examplesthat change the database context simultaneously.

Unlike arangosh examples (```js), requests and responsesneed to be output explicitly by calling one of the following functions:

• logCurlRequest(method, url, body) → response: make and output an HTTP request
• logCurlRequestRaw(method, url, body) → response: make and output an HTTPrequest without code highlighting
• logCurlRequestPlain(method, url, body) → response: make and output an HTTPrequest, with the payload decoded (new lines instead of\r\n etc.). Usefulfor formatting complex requests.
• logJsonResponse(response): output a JSON server reply (fails on invalid JSON)
• logJsonLResponse(response): output a JSONL server reply (fails on invalid JSON)
• logRawResponse(response): output plaintext response (do not use for JSON replies;can be used for endpoint calls that return an empty body to output the headers)
• logPlainResponse(response): output decoded response (new lines instead of\r\n etc.). Useful for formatting complex responses, like from batch requests.
• logHtmlResponse(response): output HTML
• logErrorResponse(response): dump reply to error log for testing(makes example generation fail)

To test whether requests and replies are as expected, you can addassert(expression) calls. Expressions that evaluate to false will make theexample generation fail. You can inspect the CircleCI logs for details.

To use specialized assertions, you need to import them fromjsunity,likeassertTrue(),assertEqual(),assertTypeOf(),assertUndefined(), etc.

varassertTypeOf=require("jsunity").jsUnity.assertions.assertTypeOf;assertTypeOf("string",response.parsedBody.name);