{"id":19870146,"url":"https://github.com/arangodb/docs-hugo","last_synced_at":"2025-05-02T08:31:40.552Z","repository":{"id":74704383,"uuid":"598055547","full_name":"arangodb/docs-hugo","owner":"arangodb","description":"Source code of the ArangoDB online documentation","archived":false,"fork":false,"pushed_at":"2025-04-25T11:43:13.000Z","size":77157,"stargazers_count":5,"open_issues_count":11,"forks_count":7,"subscribers_count":24,"default_branch":"main","last_synced_at":"2025-04-25T12:35:40.423Z","etag":null,"topics":["arangodb","distributed-database","documentation","graph-database","graphdb","hacktoberfest","hugo","nosql-database"],"latest_commit_sha":null,"homepage":"https://docs.arangodb.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arangodb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-02-06T09:55:28.000Z","updated_at":"2025-04-25T11:43:16.000Z","dependencies_parsed_at":"2025-04-25T12:36:11.441Z","dependency_job_id":null,"html_url":"https://github.com/arangodb/docs-hugo","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arangodb%2Fdocs-hugo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arangodb%2Fdocs-hugo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arangodb%2Fdocs-hugo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arangodb%2Fdocs-hugo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arangodb","download_url":"https://codeload.github.com/arangodb/docs-hugo/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252008826,"owners_count":21679646,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arangodb","distributed-database","documentation","graph-database","graphdb","hacktoberfest","hugo","nosql-database"],"created_at":"2024-11-12T16:08:05.362Z","updated_at":"2025-05-02T08:31:40.543Z","avatar_url":"https://github.com/arangodb.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ArangoDB Documentation\n\nThis repository contains the source files of the ArangoDB documentation as\npublished on [docs.arangodb.com](https://docs.arangodb.com/).\n\nThe ArangoDB documentation is licensed under Apache-2.0.\nSee [LICENSE](LICENSE) for details.\n\n## Contribute\n\nTo suggest a concrete change to the documentation, you may\n[edit files directly on GitHub](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files).\nIt will fork the repository automatically if necessary. Commit the changes to a\nnew branch, give it a succinct name, and open a pull request (PR).\n\nTo add more changes to a PR, click on the branch name below the headline\nof the PR (the latter link of \"\u0026lt;User\u0026gt; wants to merge \u0026lt;n\u0026gt; commits\ninto `main` from `branch-name`\"). Then locate and edit the next file.\nCommit the changes directly to your PR branch.\n\nFor general suggestions, feel free to\n[create an issue](https://github.com/arangodb/docs-hugo/issues/new).\n\n### Automatic Previews\n\nIn every pull request, the _arangodb-docs-automation_ bot comments with a deploy\npreview link. Whenever you push a change to the PR branch, a preview is built.\nIf it succeeds, then you can view the preview hosted on Netlify by following\nthe link.\n\nNote that the automatic previews run [plain builds](#plain-build), which means\nthat [generated content](#generated-content) is not updated. The ArangoDB\ndocumentation team takes of regenerating this content if necessary.\n\n### Contributor License Agreement\n\nTo accept external contributions, we need you to fill out and sign our\nContributor License Agreement (CLA). We use an Apache 2 CLA for ArangoDB,\nwhich can be found here: \u003chttps://www.arangodb.com/documents/cla.pdf\u003e\nYou can scan and email the CLA PDF file to \u003ccla@arangodb.com\u003e or send it via\nfax to +49-221-2722999-88.\n\n## Build the documentation\n\nThe following section describes how you can build the documentation locally.\nThis is not strictly necessary when contributing. You can also rely on\n[automatic previews](#automatic-previews) for basic changes.\n\n### The toolchain\n\nAt the core, docs are generated with the static site generator\n[Hugo](https://gohugo.io/). The `hugo` build command generates static HTML\ncontent from the Markdown, data, and theme files.\n\nThe documentation toolchain is containerized and uses Docker Compose to\norchestrate builds. The following containers are created:\n\n- `toolchain` - contains the code for controlling the toolchain and the\n  generated content, spawning the other containers\n- `docs_arangoproxy` - contains the arangoproxy web server written in Go that\n  handles generated content using arangosh to run examples against a server and\n  assemble the OpenAPI descriptions\n- `docs_site` - contains Hugo and the logic to start it\n- `docs_server_\u003cversion\u003e` - an ArangoDB single server\n- `docs_server_\u003cversion\u003e_cluster` - an ArangoDB cluster\n\n### Render hooks\n\nFor headlines, links, images, and fenced code blocks in Markdown, Hugo can run\ntemplate files that are called _Render Hooks_ to trigger special processing.\nThis is used to extract and execute examples against actual ArangoDB servers and\nplace the output into the rendered documentation, for example.\n\n- **Heading render hook**\n\n  Defined in `site/themes/arangodb-docs-theme/layouts/_default/_markup/render-heading.html`\n\n  Checks that there is no level 1 `# Headline` in the content, as this is\n  reserved for the `title` defined in the front matter. Also injects the widget\n  to copy anchor links to the clipboard.\n\n- **Link render hook**\n\n  Defined in `site/themes/arangodb-docs-theme/layouts/_default/_markup/render-link.html`\n\n  Scans all the hrefs in a file and tries to retrieve the page from that link.\n  If the page is not found, the build fails because of a broken link.\n\n- **Image render hook**\n\n  Defined in `site/themes/arangodb-docs-theme/layouts/_default/_markup/render-image.html`\n\n  Transforms the style attributes defined in the image link as\n  `{path.png?{attribute1=value1\u0026attribute2=value2\u0026..}}` in a style attribute\n  inside the `img` HTML tag.\n\n- **Codeblock render hook**\n\n  Defined in `site/themes/arangodb-docs-theme/layouts/_default/_markup/render-codeblock-*.html`\n\n  Triggers a remote call to the _arangoproxy_ web server for assembling the\n  OpenAPI descriptions as well as to run the example generation if the code\n  starts with a front matter block surrounded by `---`, like this:\n\n  ````markdown\n  ```aql\n  ---\n  name: the_answer\n  description: AQL block with front matter\n  ---\n  RETURN 42\n  ```\n  ````\n\n  The following codeblocks are supported:\n\n  - `` ```js `` for arangosh / JavaScript API examples\n  - `` ```aql `` for AQL query examples\n  - `` ```openapi `` for REST HTTP API descriptions\n  - `` ```curl `` for REST HTTP API examples\n\nThe hooks trigger a `POST` call to the dedicated _arangoproxy_ endpoint\n(`/js`, `/aql`, `/curl`, `openapi`) with the entire codeblock as request body.\n\nThe _arangoproxy_ endpoint parses the request, checks if the examples is cached,\notherwise executes the code against the ArangoDB instance with the version as\ndetermined from the version folder name and saves the example output in the cache.\n\nThe input/output (as defined in the YAML render option) is returned as JSON to\nHugo in the render hook, which generates HTML replacing the codeblock in the\nfile with the input/output of the example.\n\n### Build workflows\n\nThe following build workflows exist:\n\n- **Plain build workflow**\n\n  Build docs without re-generating examples (using a committed cache file).\n\n  Includes the assembly of the REST HTTP API descriptions (OpenAPI) with\n  validation at each run. `` ```curl `` examples require a different workflow.\n\n  You may need to specify upstream branches.\n\n- **Scheduled workflow**\n\n  The following generated content is re-generated periodically using CircleCI:\n  - Metrics\n  - Error codes and meanings\n  - AQL optimizer rules\n  - Startup options\n  - oasisctl documentation\n\n- **Example generation workflow**\n\n  Build docs including re-generating examples for AQL, arangosh (JavaScript API),\n  and cURL (HTTP API).\n\n  Specifying upstream branches is required for all versions in which you modified\n  example code and thus require a re-generation. These can be a Docker Hub images\n  or GitHub pull request links.\n\n#### Plain build\n\nGo to the `toolchain/docker/\u003carchitecture\u003e` folder, with `\u003carchitecture\u003e` being\neither `amd64` for x86-64 CPUs and `arm64` for 64-bit ARM CPUs (including\nApple silicon like M1).\n\nRun the `docker compose` services using the `docker-compose.pain-build.yml` file.\n\n```sh\ndocs-hugo/toolchain/docker/amd64\u003e docker compose -f docker-compose.plain-build.yml up --abort-on-container-exit\n```\n\nThe site will be available at `http://localhost:1313`.\n\nTo make the documentation tooling not start a live server in watch mode but\nrather create a static build and exit, set the environment variable `ENV` to\nany value other than `local` before calling `docker compose ...`:\n\n```sh\nexport ENV=static  # Bash\nset -xg ENV static # Fish\n$Env:ENV='static'  # PowerShell\n```\n\nThe output files will be written to `site/public/`.\n\n#### Scheduled and example generation build\n\n**Configuration**\n\nThe toolchain container needs to be set up via config file in `toolchain/docker/config.yaml`:\n\n```yaml\ngenerators:   # Generators to trigger - empty string defaults to all generators\nservers:      # Array to define arangodb servers to be used by the toolchain\n  - image:    # arangodb docker image to be used, can be arangodb/enterprise-preview:... or a branch name\n    version:  # docs branch to put the generated content into\n  - ...       # Additional images and versions as needed\n```\n\n**Available generators**\n\n- `examples`\n- `metrics`\n- `error-codes`\n- `optimizer`\n- `options`\n- `oasisctl`\n\nThe generators entry is a space-separated string.\n\nIf `metrics` or `error-codes` is in the `generators` string, the following\nenvironment variable has to be exported:\n\n```sh\nexport ARANGODB_SRC_{VERSION}=path/to/arangodb/source\n```\n\nSubstitute `{VERSION}` with a version number like `3_11`.\n\nOn Windows using PowerShell, use a Unix-like path:\n\n```powershell\n$Env:ARANGODB_SRC_3_11 = \"/Drive/path/to/arangodb\"\n```\n\n**Configuration example**\n\n```yaml\ngenerators: examples oasisctl options optimizer\nservers:\n  - image: arangodb/enterprise-preview:3.11-nightly\n    version: \"3.11\"\n  - image: arangodb/enterprise-preview:devel-nightly\n    version: \"3.12\"\n```\n\n**Run the toolchain**\n\nGo to the `toolchain/docker/\u003carchitecture\u003e` folder, with `\u003carchitecture\u003e` being\neither `amd64` for x86-64 CPUs and `arm64` for 64-bit ARM CPUs (including\nApple silicon like M1).\n\nRun the `docker compose` services without specifying a file:\n\n```sh\ndocs-hugo/toolchain/docker/arm64\u003e docker compose up --abort-on-container-exit\n```\n\nThe site will be available at `http://localhost:1313`\n\n## Work with the documentation content\n\n### Documentation structure\n\nIn the `site/content` directory, the directories `3.10`, `3.11` etc. represent\nthe individual ArangoDB versions and their documentation. There is only one\nmaintained version of the documentation for every minor and major version (3.12,\n4.0, etc.) but not for every patch release (e.g. 3.12.1).\n\nHaving a folder per version has the advantage that all versions can be built at\nonce, but the drawback of Git cherry-picking not being available and therefore\nrequiring to manually apply changes to different versions as necessary.\n\n- `site/` - Folder with all files that Hugo needs to generate the site\n  - `config/` - The base Hugo configuration in `_default/` as well as additional\n    configurations for different build workflows\n  - `content/` - The Markdown source files in version folders as well as a\n    shared folder for images\n  - `data/` - Contains JSON and YAML files for the documentation versions,\n    the OpenAPI tag list, the example cache, etc.\n  - `public/` - Default output directory for the generated site (not committed)\n  - `resources/` - Holds the various cached resources that are generated by Hugo\n    when using `hugo serve`\n  - `themes/` - Folder for Hugo themes, containing the customized ArangoDB docs theme\n- `toolchain/` - Folder for the docs toolchain tools and scripts\n  - `arangoproxy/` - Source code of the arangoproxy web server\n  - `docker/` - The Docker container and compose files, with two sets of\n    configurations for the `amd64` and `arm64` architectures that are needed for\n    the scheduled and example generation build workflows\n  - `scripts/` - The toolchain scripts\n\n### Markup overview\n\nThe documentation is written in the light-weight markup language\n[Markdown](https://daringfireball.net/projects/markdown/), using the GitHub\nflavor, and further extended by Hugo _shortcodes_ for advanced templating needs.\n\nFor an overview over the basic markup, see the [CommonMark help](https://commonmark.org/help/).\n\nThe following extensions are available:\n\n#### Admonitions\n\nYou can use admonitions for hints and callouts that render in a colored box with\nan icon, highlighting useful or important information.\n\n```markdown\n{{\u003c danger \u003e}}\nCritical information to prevent data loss or similarly impactful events.\n{{\u003c /danger \u003e}}\n```\n\n```markdown\n{{\u003c warning \u003e}}\nBe careful and mind restrictions to avoid issues.\n{{\u003c /warning \u003e}}\n```\n\n```markdown\n{{\u003c security \u003e}}\nMind this information to keep the system and your data safe.\n{{\u003c /security \u003e}}\n```\n\n```markdown\n{{\u003c info \u003e}}\nHelpful information to have.\n{{\u003c /info \u003e}}\n```\n\n```markdown\n{{\u003c tip \u003e}}\nFollow best practices and utilize features to set yourself up for success.\n{{\u003c /tip \u003e}}\n```\n\nAdmonitions can also be used in `description` fields inside of `` ```openapi ``\ncode blocks but the syntax then needs to be like this:\n\n````yaml\n```openapi\npaths:\n  /_api/endpoint:\n    post:\n      description: |\n        {{\u003c/* warning */\u003e}}\n        Admonition inside of REST HTTP API description.\n        {{\u003c/* /warning */\u003e}}\n        ...\n```\n````\n\nFor the OpenAPI JSON output, this is rendered as `\u003e **WARNING:** ...`\n(a blockquote with the admonition type in bold and uppercase).\nOnly a single paragraph is properly supported by the toolchain. Additional\nparagraphs will not be part of the blockquote.\n\nAdmonitions inside of other shortcodes need to use the special syntax, too:\n\n```markdown\n{{\u003c expand title=\"Outer shortcode\" \u003e}}\n\n{{\u003c/* tip */\u003e}}\nInner shortcode\n{{\u003c/* /tip */\u003e}}\n\n{{\u003c /expand \u003e}}\n```\n\n#### Tags\n\nTags let you display badges, usually below a headline.\n\nThis is mainly used for pointing out if a feature is only available in the\nEnterprise Edition of ArangoDB, the ArangoGraph Insights Platform, or both.\nSee [Edition remarks](#edition-remarks) for details.\n\n#### Tabs\n\nDisplay content with a tabbed interface, like for code examples using different\nlanguages or if there are multiple ways of achieving a goal like configuring\nArangoDB.\n\n```markdown\n{{\u003c tabs \"startup-options\" \u003e}}\n\n{{\u003c tab \"Command-line\" \u003e}}\nStart `arangod` with the startup option `--log.level startup=trace`.\n{{\u003c /tab \u003e}}\n\n{{\u003c tab \"Configuration file\" \u003e}}\nInclude the following startup option setting in your `arangod.conf`:\n\n```conf\n[log]\nlevel = startup=trace\n```\n{{\u003c /tab \u003e}}\n\n{{\u003c /tabs \u003e}}\n```\n\nThe parameter for the `tabs` shortcode is a group identifier. If there are\nmultiple tab groups in one page, changing the active tab of one of them also\nchanges the active tabs of all other groups with the same identifier while\ngroups with different identifiers are unaffected. The browser remembers the last\nactive tab of each group.\n\nThe parameter for the `tab` shortcode is the label to display for the tab in the\ntab panel. Tab groups using the same identifier should use the same tab labels.\n\n#### Figures\n\nIf you want to add an image with a caption, use this shortcode instead of the\nnative Markdown syntax `![alt](/images/file.png)`:\n\n```markdown\n{{\u003c image src=\"../images/file.png\" alt=\"Description of image content, used as caption\" \u003e}}\n```\n\nAvailable attributes:\n\n- `src`: location of the image file\n- `class`: CSS class to apply\n- `style`: CSS inline styles to apply\n- `size`: image width, can be numeric or one of `small`, `medium`, `large`\n- `alt`: image description for accessibility\n\n#### Icons\n\nDisplay an image with special styling.\n\n```markdown\n{{\u003c icon src=\"../images/file.png\" alt=\"Description of image content, used by screen readers\" \u003e}}\n```\n\nAvailable attributes:\n\n- `src`: location of the image file\n- `class`: CSS class to apply\n- `style`: CSS inline styles to apply\n- `size`: image width, can be numeric or one of `small`, `medium`, `large`\n- `alt`: image description for accessibility\n\n#### Cards\n\nTo prominently link to other content, you may use cards:\n\n```markdown\n{{\u003c cards \u003e}}\n\n{{% card title=\"Graphs\" link=\"graphs/\" icon=\"/images/file.png\" %}}\nLearn everything about graphs.\n{{% /card %}}\n\n{{% card title=\"Data science\" link=\"data-science/\" icon=\"/images/file.png\" %}}\nRead about ArangoDB's features for analytics.\n{{% /card %}}\n\n{{\u003c /cards \u003e}}\n```\n\n#### Comments\n\nIf you want to place a remark in the source files that should not end up in the\ngenerated output, you can use a comment as follows:\n\n```markdown\n{{% comment %}}\nContent or reminder that should not be rendered.\n{{% /comment %}}\n```\n\n#### Special shortcodes\n\nThe following shortcodes also exist but are rarely used:\n\n- ```markdown\n  {{\u003c expand title=\"A short description\" \u003e}}\n  Content that is collapsed by default but can be expanded.\n  {{\u003c /expand \u003e}}\n  ```\n\n- `{{\u003c youtube id=\"dQw4w9WgXcQ\" \u003e}}` can be used to embed a single YouTube video,\n  and `{{\u003c youtube-playlist id=\"PL0tn-TSss6NV45d1HnLA57VJFH6h1SeH7\" \u003e}}`\n  for a YouTube playlist.\n\n- `{{% optimizer-rules %}}` is used once to render the list of AQL optimizer\n  rules from a JSON source file.\n\n- `{{% program-options name=\"arangod\" %}}` renders the startup options of a\n  component like the ArangoDB server (`arangod`) or shell (`arangosh`).\n\n- `{{% error-codes %}}` renders the ArangoDB server error codes and their meaning.\n\n- `{{% metrics %}}` renders the list of ArangoDB server metrics.\n\n### Content Guidelines\n\n- Use American English spelling, e.g. _behavior_ instead of _behaviour_.\n\n- Use inclusive language, e.g. _work-hours_ instead of _man-hours_.\n\n- Get to point quickly on every page. [Add lead paragraphs](#add-lead-paragraphs)\n  that summarizes what the page is about.\n\n- Target end-users and focus on the outcome. It should be about solutions, not\n  features.\n\n- Do not use jargon or technical abbreviations in headlines or the navigation.\n  Define the meaning if you use it in the content.\n\n- Do not add too many admonitions or everything ends up being a callout.\n\n### Syntax Guidelines\n\n- Wrap text at 80 characters where possible. This helps tremendously in version\n  control. Pre-wrap lines if necessary.\n\n- Put Markdown links on a single line `[link label](target.md#hash)`,\n  even if it violates the guideline of 80 characters per line.\n\n- Avoid breaking lines of code blocks and where Markdown does not allow line\n  breaks, e.g. in Markdown table rows (you can use `\u003cbr\u003e` if really necessary).\n\n- Avoid using `here` as link label. Describe what the link points to instead.\n\n- Avoid overly long link labels, such as entire sentences.\n\n- Use relative links for cross-references to other documentation pages, e.g.\n  `../drivers/js/_index.md` instead of `/3.12/drivers/js/_index.md` or\n  `https://docs.arangodb.com/3.12/drivers/js/`.\n\n- Avoid **bold** and *italic* markup in headlines. If you have to use it, then\n  prefer `**bold**` and `*italic*`  over `__bold__` and `_italic_` because the\n  underscores are preserved in anchor links but asterisks are removed!\n\n- Inline `` `code` `` in headlines is acceptable for code values, and required\n  for startup options because `--` otherwise gets turned into an n-dash.\n\n- `-` is preferred for bullet points in unordered lists over `*`\n\n- Don't use `#` or `===` for level 1 headlines. Every page should only have\n  a single `\u003ch1\u003e` headline, and this is automatically generated from the\n  `title` front matter parameter.\n\n- Use `##` for level 2 headlines, not `---` underlines.\n\n- There should be a blank line above and below fenced code blocks and headlines\n  (except if it is at the top of the document, right after the end of the\n  front matter `---`).\n\n- Use all lowercase languages in fenced code blocks without whitespace before\n  or after the language, and use the following languages in favor of the ones in\n  parentheses for consistency:\n\n  - `` ```py `` (instead of `` ```python ``)\n  - `` ```yaml `` (instead of `` ```yml ``)\n  - `` ```sh `` (instead of `` ```shell ``)\n  - `` ```js `` (instead of `` ```javascript ``)\n  - `` ``` `` (instead of `` ```plain `` or `` ```text ``)\n\n- Use the exact spelling of Enterprise Edition and its features, as well as for\n  all other terms coined by ArangoDB:\n  - _EnterpriseGraphs_\n  - _SmartGraphs_, _Disjoint SmartGraphs_\n  - _SmartGraphs using SatelliteCollection_, not ~~Hybrid SmartGraphs~~\n  - _SmartJoins_\n  - _OneShard_\n  - _Community Edition_\n  - _Enterprise Edition_\n  - _DB-Server_, not ~~dbserver~~, ~~db-server~~, ~~DBserver~~ (unless it is a code value)\n  - _Coordinator_ (uppercase C)\n  - _Agent_, _Agency_ (uppercase A)\n  - _ArangoGraph Insights Platform_ and _ArangoGraph_ for short, but not\n    ~~Oasis~~, ~~ArangoDB Oasis~~, or ~~ArangoDB Cloud~~\n  - _Deployment mode_ (single server, cluster, etc.), not ~~deployment type~~\n\n- Never capitalize the names of executables or code values, e.g. write\n  _arangosh_ instead of _Arangosh_.\n\n- Do not write TODOs right into the content and avoid using\n  `\u003c!-- HTML comments --\u003e`. Use `{{\u003c comment \u003e}}...{{\u003c /comment \u003e}}` instead.\n\n### Add links\n\nFor external links, use standard Markdown. Clicking these links automatically\nopens them in a new tab:\n\n```markdown\n[ArangoGraph Insights Platform](https://dashboard.arangodb.cloud)\n```\n\nFor internal links, use relative paths to the Markdown files. Always link to\nfiles, not folders (e.g. `../graphs/_index.md` instead of `../graphs/`).\nThis way, links can be followed in tools like Visual Studio Code and on GitHub.\n\n```markdown\n[Graphs](../graphs/_index.md)\n```\n\nFor anchor links, append `#fragment-identifier` to the path if the content is\nin a different file, or use the fragment ID only to link to a headline in the\nsame file:\n\n```markdown\nSee [Named Graphs](#named-graphs)\n```\n\n### Version Remarks\n\nThe main page about a new feature should indicate the version the feature was\nadded in, as shown below:\n\n```markdown\n---\ntitle: New feature\n...\n---\n\u003csmall\u003eIntroduced in: v3.12.0\u003c/small\u003e\n\n...\n```\n\nSimilarly, the remark should be added if only a section is added to an existing\npage, as shown below:\n\n```markdown\n## Existing feature\n\n...\n\n### New feature section\n\n\u003csmall\u003eIntroduced in: v3.12.0\u003c/small\u003e\n\n...\n```\n\nThe value `v3.12.0` implies that all later versions also have this feature\n(3.12.1, 3.12.2, etc., as well as 4.0.0 and later). If this is not the case,\nthen also mention the other relevant versions. For example, if a feature is\nadded to 3.11.5 and 3.12.2, then write the following in the 3.12 documentation:\n\n```markdown\n\u003csmall\u003eIntroduced in: v3.11.5, v3.12.2\u003c/small\u003e\n```\n\nAll later documentation versions should use a copy of the content, as thus the\n4.0 documentation would contain the same.\n\nIn the 3.11 documentation, only mention versions up to this documentation version\n(excluding 3.12 and later in this example), pretending no later version exists\nto be consistent with the rest of the 3.11 documentation and to avoid additional\nmaintenance burdens:\n\n```markdown\n\u003csmall\u003eIntroduced in: v3.11.5\u003c/small\u003e\n```\n\nNew options in the JavaScript and HTTP APIs are covered by the release notes,\nbut if new options are added mid-release (not in the `x.x.0` release but a later\nbugfix version), then this should be pointed out as follows:\n\n```markdown\n- `existingOption` (number, _optional_): ...\n- `newOption` (string, _optional_): ... (introduced in v3.11.5, v3.12.2).\n```\n\nYou may also add a remark if an existing feature or option is significantly\nextended by a new (sub-)option in a `x.x.0` release.\n\nWhile version remarks are mostly `Introduced in: ...`, you can also mark\ndeprecated features in the same manner with `Deprecated in: ...`.\n\n### Edition Remarks\n\nPages and sections about Enterprise Edition features should indicate that the\nEnterprise Edition is required using a hint box. Use the following include in\nthe general case:\n\n```markdown\n{{\u003c tag \"ArangoDB Enterprise Edition\" \"ArangoGraph\" \u003e}}\n```\n\nThis shortcode should be placed immediately after a headline, before any version\nremarks (`\u003csmall\u003eIntroduced in: ...\u003c/small\u003e`).\n\nTo tag options in lists, place the shortcode as follows:\n\n```markdown\n- **optionName** (data type):\n\n  {{\u003c tag \"ArangoDB Enterprise Edition\" \"ArangoGraph\" \u003e}}\n\n  Version remarks and description of the option\n```\n\nMost Enterprise Edition features are also available in ArangoGraph, but some\nfeatures are not or in a different form (e.g. Hot Backup). If a feature\nis not available in ArangoGraph, use the following include instead:\n\n```markdown\n{{\u003c tag \"ArangoDB Enterprise Enterprise\" \u003e}}\n```\n\nIn the release notes, add the following at the end of a section about a new\nEnterprise Edition feature:\n\n```markdown\nThis feature is only available in the Enterprise Edition.\n```\n\nHTTP API options, that is options described in an `` ```openapi `` code block,\nshould have a remark as follows if they are only available in the Enterprise Edition:\n\n```markdown\n- `enterpriseOption` (boolean, _optional_): ...\n  (Enterprise Edition only).\n```\n\nIf there are both a version remark and an Enterprise Edition remark, use:\n\n```markdown\n- `enterpriseOption` (boolean, _optional_): ...\n  (introduced in v3.11.5 and v3.12.2, Enterprise Edition only).\n```\n\n### Add lead paragraphs\n\nA lead paragraph is the opening paragraph of a written work that summarizes its\nmain ideas. Only few pages have one so far, but new content should be written\nwith such a brief description. It is supposed to clarify the scope of the\narticle so that the reader can quickly assess whether the following information\nis of relevance, but also acts as an introduction.\n\nYou can set the lead paragraph via the `description` parameter in the\nfront matter of a page:\n\n```markdown\n---\ntitle: Feature X\ndescription: \u003e-\n  You can do this and that with X, and it is ideal to solve problem Y\n---\n...\n```\n\nThe lead paragraph text should end without a period, contain no links, and\nusually avoid other markup as well. However, **bold**, _italic_, and\n`inline code` are acceptable.\n\n### Add a page or section\n\nStart off by finding a file name. It should be:\n\n- All lower-case\n- Use hyphen-minus `-` instead of spaces\n- Be very short but descriptive\n- Follow the patterns of existing files\n\nNote that the file name is independent of what will show in the navigation or\nwhat will be used as headline for that page. The file name will be used as\npart of the final URL, however. For example, `3.12/aql/examples.md` will become\n`http://docs.arangodb.com/3.12/aql/examples/`.\n\nCreate a new file with the file name and a `.md` file extension. Open the file\nin a text editor (Visual Studio Code is recommended). Add the following\nfront matter:\n\n```yaml\n---\ntitle: The level 1 headline\ndescription: \u003e-\n  A meaningful description of the page\nmenuTitle: Short navigation menu title\nweight: 42 # controls navigation position within the current section (low to high)\n---\n```\n\nAdd the actual content formatted in Markdown syntax below the front matter.\n\n### Rename a page or section\n\nNetlify supports server-side redirects configured with a text file\n([documentation](https://docs.netlify.com/routing/redirects/#syntax-for-the-redirects-file)).\nThis is helpful when renaming folders with many subfolders and files because\nthere is support for splatting and placeholders (but not regular expressions). See\n[Redirect options](https://docs.netlify.com/routing/redirects/redirect-options/)\nfor details. The configuration file is `site/static/_redirects`.\n\nOtherwise, the following steps are necessary for moving content:\n1. Rename file or folder\n2. Set up `aliases` via the front matter as needed\n3. Adjust `weight` of pages in the front matter if necessary\n4. Update cross-references in all of the content to use the new file path\n\nThe URL of a page is derived from the file name and the parent folders, with\nspecial handling for sections (folders with a `_index.md` file).\nFor example, `3.12/aql/operators.md` becomes the URL path `/3.12/aql/operators/`,\nand `3.12/aql/functions/_index.md` becomes `/3.12/aql/functions/`.\n\nIf you rename a file, from `section/old-name.md` to `section/new-name.md` for\ninstance, make sure to add a redirect for the old URL by adding the following to\nthe front matter of `section/new-name.md`:\n\n```yaml\naliases:\n  - old-name\n```\n\nDon't forget to update any references to the old file in the content to the new\npath.\n\nIf you move a file from one folder to another, from `old/file.md` to `new/file.md`\nfor instance, use a relative path as shown below:\n\n```yaml\naliases:\n  - ../old/file\n```\n\nIf you rename a folder, from `old/` to `new/` for instance, add the following\nfront matter to `new/_index.md`:\n\n```yaml\naliases:\n  - old\n```\n\nFor aliases in `_index.md` files, think of the folder they are in as a file.\nIn the above example, the folder is `new/`. Treating it like the file that\ndefines the page means that the alias `old` is relative to its parent folder\n(here: the root folder of the content, `site/content/`). Therefore, the alias\nneeds to be `old`, not `../old`.\n\nNote that you need to set up aliases for all files in `new/` so that every URL\nwhich includes the old folder name redirects to the corresponding new URL.\nFor example, for a file `new/other.md` (previously `old/other.md`), add the\nfollowing:\n\n```yaml\naliases:\n  - ../old/other\n```\n\nAliases create HTML files with client-side redirects before any content is\nrendered to HTML, which means that aliases can get overwritten by content files.\nIf this is not a mistake, the affected aliases should be removed.\n\n### Disable or limit the table of contents\n\nThe table of contents (ToC) or \"On this page\" on the right-hand side at the top\nof a page lists the headlines if there are at least two headlines on the page\n(excluding the title).\n\nThe ToC can be restricted to a maximum headline level to omit the deeper nested\nheadlines for less clutter:\n\n```yaml\n---\n...\npageToc:\n  maxHeadlineLevel: 3\n---\n```\n\nA setting of `3` means that `\u003ch1\u003e`, `\u003ch2\u003e`, and `\u003ch3\u003e` headlines will be listed\nin the ToC, whereas `\u003ch4\u003e`, `\u003ch5\u003e`, and `\u003ch6\u003e` will be ignored.\n\n### Deprecate a version\n\nWhen an ArangoDB version reaches [End-of-Life](https://www.arangodb.com/subscriptions/end-of-life-notice/),\nits documentation needs to be marked as such. For the respective version, set\nthe `deprecated` attribute to `true` in the `site/data/versions.yaml` file:\n\n```diff\n - name: \"3.10\"\n   version: \"3.10.9\"\n   alias: \"3.10\"\n-  deprecated: false\n+  deprecated: true\n```\n\nIt makes a warning show at the top of every page for that version.\n\n### Add a new version\n\n1. In the `site/data/versions.yaml` file, add a new entry for the version you\n   want to add. Example:\n\n   ```diff\n   +- name: \"4.0\"\n   +  version: \"4.0.0\"\n   +  alias: \"4.0\"\n   +  deprecated: false\n   +\n    - name: \"3.12\"\n      version: \"3.12.0\"\n      alias: \"devel\"\n      deprecated: false\n   ```\n\n2. Near the top of the `.circleci/config.yml` file under `parameters`, find the\n   last entry with the format `arangodb-X_XX` where `X_XX` is a version number\n   like `3_12`, so `arangodb-3_12` for example. Duplicate the block and adjust\n   the version number. Example:\n\n   ```diff\n      arangodb-3_12:\n        type: string\n        default: \"undefined\"\n   +\n   +  arangodb-4_0:\n   +    type: string\n   +    default: \"undefined\"\n   ```\n\n   Near the end of the file under `jobs.generate-config.steps[0].run.command`,\n   find the line of code that calls `python3 generate_config.py`. In one of the\n   following lines, a parameter for every version is passed as argument. Add one\n   for the new version. Example:\n\n   ```diff\n                python3 generate_config.py \\\n                  --workflow \u003c\u003c pipeline.parameters.workflow \u003e\u003e \\\n   -              --arangodb-branches \u003c\u003c pipeline.parameters.arangodb-3_11 \u003e\u003e \u003c\u003c pipeline.parameters.arangodb-3_12 \u003e\u003e \\\n   +              --arangodb-branches \u003c\u003c pipeline.parameters.arangodb-3_11 \u003e\u003e \u003c\u003c pipeline.parameters.arangodb-3_12 \u003e\u003e \u003c\u003c pipeline.parameters.arangodb-4_0 \u003e\u003e \\\n   ```\n\n3. In the `toolchain/docker/amd64/docker-compose.yml` file, add an entry under\n   `services.toolchain.volumes` for the new version. Simply increment the value\n   after `:-/tmp/`. Example:\n\n   ```diff\n          - ${ARANGODB_SRC_3_12:-/tmp/2}:/tmp/3.12\n   +      - ${ARANGODB_SRC_4_0:-/tmp/3}:/tmp/4.0\n   ```\n\n   Under `services.toolchain.environment`, you need to add two different entries\n   for the new version. Example:\n\n   ```diff\n          ARANGODB_SRC_3_11: ${ARANGODB_SRC_3_11}\n          ARANGODB_SRC_3_12: ${ARANGODB_SRC_3_12}\n   +      ARANGODB_SRC_4_0: ${ARANGODB_SRC_4_0}\n          ARANGODB_BRANCH_3_11: ${ARANGODB_BRANCH_3_11}\n          ARANGODB_BRANCH_3_12: ${ARANGODB_BRANCH_3_12}\n   +      ARANGODB_BRANCH_4_0: ${ARANGODB_BRANCH_4_0}\n   ```\n\n   The same changes are required in the\n   `toolchain/docker/arm64/docker-compose.yml` file.\n\n4. In the `toolchain/docker/config.yaml` file, add an entry for the new version.\n   Example:\n\n   ```diff\n      - image: ${ARANGODB_BRANCH_3_12_IMAGE}\n        version: ${ARANGODB_BRANCH_3_12_VERSION}\n   +\n   +  - image: ${ARANGODB_BRANCH_4_0_IMAGE}\n   +    version: ${ARANGODB_BRANCH_4_0_VERSION}\n   ```\n\n5. In the `toolchain/scripts/toolchain.sh` file, find the code that accesses\n   environment variables with the format `$ARANGODB_BRANCH_X_XX` where `X_XX`\n   is a version number like `3_12`, so `$ARANGODB_BRANCH_3_12` for instance.\n   Duplicate the block of an existing version and adjust all version numbers.\n   Example:\n\n   ```diff\n    if [ \"$ARANGODB_BRANCH_3_12\" != \"\" ] ; then\n          export ARANGODB_BRANCH_3_12_IMAGE=\"$ARANGODB_BRANCH_3_12\"\n          export ARANGODB_BRANCH_3_12_VERSION=\"3.12\"\n    fi\n    \n   +if [ \"$ARANGODB_BRANCH_4_0\" != \"\" ] ; then\n   +      export ARANGODB_BRANCH_4_0_IMAGE=\"$ARANGODB_BRANCH_4_0\"\n   +      export ARANGODB_BRANCH_4_0_VERSION=\"4.0\"\n   +fi\n   ```\n\n6. In the `site/data` folder, create a new folder with the short version number\n   as the name, e.g. `4.0`. In the new `site/data/4.0` folder, create a\n   `cache.json` file with the following content:\n\n   ```json\n   {}\n   ```\n\n   Add this untracked file to Git!\n\n7. Duplicate the folder of the most recent version in `site/content`, e.g.\n   the `3.12` folder, and rename the copy to the new version, e.g. `4.0`.\n\n   The `menuTitle` in the front matter of the version homepage, e.g.\n   `site/content/4.0/_index.md`, needs to adjusted to the new version,\n   like `menuTitle: '4.0'`.\n\n   In the folder for release notes, e.g. `site/content/4.0/release-notes/`,\n   duplicate the folder of the most recent version, e.g. `version-3.12`, and\n   rename it, e.g. to `version-4.0`. In this folder, rename the files to replace\n   the old with the new version number, e.g. `api-changes-in-3-12.md` to\n   `api-changes-in-4-0.md` and so on.\n   \n   In the `_index.md` file in the folder, e.g.\n   `site/content/4.0/release-notes/version-4.0/_index.md`, you need to replace\n   the version numbers in the front matter and links. You also need to adjust\n   the `weight` in the front matter. Decrement the value by one to make the new\n   version appear before the existing versions, but make sure that it is greater\n   than `0`, which may require adjusting the weights in all of the section files.\n\n   In the other files of the release notes, remove the version-specific content\n   and only leave the front matter, introductions, and headlines that are\n   commonly used across different versions in the release notes. Adjust the\n   version numbers in the front matter and content.\n\n   Search the entire version folder, e.g. `site/content/4.0/`, for links that\n   are meant to point to the release notes of the own version, but which are\n   still pointing to the version the content has been copied from. For example,\n   if you duplicated the `3.12` folder, search the `4.0` folder for\n   `version-3.12/`. You should find links to `version-3.12/known-issues-in-3-12.md`\n   that need to be updated to `version-4.0/known-issues-in-4-0.md`.\n\n   In the release notes root file, e.g. `site/content/4.0/release-notes/_index.md`,\n   add the links for the new version following the existing pattern. Do this\n   after updating the links to the known issues so that you don't accidentally\n   change the 3.12 link in the release notes root file.\n\n   In the _Highlights by Version_ page, e.g.\n   `site/content/4.0/introduction/features/highlights-by-version.md`, add a\n   section for the new version including a link to the release notes.\n\n   Add the new, untracked files to Git!\n\n8. In the `PULL_REQUEST_TEMPLATE.md` file, add a new line for the new version.\n   Example:\n\n   ```diff\n    - 3.12: \n   +- 4.0: \n   ```\n\n   Stage all changes and commit them. Open a pull request (PR) on GitHub. You only\n   need to specify a Docker image or PR link for `- 4.0: ` if you plan to use\n   the `/generate` or `/generate-commit` command to re-generate the examples.\n   If you follow the next step, the example generation is run manually along\n   with some other generators, so using the commands shouldn't be necessary.\n\n   Expect the plain build to fail for the time being because of missing data files.\n\n9. You can use CircleCI to initially generate the data files for the new version,\n   like the startup option dumps. You can also populate the example cache at the\n   same time.\n\n   Before you continue, make sure there are no conflicts in the PR with the\n   `main` branch. The CircleCI workflow will otherwise create a merge commit\n   favoring the `main` branch (in order to update the cache file but also\n   affecting other files), and this can cause e.g. the `versions.yaml` file to\n   get reverted in case of a conflict. The toolchain would then be unaware of\n   the newly added version.   \n   \n   In CircleCI at \u003chttps://app.circleci.com/pipelines/github/arangodb/docs-hugo\u003e,\n   select the branch of your PR and click **Trigger Pipeline**.\n   Enter the parameters similar to this example:\n\n   | Type | Name | Value |\n   |:-----|:-----|:------|\n   | string | `workflow` | `generate` |\n   | 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`) |\n   | string | `generators` | `examples metrics error-codes optimizer options` |\n   | string | `deploy-url` | `deploy-preview-{PR-number}` with the number of the docs PR |\n   | boolean | `commit-generated` | `true` |\n\n   Approve the workflow in CircleCI. After a successful run, you should see a\n   commit in the docs PR with the updated data files, as well as an updated\n   example cache file. The plain build should no longer fail and provide you\n   with a Netlify preview.\n\n### Remove a version\n\nThe process is similar to [adding a version](#add-a-new-version) but you need to\nundo the changes.\n\n### Change the stable version\n\nFor example, if the current stable version is 3.11 and the devel version is 3.12,\nthe `site/data/versions.yaml` file may look like this:\n\n```yaml\n- name: \"4.0\"\n  version: \"4.0.0\"\n  alias: \"4.0\"\n  deprecated: false\n\n- name: \"3.12\"\n  version: \"3.12.0\"\n  alias: \"devel\"\n  deprecated: false\n\n- name: \"3.11\"\n  version: \"3.11.4\"\n  alias: \"stable\"\n  deprecated: false\n```\n\nTo make 3.12 the new stable version, you need to set `alias` to `\"stable\"` for\nthe 3.12 entry. As there can only be a single stable version (in the\ndocumentation sense), the `alias` value of the former stable version needs to be\nchanged. In this example, it is the 3.11 entry where you need to change `alias`\nto the version `name`, which is `\"3.11\"` in this case. Finally, you need to\nre-assign the `\"devel\"` alias to the version that comes after the new stable\nversion. In this example, you need to adjust the `alias` of the 4.0 entry.\nThe final configuration would then look lik this:\n\n```yaml\n- name: \"4.0\"\n  version: \"4.0.0\"\n  alias: \"devel\"   # was \"4.0\"\n  deprecated: false\n\n- name: \"3.12\"\n  version: \"3.12.0\"\n  alias: \"stable\"  # was \"devel\"\n  deprecated: false\n\n- name: \"3.11\"\n  version: \"3.11.4\"\n  alias: \"3.11\"    # was \"stable\"\n  deprecated: false\n```\n\n### Add a new arangosh example\n\nA complete example:\n\n````markdown\n```js\n---\nname: ensureUniquePersistentSingle\ndescription: Create a unique persistent index on a single document attribute\n---\n~db._create(\"ids\");\ndb.ids.ensureIndex({ type: \"persistent\", fields: [ \"myId\" ], unique: true });\ndb.ids.save({ \"myId\": 123 });\ndb.ids.save({ \n  \"myId\": 123\n}); // xpError(ERROR_ARANGO_UNIQUE_CONSTRAINT_VIOLATED)\n~db._drop(\"ids\");\n```\n````\n\nGroups of examples should have the same name prefix.\n\nIf an example needs to be run against an ArangoDB cluster instead of a\nsingle server (default), then add the following front matter option:\n\n```yaml\ntype: cluster\n```\n\nTo not render the transcript comprised of input and output but only the input\nor output, set the `render` front matter option:\n\n```yaml\nrender: input # or 'output', default 'input/output'\n```\n\nAfter the front matter, you can write the JavaScript code for arangosh:\n\n```js\ndb._create(\"collection\");\ndb.collection.save({ _key: \"foo\", value: 123 });\ndb._query(`FOR doc IN collection RETURN doc.value`).toArray();\ndb._drop(\"collection\");\n```\n\nStatements can span multiple lines:\n\n```js\ndb.collection.save([\n  { multiple: true },\n  { lines: true }\n]);\n```\n\nThe statements as well as the results will be visible in the example transcript.\nTo hide certain statements from the output, e.g. for setup/teardown that is not\nrelevant for the example, you can use a leading tilde `~` to suppress individual\nlines:\n\n```js\n~db._create(\"collection\");\ndb.collection.save({ _key: \"foo\" });\n~db._drop(\"collection\");\n```\n\nExamples need to remove the collections and Views they create. Not dropping them\nwill raise an error unless they are specifically exempt:\n\n```js\n~db._create(\"collection\");\n~db._createView(\"view\", \"arangosearch\", {...});\ndb.collection.save({...});\n~addIgnoreView(\"view\");\n~addIgnoreCollection(\"collection\");\n```\n\nThis is helpful for creating collections and Views once, using them in multiple\nexamples, and finally dropping them instead of having to create and drop them\nin each example.\n\n\u003c!-- TODO: Does Hugo guarantee to invoke the render hooks one after another,\ntop to bottom of a page, and do this serially?\n\nYou need to choose the names for the examples so that they are alphabetically\nsortable to have them execute in the correct order.\n--\u003e\n\nThe last example of the series should undo the ignore to catch unintended leftovers:\n\n```js\n~removeIgnoreCollection(\"collection\");\n~removeIgnoreView(\"view\");\n~db._dropView(\"view\");\n~db._drop(\"collection\");\n```\n\nNote that a series of examples needs to be contained within a single file.\n\nIf a statement is expected to fail (e.g. to demonstrate the error case), then\nthis has to be indicated with a special JavaScript comment:\n\n```js\ndb._document(\"collection/does_not_exist\"); // xpError(ERROR_ARANGO_DOCUMENT_NOT_FOUND)\n```\n\nThis will make the example generation continue despite the error. See\n[Error codes and meanings](https://docs.arangodb.com/3.12/develop/error-codes-and-meanings/)\nfor a list of all error codes and their names. If a unexpected error is raised,\nthen the example generation will abort with an error.\n\nEvery backslash in a query needs to be escaped with another backslash, i.e.\nJSON escape sequences require two backslashes, and literal backslashes four:\n\n```js\ndb._query(`RETURN REGEX_SPLIT(\"foo\\\\t bar\\\\r baz\\\\n foob\", \"\\\\\\\\s+|(?:b\\\\\\\\b)\")`).toArray();\n```\n\nThis does not apply to backslashes in bind variables:\n\n```js\ndb._query(`RETURN REGEX_SPLIT(@t, @r)`, {t: \"foo\\t bar\\r baz\\n foob\", r: \"\\\\s+|(?:b\\\\b)\"}).toArray();\n```\n\n### Add a new AQL example\n\nComplete example:\n\n````yaml\n```aql\n---\nname: joinTuples\ndescription:\nbindVars: {\n  friend: \"friend\"\n}\ndataset: joinSampleDataset\nexplain: true\n---\nFOR u IN users\n  FILTER u.active == true\n  LIMIT 0, 4\n  FOR f IN relations\n    FILTER f.type == @friend \u0026\u0026 f.friendOf == u.userId\n    RETURN {\n      \"user\" : u.name,\n      \"friendId\" : f.thisUser\n    }\n```\n````\n\nAn example can optionally specify a `dataset` in the front matter that will be\nloaded before the query is run:\n\n```yaml\ndataset: name_of_dataset\n```\n\nSee [datasets.json](toolchain/arangoproxy/internal/utils/datasets.json)\nfor the available datasets.\n\nTo get the query explain output including the execution plan instead of the\nactual query result, you can optionally specify the `explain` option in the\nfront matter:\n\n```yaml\nexplain: true\n```\n\nThen the actual AQL query follows, e.g.\n\n```\nFOR i IN 1..3\n  RETURN i\n```\n\nThe query can optionally use bind parameters that can be set via the `bindVars`\noption in the front matter:\n\n```yaml\n---\n...\nbindVars:\n  '@coll': products\n  attr:\n    - title\n    - de\n# or using JSON notation:\n#bindVars: { \"@coll\": \"products\", \"attr\": [\"title\", \"de\"] }\n---\nFOR doc IN @@coll\n  RETURN doc.@attr\n```\n\n### Add a new OpenAPI endpoint description\n\nUsed to describe an HTTP REST API endpoint using the\n[OpenAPI Specification](https://spec.openapis.org/oas/latest.html) standard in\nversion 3.1.0.\n\nThe content inside the codeblock is a standard OpenAPI endpoint description in\nYAML format for a single ArangoDB endpoint. The headline above the code block is\nalso used as the endpoint summary automatically:\n\n````yaml\n### Get the service README\n\n```openapi\npaths:\n  /_api/foxx/readme:\n    get:\n      operationId: getFoxxReadme\n      description: |\n        Fetches the service's README or README.md file's contents if any.\n      parameters:\n        - name: mount\n          in: query\n          required: true\n          description: |\n            Mount path of the installed service.\n          schema:\n            type: string\n      responses:\n        '200':\n          description: |\n            Returned if the request was successful.\n        '204':\n          description: |\n            Returned if no README file was found.\n      tags:\n        - Foxx\n```\n````\n\nOnly define a single tag in `tags` as this is used to categorize the endpoints.\nSee the [`openapi_tags.yaml`](site/data/openapi_tags.yaml) file for the available\ncategories, or add new ones if necessary.\n\nThe REST HTTP API endpoint descriptions are rendered in the documentation, but\n_arangoproxy_ also converts the YAML to JSON and assembles a single `api-docs.json`\nfile. This file is needed by the web interface for _Swagger UI_.\n\n### Add a new cURL example\n\nComplete example:\n\n````\n```curl\n---\nname: HttpAqlToBase64\ndescription: Encode example credentials using the HTTP API\n---\nvar url = \"/_api/cursor\";\nvar body = { query: `RETURN TO_BASE64(\"user:pass\")` };\nvar response = logCurlRequest('POST', url, body);\nassert(response.code === 201);\nlogJsonResponse(response);\n```\n````\n\nIf an endpoint requires the `_system` database as the context, the URL should be\nset accordingly, e.g. `var url = \"/_db/_system/_api/database\";`. This ensures\nthat the request is issued correctly as the toolchain may process other examples\nthat change the database context simultaneously.\n\nUnlike arangosh examples (`` ```js ``), requests and responses\nneed to be output explicitly by calling one of the following functions:\n\n- `logCurlRequest(method, url, body) → response`: make and output an HTTP request\n- `logCurlRequestRaw(method, url, body) → response`: make and output an HTTP\n  request without code highlighting\n- `logCurlRequestPlain(method, url, body) → response`: make and output an HTTP\n  request, with the payload decoded (new lines instead of `\\r\\n` etc.). Useful\n  for formatting complex requests.\n- `logJsonResponse(response)`: output a JSON server reply (fails on invalid JSON)\n- `logJsonLResponse(response)`: output a JSONL server reply (fails on invalid JSON)\n- `logRawResponse(response)`: output plaintext response (do not use for JSON replies;\n  can be used for endpoint calls that return an empty body to output the headers)\n- `logPlainResponse(response)`: output decoded response (new lines instead of\n  `\\r\\n` etc.). Useful for formatting complex responses, like from batch requests.\n- `logHtmlResponse(response)`: output HTML\n- `logErrorResponse(response)`: dump reply to error log for testing\n  (makes example generation fail)\n\nTo test whether requests and replies are as expected, you can add\n`assert(expression)` calls. Expressions that evaluate to false will make the\nexample generation fail. You can inspect the CircleCI logs for details.\n\nTo use specialized assertions, you need to import them from\n[jsunity](https://github.com/arangodb/arangodb/blob/devel/js/common/modules/jsunity/jsunity.js),\nlike `assertTrue()`, `assertEqual()`, `assertTypeOf()`, `assertUndefined()`, etc.\n\n```js\nvar assertTypeOf = require(\"jsunity\").jsUnity.assertions.assertTypeOf;\nassertTypeOf(\"string\", response.parsedBody.name);\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farangodb%2Fdocs-hugo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farangodb%2Fdocs-hugo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farangodb%2Fdocs-hugo/lists"}