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."
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.
hugo new content
. Right now, the only supported archetype is the default one. Note: We might want to add additional archetypes in the future because most of our pages contain additional meta data properties like linkTitle
. /develop
, /integrate
, and /operate
single.html
and list.html
. The single
template is used to render a discrete page. The list
template is used to render a collection of related pages (e.g., all sub-pages).npm
).You will need the following tools to build the site locally:
python3
: Python >= 3.8.node
and npm
: Node.js >= 19.7.0, and the Node.js package manager >= 9.5.0.hugo
: Hugo site generator, v0.111.2; the extended edition.make
: To run the makefile.git
: To manage the source code of this repo.The site can be built using the command make all
. Here is what's executed:
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.
The build pipeline that is defined within .github/workflows/main.yml
builds the documentation and uploads it into a GCS bucket:
make all
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:
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)
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" >}} {{< image filename="/images/rc/icon-database-update-status-active.png#no-click" alt="Active database status" class="inline" >}}
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" -}}
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
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:
Copy your font files to the fonts folder static/fonts
.
Ensure that the font is loaded by adding it to the partial layouts/partials/fonts.html
. This partial defines the font using a style sheet and ensures that the font resources are pre-loaded.
Here is an example that shows how to define the font face 'Geist Mono' with a regular font weight:
@font-face {
font-family: 'Geist Mono';
src: url('{{ $basePath }}/fonts/GeistMono-Regular.woff2') format('woff2');
font-weight: 400;
font-style: normal;
font-display: swap;
}
Make your font available via Tailwind by adding it to the tailwind.config.js
file.
module.exports = {
content: ["content/**/*.md", "layouts/**/*.html", "./tailwindcss.whitelist.txt"],
theme: {
extend: {
fontFamily: {
sans: [ 'Space Grotesk', ...defaultTheme.fontFamily.sans ],
mono: [ 'Space Mono', 'SF Mono', ...defaultTheme.fontFamily.mono ],
monogeist: ['Geist Mono', ...defaultTheme.fontFamily.mono ],
},
...
Use a font-*
CSS class within HTML or your style sheets, whereby the *
needs to be substituted with one of the Tailwind fonts that you defined in the Tailwind configuration file (tailwind.config.js
).
Here is an example how to use font-monogeist
in the global CSS file assets/css/index.css
to change the font of code blocks:
.prose pre > code {
@apply bg-none font-monogeist;
}
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.