## 1. Project Overview & Quickstart (redis/redis-rb) # redis-rb [![Build Status][gh-actions-image]][gh-actions-link] [![Inline docs][rdoc-master-image]][rdoc-master-link] A Ruby client that tries to match [Redis][redis-home]' API one-to-one, while still providing an idiomatic interface. See [RubyDoc.info][rubydoc] for the API docs of the latest published gem. ## Getting started Install with: ``` $ gem install redis ``` You can connect to Redis by instantiating the `Redis` class: ```ruby require "redis" redis = Redis.new ``` This assumes Redis was started with a default configuration, and is listening on `localhost`, port 6379. If you need to connect to a remote server or a different port, try: ```ruby redis = Redis.new(host: "10.0.1.1", port: 6380, db: 15) ``` You can also specify connection options as a [`redis://` URL][redis-url]: ```ruby redis = Redis.new(url: "redis://:p4ssw0rd@10.0.1.1:6380/15") ``` The client expects passwords with special characters to be URL-encoded (i.e. `CGI.escape(password)`). To connect to Redis listening on a Unix socket, try: ```ruby redis = Redis.new(path: "/tmp/redis.sock") ``` To connect to a password protected Redis instance, use: ```ruby redis = Redis.new(password: "mysecret") ``` To connect a Redis instance using [ACL](https://redis.io/topics/acl), use: ```ruby redis = Redis.new(username: 'myname', password: 'mysecret') ``` The Redis class exports methods that are named identical to the commands they execute. The arguments these methods accept are often identical to the arguments specified on the [Redis website][redis-commands]. For instance, the `SET` and `GET` commands can be called like this: ```ruby redis.set("mykey", "hello world") # => "OK" redis.get("mykey") # => "hello world" ``` All commands, their arguments, and return values are documented and available on [RubyDoc.info][rubydoc]. ## Language and server support redis-rb targets actively supported runtimes on both the language and the server side: - **Ruby:** Ruby 3.2 and newer. See the [Ruby maintenance branches][ruby-branches] page for each version's status and dates. - **Redis server:** the versions designated for support by Redis. See [Supported Redis database versions][redis-versions]. ## Protocol (RESP3) Starting in 6.0, the client negotiates the [RESP3 protocol][resp3] (`HELLO 3`) by default. Command return values are unchanged from 5.x, with one exception: `GEOPOS` and `GEOSEARCH`/`GEORADIUS` with `WITHCOORD` now return coordinates as `Float` instead of `String`. To keep the previous RESP2 behavior, pass `protocol: 2`: ```ruby redis = Redis.new(protocol: 2) ``` Servers without RESP3 support (Redis < 6.0, or anything replying `NOPROTO`) are detected on connect and the client transparently falls back to RESP2, so no configuration is needed for older servers. ### Why RESP3 is the default RESP3's richer wire types let the parser deliver replies already in their final Ruby shape. Under RESP2, structured replies arrive as flat arrays of bulk strings and the client re-shapes them in Ruby: `HGETALL` turns a flat `[field, value, field, value, ...]` array into a `Hash`, and sorted-set scores are converted from `String` to `Float` pair by pair. Under RESP3 the server tags these replies as native maps and doubles, so the final `Hash` and `Float` values come straight out of the parser and the Ruby-side re-shaping pass disappears entirely. How much that saves depends on where parsing happens. In our benchmarks ([bench/resp_comparison.rb](bench/resp_comparison.rb), Ruby 3.4, 100-element replies), hash reads (`HGETALL`) consistently use ~10–25% less client CPU per call on both drivers. With the [hiredis driver](#hiredis-binding), where parsing runs in C, sorted-set reads with scores gain up to 16% throughput and ~20% less CPU per call on top of that; with the pure-Ruby driver they are unchanged, since the parser then spends in Ruby roughly what the re-shaping pass used to cost. Simple string commands and stream commands are unaffected either way — their reply shapes are the same in both protocols. In short: RESP3 is never slower where it matters, and it pairs best with hiredis — that combination moves all reply construction out of Ruby and into C. Beyond performance, RESP3 unlocks protocol capabilities RESP2 simply doesn't have. The most important is out-of-band **push messages**: the server can send notifications on a connection without the client asking, which is the foundation for server-assisted client-side caching (`CLIENT TRACKING` invalidation events), pub/sub messages delivered over the regular command connection instead of a dedicated one, and other server-initiated notifications. Defaulting to RESP3 in 6.0 lays the groundwork for building these features in future releases without another protocol migration. See [the RESP3 migration guide](specs/migration-resp3.md) for full details. ## Client identification On connect the client identifies itself to the server with `CLIENT SETINFO`, so `redis-rb` and its version are visible in `CLIENT LIST` and `CLIENT INFO`: ``` lib-name=redis-rb lib-ver= ``` Libraries built on top of `redis-rb` can add their own identity with `driver_info:`, which is reported alongside it. The recommended suffix format is `_v`, following the convention used by the official client libraries: ```ruby Redis.new(driver_info: "my-gem_v#{MyGem::VERSION}") # reported as: lib-name=redis-rb(my-gem_v1.0.0) lib-ver= ``` `driver_info:` also accepts an array, joined with `;` (the conventional delimiter for multiple suffixes). It extends the reported name rather than replacing it, so `redis-rb` stays identifiable either way. Runs of characters the server would reject (spaces, non-printable bytes) and of the parentheses that delimit the suffix are each replaced with a single `_`, or dropped at the edges of the value. Servers older than 7.2 don't support `CLIENT SETINFO`; they reject it, the error is ignored, and the connection is used as normal. If a proxy or server can't tolerate the command at all, pass `driver_info: false` to disable client identification entirely. ## Connection Pooling and Thread safety The client does not provide connection pooling. Each `Redis` instance has one and only one connection to the server, and use of this connection is protected by a mutex. As such it is heavily recommended to use the [`connection_pool` gem](https://github.com/mperham/connection_pool), e.g.: ```ruby module MyApp def self.redis @redis ||= ConnectionPool::Wrapper.new do Redis.new(url: ENV["REDIS_URL"]) end end end MyApp.redis.incr("some-counter") ``` ## Sentinel support The client is able to perform automatic failover by using [Redis Sentinel](http://redis.io/topics/sentinel). Make sure to run Redis 2.8+ if you want to use this feature. To connect using Sentinel, use: ```ruby SENTINELS = [{ host: "127.0.0.1", port: 26380 }, { host: "127.0.0.1", port: 26381 }] redis = Redis.new(name: "mymaster", sentinels: SENTINELS, role: :master) ``` * The master name identifies a group of Redis instances composed of a master and one or more slaves (`mymaster` in the example). * It is possible to optionally provide a role. The allowed roles are `master` and `slave`. When the role is `slave`, the client will try to connect to a random slave of the specified master. If a role is not specified, the client will connect to the master. * When using Sentinel support, you need to specify a list of sentinels to connect to. The list does not need to enumerate all your Sentinel instances, but a few so that if one is down the client will try the next one. The client is able to remember the last Sentinel that was able to reply correctly and will use it for the next request. To [authenticate](https://redis.io/docs/management/sentinel/#configuring-sentinel-instances-with-authentication) with Sentinel itself, you can specify the `sentinel_username` and `sentinel_password`. Exclude the `sentinel_username` option if you're using password-only authentication. ```ruby SENTINELS = [{ host: '127.0.0.1', port: 26380}, { host: '127.0.0.1', port: 26381}] redis = Redis.new(name: 'mymaster', sentinels: SENTINELS, sentinel_username: 'appuser', sentinel_password: 'mysecret', role: :master) ``` If you specify a username and/or password at the top level for your main Redis instance, Sentinel *will not* use those credentials. ```ruby # Use 'mysecret' to authenticate against the mymaster instance, but skip authentication for the sentinels: SENTINELS = [{ host: '127.0.0.1', port: 26380 }, { host: '127.0.0.1', port: 26381 }] redis = Redis.new(name: 'mymaster', sentinels: SENTINELS, role: :master, password: 'mysecret') ``` So you have to provide Sentinel credentials and Redis explicitly even if they are the same. ```ruby # Use 'mysecret' to authenticate against the mymaster instance and sentinel SENTINELS = [{ host: '127.0.0.1', port: 26380 }, { host: '127.0.0.1', port: 26381 }] redis = Redis.new(name: 'mymaster', sentinels: SENTINELS, role: :master, password: 'mysecret', sentinel_password: 'mysecret') ``` Also, the `name`, `password`, `username`, and `db` for the Redis instance can be passed as a URL: ```ruby redis = Redis.new(url: "redis://appuser:mysecret@mymaster/10", sentinels: SENTINELS, role: :master) ``` ## Cluster support [Clustering](https://redis.io/topics/cluster-spec). is supported via the [`redis-clustering` gem](cluster/). ## Pipelining When multiple commands are executed sequentially, but are not dependent, the calls can be *pipelined*. This means that the client doesn't wait for reply of the first command before sending the next command. The advantage is that multiple commands are sent at once, resulting in faster overall execution. The client can be instructed to pipeline commands by using the `#pipelined` method. After the block is executed, the client sends all commands to Redis and gathers their replies. These replies are returned by the `#pipelined` method. ```ruby redis.pipelined do |pipeline| pipeline.set "foo", "bar" pipeline.incr "baz" end # => ["OK", 1] ``` Commands must be called on the yielded objects. If you call methods on the original client objects from inside a pipeline, they will be sent immediately: ```ruby redis.pipelined do |pipeline| pipeline.set "foo", "bar" redis.incr "baz" # => 1 end # => ["OK"] ``` ### Exception management The `exception` flag in the `#pipelined` is a feature that modifies the pipeline execution behavior. When set to `false`, it doesn't raise an exception when a command error occurs. Instead, it allows the pipeline to execute all commands, and any failed command will be available in the returned array. (Defaults to `true`) ```ruby results = redis.pipelined(exception: false) do |pipeline| pipeline.set('key1', 'value1') pipeline.lpush('key1', 'something') # This will fail pipeline.set('key2', 'value2') end # results => ["OK", #, "OK"] results.each do |result| if result.is_a?(Redis::CommandError) # Do something with the failed result end end ``` ### Executing commands atomically You can use `MULTI/EXEC` to run a number of commands in an atomic fashion. This is similar to executing a pipeline, but the commands are preceded by a call to `MULTI`, and followed by a call to `EXEC`. Like the regular pipeline, the replies to the commands are returned by the `#multi` method. ```ruby redis.multi do |transaction| transaction.set "foo", "bar" transaction.incr "baz" end # => ["OK", 1] ``` ### Futures Replies to commands in a pipeline can be accessed via the *futures* they emit. All calls on the pipeline object return a `Future` object, which responds to the `#value` method. When the pipeline has successfully executed, all futures are assigned their respective replies and can be used. ```ruby set = incr = nil redis.pipelined do |pipeline| set = pipeline.set "foo", "bar" incr = pipeline.incr "baz" end set.value # => "OK" incr.value # => 1 ``` ## Bulk hash ingestion (HIMPORT) > **Experimental:** HIMPORT support is experimental. The client API (method > signatures, reply aggregation on cluster, and the automatic re-prepare > behavior) may change in a future minor release without a major version bump. Redis 8.10 adds the `HIMPORT` command family for loading many hashes that share the same set of field names: register the field names once with `himport_prepare`, then create each hash by sending only its values. Keys written this way are regular hashes — every hash command works on them. ```ruby redis.himport_prepare("users", ["name", "email", "age"]) redis.himport_set("user:1", "users", ["alice", "alice@example.com", "25"]) redis.himport_set("user:2", "users", ["bob", "bob@example.com", "30"]) redis.himport_discard("users") # => 1 ``` Values pair positionally with the prepared fields. Note that hash enumeration order (`HGETALL`, `HKEYS`) is not guaranteed to match the prepare order. ### Fieldsets are connection state A prepared fieldset lives in the server-side session of the physical connection that prepared it: it is invisible to other connections and destroyed by a disconnect or `RESET`. A `himport_set` on a connection without the fieldset fails with `ERR no such fieldset`. Because a `Redis` instance transparently replaces a dead connection (see [Reconnections](#reconnections)), the client keeps all fieldset schemas and, when a `himport_set` reports the fieldset is gone, re-prepares it and retries the command once. Explicitly discarded fieldsets are never restored. To keep the fieldset lifecycle fully explicit instead, disable the recovery: ```ruby redis = Redis.new(himport_auto_prepare: false) ``` For the highest ingestion throughput, send the `PREPARE` and its `SET`s as one pipeline — a single batch always executes on a single connection: ```ruby redis.pipelined do |pipeline| pipeline.himport_prepare("users", ["name", "email", "age"]) rows.each { |id, row| pipeline.himport_set("user:#{id}", "users", row) } end ``` If the `PREPARE` in a batch fails, every `SET` in it fails with `no such fieldset` — the `PREPARE` error is the root cause. Note that the automatic re-prepare applies to direct calls only, not to commands inside `pipelined`/`multi` blocks. When using the `connection_pool` gem, each checkout may hand you a different underlying connection: run `himport_prepare` and its `himport_set` calls within one checkout (`pool.with { |redis| ... }`), ideally as one pipelined block. With `Redis::Distributed`, `himport_prepare`, `himport_discard` and `himport_discard_all` fan out to every ring node and return an array with one reply per node; `himport_set` routes by key. With `Redis::Cluster`, the same commands fan out to every master node and return a single aggregated reply, matching the standalone API. ## Error Handling In general, if something goes wrong you'll get an exception. For example, if it can't connect to the server a `Redis::CannotConnectError` error will be raised. ```ruby begin redis.ping rescue Redis::BaseError => e e.inspect # => # e.message # => Timed out connecting to Redis on 10.0.1.1:6380 end ``` See lib/redis/errors.rb for information about what exceptions are possible. ## Timeouts The client allows you to configure connect, read, and write timeouts. Starting in version 5.0, the default for each is 1. Before that, it was 5. Passing a single `timeout` option will set all three values: ```ruby Redis.new(:timeout => 1) ``` But you can use specific values for each of them: ```ruby Redis.new( :connect_timeout => 0.2, :read_timeout => 1.0, :write_timeout => 0.5 ) ``` All timeout values are specified in seconds. When using pub/sub, you can subscribe to a channel using a timeout as well: ```ruby redis = Redis.new(reconnect_attempts: 0) redis.subscribe_with_timeout(5, "news") do |on| on.message do |channel, message| # ... end end ``` If no message is received after 5 seconds, the client will unsubscribe. ## Reconnections **By default**, this gem will only **retry a connection once** and then fail, but the client allows you to configure how many `reconnect_attempts` it should complete before declaring a connection as failed. ```ruby Redis.new(reconnect_attempts: 0) Redis.new(reconnect_attempts: 3) ``` If you wish to wait between reconnection attempts, you can instead pass a list of durations: ```ruby Redis.new(reconnect_attempts: [ 0, # retry immediately 0.25, # retry a second time after 250ms 1, # retry a third and final time after another 1s ]) ``` If you wish to disable reconnection only for some commands, you can use `disable_reconnection`: ```ruby redis.get("some-key") # this may be retried redis.disable_reconnection do redis.incr("some-counter") # this won't be retried. end ``` ## SSL/TLS Support To enable SSL support, pass the `:ssl => true` option when configuring the Redis client, or pass in `:url => "rediss://..."` (like HTTPS for Redis). You will also need to pass in an `:ssl_params => { ... }` hash used to configure the `OpenSSL::SSL::SSLContext` object used for the connection: ```ruby redis = Redis.new( :url => "rediss://:p4ssw0rd@10.0.1.1:6381/15", :ssl_params => { :ca_file => "/path/to/ca.crt" } ) ``` The options given to `:ssl_params` are passed directly to the `OpenSSL::SSL::SSLContext#set_params` method and can be any valid attribute of the SSL context. Please see the [OpenSSL::SSL::SSLContext documentation] for all of the available attributes. Here is an example of passing in params that can be used for SSL client certificate authentication (a.k.a. mutual TLS): ```ruby redis = Redis.new( :url => "rediss://:p4ssw0rd@10.0.1.1:6381/15", :ssl_params => { :ca_file => "/path/to/ca.crt", :cert => OpenSSL::X509::Certificate.new(File.read("client.crt")), :key => OpenSSL::PKey::RSA.new(File.read("client.key")) } ) ``` [OpenSSL::SSL::SSLContext documentation]: http://ruby-doc.org/stdlib-2.5.0/libdoc/openssl/rdoc/OpenSSL/SSL/SSLContext.html ## Expert-Mode Options - `inherit_socket: true`: disable safety check that prevents a forked child from sharing a socket with its parent; this is potentially useful in order to mitigate connection churn when: - many short-lived forked children of one process need to talk to redis, AND - your own code prevents the parent process from using the redis connection while a child is alive Improper use of `inherit_socket` will result in corrupted and/or incorrect responses. ## hiredis binding By default, redis-rb uses Ruby's socket library to talk with Redis. The hiredis driver uses the connection facility of hiredis-rb. In turn, hiredis-rb is a binding to the official hiredis client library. It optimizes for speed, at the cost of portability. Because it is a C extension, JRuby is not supported (by default). It is best to use hiredis when you have large replies (for example: `LRANGE`, `SMEMBERS`, `ZRANGE`, etc.) and/or use big pipelines. In your Gemfile, include `hiredis-client`: ```ruby gem "redis" gem "hiredis-client" ``` If your application doesn't call `Bundler.require`, you may have to require it explicitly: ```ruby require "hiredis-client" ```` This makes the hiredis driver the default. If you want to be certain hiredis is being used, when instantiating the client object, specify hiredis: ```ruby redis = Redis.new(driver: :hiredis) ``` ## See Also - [async-redis](https://github.com/socketry/async-redis) — An [async](https://github.com/socketry/async) compatible Redis client. ## Contributors Several people contributed to redis-rb, but we would like to especially mention Ezra Zygmuntowicz. Ezra introduced the Ruby community to many new cool technologies, like Redis. He wrote the first version of this client and evangelized Redis in Rubyland. Thank you, Ezra. ## Contributing [Fork the project](https://github.com/redis/redis-rb) and send pull requests. [rdoc-master-image]: https://img.shields.io/badge/docs-rdoc.info-blue.svg [rdoc-master-link]: https://rubydoc.info/github/redis/redis-rb [redis-commands]: https://redis.io/commands [redis-home]: https://redis.io [redis-url]: https://www.iana.org/assignments/uri-schemes/prov/redis [gh-actions-image]: https://github.com/redis/redis-rb/workflows/Test/badge.svg [gh-actions-link]: https://github.com/redis/redis-rb/actions [rubydoc]: https://rubydoc.info/gems/redis [resp3]: https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md [ruby-branches]: https://www.ruby-lang.org/en/downloads/branches/ [redis-versions]: https://redis.io/docs/latest/operate/rc/databases/version-management/#supported-database-versions ## 2. Official Technical Reference & Guides (redis/docs) # Redis Docs > Note: if you are an AI agent, please see [AI_AGENT_DEVELOPER_GUIDE.md](AI_AGENT_DEVELOPER_GUIDE.md) for more information. PRs are merged to the `main` branch of this repo. Merging to `main` automatically builds and publishes your changes to the live docs site (under `/latest`) — there is no separate manual publish step, so allow a little time for the build and CDN cache to refresh after your PR is merged. Before your PR is merged, you can preview your changes on a per-branch staging URL; the docs team's bot posts the staging links as a comment on your PR. ## 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. * **/Makefile**: We use make to wrap some Hugo commands and to add additional 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.143.0; 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. 1. Install the necessary Node.js and Python dependencies. 1. Build the components that were fetched from external Github repositories (e.g., client examples). This fetches source code files and generates data files. 1. 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 1. Check the branch out 1. Perform the build as stated before by using `make all` 1. Install the Google Cloud CLI 1. Authenticate to the GCS bucket 1. Validate the branch name 1. 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`). ### 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" >}}   {{< image filename="/images/rc/icon-database-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.