Skip to content

Latest commit

 

History

History
214 lines (149 loc) · 10.3 KB

README.md

File metadata and controls

214 lines (149 loc) · 10.3 KB
Raw

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

  • /archetypes: A Markdown file needs to have some front matter. An archetype defines which front matter is used when using 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.
  • /content: This folder contains the markdown files. We will have the subfolders like /develop, /integrate, and /operate
  • /assets: CSS files, site-wide icons, and images.
  • /data: Data files that are accessed by Hugo and rendered with the help of short codes or partials.
  • /layouts/partials: HTML templates that are used across sites. Examples are TOCs, breadcrumbs, or headers.
  • /layouts/$type: Each page type has at least the following templates to implement 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).
  • /layouts/home.html: The home page of the site, that is, the page that is displayed when you open the root path.
  • /layouts/404.html: The default 404 page.
  • /layouts/shortcodes HTML template snippets that you want to leverage within Markdown files. Examples are tabbed code examples or notification blocks.
  • /public: This is the folder that is generated by Hugo. This content needs to be published by site maintainers.
  • /static: Any static files that need to be accessed by the site, e.g., CSS or JavaScript.
  • /package.json: Node.js dependencies. Tailwind, for example, is installed via the Node package manager (npm).
  • /config.toml: Hugo's site configuration, like the root path and menu items. Hugo can access configuration elements when rendering the site. So you can define custom configuration settings here.
  • /syntax.css: Hugo supports syntax highlighting via shortcodes. The highlighter is configured via this CSS file.
  • /Makefile: We use make to wrap some Hugo commands and to add addtional build steps.
  • /tailwind.config.js: This is the Tailwind CSS framwork's configuration file.
  • /postcss.config.js: Needed to make Tailwind statically accessible to the site.

Requirements

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.

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:

  • 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;
}

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.