Home

Awesome

Redis Docs

OPEN SOURCE LICENSE VS. TRADEMARKS. The three-clause BSD license gives you the right to redistribute and use the software in source and binary forms, with or without modification, under certain conditions. However, open source licenses like the three-clause BSD license do not address trademarks. For further details please read the Redis Trademark Policy."

A note for Issue and PR submitters

PRs are merged first to the main branch of this repo. Periodically, the docs team will merge main into latest, which will make the changes visible on the docs site. Please be patient, as there may be a lag of several days before main is merged into latest. If you want to see your changes before they're merged to latest, you can see them on https://redis.io/docs/staging/dev/. If your PR is urgent, let the docs team know in the PR comments, and we will do our best to accommodate.

Site template files and folders

Requirements

You will need the following tools to build the site locally:

Build script and data files

The site can be built using the command make all. Here is what's executed:

  1. Clean the current folder by deleting the generated output of a previous build.
  2. Install the necessary Node.js and Python dependencies.
  3. Build the components that were fetched from external Github repositories (e.g., client examples). This fetches source code files and generates data files.
  4. Execute the hugo command to generate the HTML pages. The build result can be found within the folder /public.

The command make serve performs the same steps, but serves the web pages on the local host for development purposes.

The Makefile contains details about the executed commands.

N.B. once you've built the site once, you can continuing working without rebuilding every time you make a change. Use hugo serve to serve the docs locally. The only time you really need to rebuild the site locally is when new code samples need to be pulled from the client sites.

Build pipeline

The build pipeline that is defined within .github/workflows/main.yml builds the documentation and uploads it into a GCS bucket:

  1. Install Hugo
  2. Check the branch out
  3. Perform the build as stated before by using make all
  4. Install the Google Cloud CLI
  5. Authenticate to the GCS bucket
  6. Validate the branch name
  7. Sync the branch with a GCS folder

Hugo specifics

Relative links

We are using the following syntax for Hugo relrefs:

[Link title]({{< relref "link relative to the site's base url" >}})

Here is an example:

[Data structure store]({{< relref "/develop/get-started/data-store" >}})

It's strongly advised to use relref because it provides the following advantages:

  1. Links are checked at build time. Any broken references within the site are reported, stopping the build.
  2. References are prefixed with the site's base URL, which means that they work in builds with a different base URL.

The following needs to be taken into account when using relref: The reference /develop/get-started/data-store and /develop/get-started/data-store/ aren't the same. You must use the trailing slash if the referenced article is an _index.md file within a folder (e.g., .../data-store/ for .../data-store/_index.md). Otherwise, you should not use the trailing slash (e.g., .../get-started/data-store.md).

RelRefs with dots (.) and hashtags (#) in the reference name, such as /commands/ft.create or /develop/data-types/timeseries/configuration#compaction_policy, don't seem to work. Please use the {{< baseurl >}} as a workaround in that case. Here are a couple of examples:

[compaction]({{< baseurl >}}/develop/data-types/timeseries/configuration#compaction_policy)
[FT.CREATE]({{< baseurl >}}/commands/ft.create)

Images

The image shortcode doesn't need to be closed anymore. Here is an example;

{{< image filename="/images/rc/icon-database-update-status-pending.png" alt="Database update" >}}

The filename property value can be any file name path which is relative to the site's base path.

We added a new property class which allows you to override the CSS class of the image. Images have by default a block display in Tailwind. You can change this by setting the class property to inline. The following example shows two images that are in a single line:

{{< image filename="/images/rc/icon-database-update-status-pending.png#no-click" alt="Pending database status" class="inline" >}} &nbsp; {{< image filename="/images/rc/icon-database-update-status-active.png#no-click" alt="Active database status" class="inline" >}}

Templating

Variables are scoped in the context of their block. Overriding a variable within an if block doesn't change the variable value as soon as you leave that block. This is a specific limitation of the Go templating language.

The following will give you the / outside of the condition block if the path was initially set to /:

{{ $path := $parsed.Path }}
{{ if (eq $path "/") }}
	{{ $path = "" }}
{{ end }}

{{- $path -}}

The solution is to use a scratchpad for storing the 'global' state:

{{ $path := $parsed.Path }}
{{ if (eq $path "/") }}
	{{ .Scratch.Set "path" ""}}
{{ else }}
    {{ .Scratch.Set "path" $path}}
{{ end }}

{{- .Scratch.Get "path" -}}

Child pages

The redis.io template adds a list of links to child pages at the bottom of each section page. You can prevent this by adding the following front matter property:

hideListLinks: true

Tailwind specifics

Fonts

The fonts are located in the folder static/fonts. This folder contains typically file of the formats ttf, woff, or woff2. You can perform the following steps to add a font:

Troubleshooting

NIL pointer error when rendering a section

You might sometimes see the following error message:

nil pointer evaluating page.Page.Params

This happened for us when Hugo executed the bannerText logic, which inspected all parent pages by checking if they have a banner text set. The problem was that one of the parent folders was missing an _index.md file, which meant the folder couldn't be identified as a page. The solution was to add an _index.md file to the folder that didn't have it yet.

<!-- -->