ii.com: Hugo’s data Directory (featuring Nitter instances)

When you create a Hugo project with this command:

hugo new site directory-name --format=extension

For example:

hugo new site directory-name --format=yaml

This directory structure is created:

.
└── directory-name/
    ├── archetypes/
    ├── assets/
    ├── content/
    ├── data/
    ├── layouts/
    ├── static/
    ├── themes/
    └── config.extension

💡	Possible values of `extension` are `json`, `toml`, `yaml` and `yml`. You can think of `config.extension` as Hugo’s default data file.

About the data directory

In your Hugo layout files — including in your shortcodes — you can access the contents of a non-⁠config JSON, TOML, YAML or XML file by putting the file in your project’s data directory. For example:

.
└── directory-name/
    ├── archetypes/
    ├── assets/
    ├── content/
    ├── data/
    │   └── nitter.yaml     ⟵👀
    ├── layouts/
    ├── static/
    ├── themes/
    └── config.yaml

To learn about this nitter.yaml file, see the next section.

To learn about the data directory, see…

Example

In July 2022, I started including Nitter links on some Infinite Ink tags/portals. Nitter is a Twitter front-⁠end focused on privacy, which you can learn about at…

Because Nitter instances are sometimes overloaded or broken, I use Hugo’s shuffle function to select a random Nitter instance for each timeline that I link to. Below are the steps I used to set this up.

1. Create data/nitter.yaml

First, I created the following YAML⁠^[2] file that lists (hopefully) working Nitter instances.

data/nitter.yaml

## A line beginning with # is a comment and is ignored
instances:
 - xcancel.com
 - nitter.poast.org
 - nitter.privacyredirect.com
 - lightbrd.com
 - nitter.space
 - nitter.tiekoetter.com
 - nuku.trabun.org
 - nitter.catsarch.com
 - nitter.us.catsarch.com

2. Create shortcode

Next, I created something like the following Hugo shortcode.

layouts/shortcodes/nitter-instance-of-nm-gohugo-list.html

To view @nm’s <em>gohugo</em> Twitter list on a random
<a href="https://github.com/zedeus/nitter/wiki/Instances">Nitter instance</a>,
go to
{{ range site.Data.nitter.instances | shuffle | first 1 -}}
 <a href="https://{{ . }}/nm/lists/gohugo">
  {{- . -}}/nm/lists/gohugo</a>.
{{ end }}

ℹ	The bolded line uses Hugo’s contextless global `site` function⁠^[3] to access `site.Data.nitter.instances`. In `site.Data.whatever`, `Data` must begin with upper case `D` and `site` must be all lower case.

3. Call shortcode

To call this shortcode in a content file, for example in the source of this article, I use the following syntax.

{{< nitter-instance-of-nm-gohugo-list >}}

4. Example rendering of shortcode

Here is how this shortcode is rendered on this build of this page:

To view @nm's gohugo Twitter list on a random Nitter instance, go to nitter.catsarch.com/nm/lists/gohugo.

Note that each time that Hugo builds this Infinite Ink website, the Nitter instance (nitter.catsarch.com in this case) changes.◊

1. Many Infinite Ink pages, including this one, are evergreen 🌲 and regularly updated.

2. To learn about YAML, see Infinite Ink’s YAML Includes Atoms, Maps, and Lists (featuring the string ¯\_(ツ)_/¯).

3. You can tell that the Hugo site function is contextless by noticing that it does not have a leading dot (.). To learn about this global function, see the Hugo v0.53 release notes, especially the relevant GitHub commit and GitHub issues.

Hugo’s `data` Directory (featuring Nitter instances)
Updated by nm 2023-August-29

News

Hugo’s default directory structure

About the `data` directory