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

Page contents

News

2023-August-5  As of today, this evolving⁠[1] article has been on the web for 1 year.🕯

 

Hugo’s default directory structure

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 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:
# - nitter.nixnet.services  # auth required :(
 - nitter.unixfox.eu  # white background :)
 - nitter.moomoo.me
 - nitter.poast.org
 - nitter.cz
 - nitter.privacydev.net  # 2023-09-01 "rate limited"
 - nitter.d420.de
# - nitter.nicfab.eu  # 2023-08-29 No [list] items found; 2023-09-01 works; 2023-10-16 fail
# - bird.habedieeh.re  # 2023-08-29 & 10-16 "Instance has been rate limited"
# - tweet.whateveritworks.org  # 2023-12-04 no more
 - nitter.x86-64-unknown-linux-gnu.zip
 - nitter.services.woodland.cafe
 - nitter.catsarch.com
 - nitter.perennialte.ch
# - nitter.salastil.com  # 2023-12-04 no more
# - nt.ggtyler.dev  # 2023-09-01 "List...not found"
# - nitter.hyperreal.coffee  # 2023-10-16 "can't reach"

 

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.cz/nm/lists/gohugo.

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

 

See also

For more about Hugo, see Infinite Ink’s…

 

Endnotes

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.

Please discuss & share 📝 👎 👍 📯