Dgraph Documentation

To read the official Dgraph documentation that is published from this repository, please see https://dgraph.io/docs/.

Contribution guidelines

As a contributor to Dgraph documentation, we ask that you do the following:

• Label your PR for easy management: Your PR title should be in the following format: Topic (area): details. The topic is either "Docs", "Nav" (aka, navigation), or "Chore" (for build fixes, cherry-picks, etc). The area is the feature (i.e. "GraphQL"), area of the docs (i.e., "Deployment"), or "Other" (for typo fixes and other bugfix PRs). So, example PR names include: Docs(GraphQL): Document the @deprecated annotation or Chore(Other): cherry-pick updates from main to release/v20.11
• Develop in the main branch first: Make any changes applicable to the current (recently-released) version of Dgraph in the main branch first, and then cherry-pick those changes to the correct release branch (for example, release/v20.11).

Exception: Changes that only apply to older Dgraph versions (for example release/v20.07), can occur directly in a release branch, but will not be cherry-picked forward.

• Note planned cherry-pick(s) in your PR description: If you are creating a PR in main and you know it needs to be cherry-picked to a release branch, please mention that in your PR description (for example: "cherry-pick to v20.07"). Cherry-pick PRs should reference the original PR.

• Link to discuss.dgraph.io posts when applicable: If your PR is based on discussions on Discuss, feel free to include a link to the relevant discussion in your PR description.

• Technical writing style: As much as possible, please follow technical writing style conventions (More on this below).

• (Dgraph core team only): Include the ID of any issues/tickets related to your PR in the description (i.e., "Fixes DGRAPH-12345" or "Per DGRAPH-54321").

Technical writing style

Dgraph Labs uses a style guide for our documentation so that we can make it as easy to understand as possible. The Dgraph Style Guide is a concise style reference for our documentation, but it isn't comprehensive. For anything not found in our style guide, use Google's Developer Docs Style Guide.

Style tips for machine-translatable docs!

Making our documentation easy to understand includes optimizing it for client-side machine translation into other languages. To help with this, please see the following technical writing style tips:

• Generally, use the second person ("you") rather than the third-person ("the developer") when addressing the reader.
• Always use the third person when describing Dgraph database or features (avoid "this lets us" in favor of "this lets Dgraph").
• Write in present-tense, active voice when you can.
• Prefer simple sentences to complex and complex-compound sentences.

Note: Please don't let these style conventions stop you from creating a PR to share your contribution to Dgraph Docs! PR reviewers can help with style guide issues.

references

Use hugo shortcode for relref.

Example, to reference a term, use a relref to the glossary :

>  [entity]({{< relref "dgraph-glossary.md#entity" >}})

Staging doc updates locally

We use Hugo for our documentation. You can use Hugo to locally stage doc updates before or after creating a PR.

1. Download and install hugo version v0.91 from here.

On mac you may have to remove the quarantine attribute to be able to execute hugo ''' sudo xattr -d com.apple.quarantine path/to/hugo '''

2. Run ./scripts/local.sh and visit http://localhost:1313 to see the documentation site running on your local machine.

(Optional) To run queries within the documentation using a different Dgraph instance, set the DGRAPH_ENDPOINT environment variable before starting the local web server:

DGRAPH_ENDPOINT="http://localhost:8080/query?latency=true" ./scripts/local.sh

Now you can make changes to the docs and see them being updated instantly, thanks to Hugo.

Note: While running locally, the version selector does not work because you need to build the documentation and serve it behind a reverse proxy to have multiple versions. Also, formatting of lists is less fussy when running locally; so please precede lists with a blank line in your PR.

Testing for broken links

We use htmltest to check for broken links in the generated documentation. To test for broken links after building the site:

1. Build the Hugo site:

   hugo --destination=public --baseURL=http://example.com

2. Run htmltest:

   htmltest

   Or combine both steps:

   hugo --destination=public --baseURL=http://example.com && htmltest  2>&1

The htmltest configuration is in .htmltest.yml at the root of the repository. It automatically ignores development-only files like livereload.js and empty hash links used for JavaScript interactions.

Running docs locally with Docker

Make sure you have docker-compose installed.

Run:

sh scripts/docker.sh

Branch

Depending on what branch you are on, some code examples will dynamically change. For example, go-grpc code examples will have different import path depending on the branch name.

Runnable code examples

Some code examples are runnable, allowing for reader interaction with a data set.

Custom example

Pass custom Go-GRPC example to the runnable by passing a customExampleGoGRPC to the runnable shortcode.

{{< runnable
  customExampleGoGRPC="this\nis\nan example"
>}}{
  director(func:allofterms(name, "steven spielberg")) {
    name@en
    director.film (orderdesc: initial_release_date) {
      name@en
      initial_release_date
    }
  }
}
{{< /runnable >}}

Note: Runnable doesn't support passing a multiline string as an argument to a shortcode. Therefore, you have to create the whole custom example in a single line string by replacing newlines with \n.

Hints

Adding New Tabs and Sidebar Menus

To add a new tab and configure its sidebar menu:

1. Add Tab to Navigation

Edit themes/hugo-docs/layouts/partials/topbar.html and add your tab to the $tabs slice:

{{ $tabs := slice 
  (dict "type" "docs" "url" "/dgraph-overview/" "label" "Docs")
  (dict "type" "graphql" "url" "/graphql/" "label" "GraphQL") 
  (dict "type" "learn" "url" "/learn/" "label" "Tutorials")
  (dict "type" "ratel" "url" "/ratel/overview/" "label" "Ratel UI")
  (dict "type" "yourtype" "url" "/your-section/" "label" "Your Tab")
}}

2. Set Page Type and Menu

For each page in your section, add to the frontmatter:

+++
title = "Your Page Title"
type = "yourtype"  # Must match the type in the tab definition
[menu.yourtype]   # Must match the type
  parent = "your-section"
  weight = 1
+++

3. Update Sidebar

Edit themes/hugo-docs/layouts/partials/sidebar.html and add:

{{ if eq $menuType "yourtype" }}
  {{ $menu = .Site.Menus.yourtype }}
{{ end }}

Multi-Version Documentation

This repository uses a build script to generate documentation for multiple versions from different Git branches.

./scripts/build.sh

This builds:

• Latest docs from main branch → /
• Version docs from release branches → /v24.1/, etc.

How It Works

1. Build Script (build.sh) uses Git worktrees to temporarily check out each release branch
2. Hugo builds each version into its own subdirectory with the appropriate base URL
3. Version selector loads available versions from versions.json and displays a dropdown

Configuration

Edit build.sh to add/remove versions:

VERSION_BRANCHES=("main" "release/v24.1")

VERSION_BRANCHES=("release/v25.0" "release/v24.1")

File Structure

layouts/partials/
  └── version-selector.html    # Dropdown component
scripts/
  └── build.sh         # Build script
public/                         # Generated output
  ├── index.html               # Latest docs (main)
  ├── versions.json            # Version metadata
  ├── v24.1/                   # Version 24.1 docs
  └── v24.2/                   # Version 24.2 docs

Version Selector

In layout

{{ partial "version-selector.html" . }}