From b171d00ceba32cd9372f2c748884474584e21f456445d12363c184deed81ded1 Mon Sep 17 00:00:00 2001 From: Nicholas Johnson <> Date: Fri, 18 Sep 2026 00:00:00 +0000 Subject: Add an example site The theme shipped no runnable site and documented no configuration, so every setting it reads had to be discovered by reading the templates, and there was nothing to build against when changing them. The build failure that unset RSS limits caused would have been caught immediately by an example site. The two configuration files are the separate website and capsule configurations the readme asks for, annotated with what each setting does and which are optional. The content demonstrates entries, tags, references, a standalone page and the front matter keys that control them. Also ignore build output, which no rule previously covered. Co-Authored-By: Claude Opus 5 --- exampleSite/content/about.md | 18 +++++++++ exampleSite/content/entry/tagging.md | 20 ++++++++++ exampleSite/content/entry/welcome.md | 26 +++++++++++++ exampleSite/content/entry/writing-entries.md | 36 +++++++++++++++++ exampleSite/hugo.gemini.toml | 58 ++++++++++++++++++++++++++++ exampleSite/hugo.toml | 58 ++++++++++++++++++++++++++++ exampleSite/templates/logo.txt | 5 +++ 7 files changed, 221 insertions(+) create mode 100644 exampleSite/content/about.md create mode 100644 exampleSite/content/entry/tagging.md create mode 100644 exampleSite/content/entry/welcome.md create mode 100644 exampleSite/content/entry/writing-entries.md create mode 100644 exampleSite/hugo.gemini.toml create mode 100644 exampleSite/hugo.toml create mode 100644 exampleSite/templates/logo.txt (limited to 'exampleSite') diff --git a/exampleSite/content/about.md b/exampleSite/content/about.md new file mode 100644 index 0000000..a75831d --- /dev/null +++ b/exampleSite/content/about.md @@ -0,0 +1,18 @@ +--- +title: "About" +draft: false +pageinfo: false +makerefs: false +build: + list: never +--- + +This is a standalone page rather than a journal entry. It sets +"pageinfo" to false, so no date or reading time is shown, and +"makerefs" to false, so its links are rendered in place. + +It also sets "build.list" to never, which keeps it out of the entry +list on the homepage and out of the feeds. + +Standalone pages are a good fit for a colophon, a contact page or a +now page. Link to them from the menu in your configuration file. diff --git a/exampleSite/content/entry/tagging.md b/exampleSite/content/entry/tagging.md new file mode 100644 index 0000000..caef813 --- /dev/null +++ b/exampleSite/content/entry/tagging.md @@ -0,0 +1,20 @@ +--- +title: "Tagging" +date: 2026-03-08T11:00:00+0000 +draft: false +tags: ["journal", "gemini"] +makerefs: false +--- + +Tags are listed alongside the date and reading time of an entry, and +each one gets a page and a feed of its own. + +This entry sets "makerefs" to false, so its links are rendered where +they appear rather than being collected at the foot of the page. In +gemtext a link must occupy a whole line, so only links written on their +own line become link lines: + +[The tag list for this site](/tags/) + +Set "showlinkemoji" to false in the front matter to drop the link emoji +from those lines. diff --git a/exampleSite/content/entry/welcome.md b/exampleSite/content/entry/welcome.md new file mode 100644 index 0000000..614a490 --- /dev/null +++ b/exampleSite/content/entry/welcome.md @@ -0,0 +1,26 @@ +--- +title: "Welcome To The Journal Theme" +date: 2026-01-15T09:00:00+0000 +draft: false +tags: ["journal", "hugo"] +--- + +This entry is written once and published twice: as HTML for the web and +as gemtext for the [Gemini protocol](https://geminiprotocol.net/). + +By default, links are collected into a reference section at the foot of +the gemtext version, because gemtext has no inline links. The same entry +keeps its inline links in the HTML version. Set "makerefs" to false in +an entry's front matter to render links in place on both instead. + +## What The Theme Gives You + +* An entry list on the homepage, and one per tag +* Atom feeds for the homepage, each tag and the tag list +* Publication date and reading time on every entry +* Optional audio versions of entries +* No JavaScript and no analytics + +Which Markdown features survive the trip to gemtext, and which are +flattened or dropped, is documented in full in the +[gemtext compatibility reference guide](https://git.nicholasjohnson.ch/hugo-theme-journal/tree/GEMTEXT-COMPATIBILITY-REFERENCE-GUIDE.md). diff --git a/exampleSite/content/entry/writing-entries.md b/exampleSite/content/entry/writing-entries.md new file mode 100644 index 0000000..8184c32 --- /dev/null +++ b/exampleSite/content/entry/writing-entries.md @@ -0,0 +1,36 @@ +--- +title: "Writing Entries" +date: 2026-02-20T14:30:00+0000 +draft: false +tags: ["journal"] +--- + +Create an entry with the "entry" archetype: + +```sh +hugo new --kind entry entry/my-first-entry.md +``` + +Entries are Markdown. Headings, lists, blockquotes and preformatted +blocks all survive into gemtext: + +> Gemtext has no nesting and no inline emphasis, so the theme flattens +> what it can and drops the rest. + +Emphasis is a good example. *Italics* and **bold** are rendered on the +web, and their asterisks are removed from the gemtext, so write in a way +that still reads without them. + +## Adding An Audio Version + +Make the entry a page bundle and put the audio file beside it: + +```plaintext +content/entry/my-first-entry/ +├── index.md +└── my-first-entry.opus +``` + +The website gets an audio player and the capsule gets a download link. +Include more than one encoding and browsers pick the format they +support, while the capsule only links the most preferred one. diff --git a/exampleSite/hugo.gemini.toml b/exampleSite/hugo.gemini.toml new file mode 100644 index 0000000..64d3956 --- /dev/null +++ b/exampleSite/hugo.gemini.toml @@ -0,0 +1,58 @@ +# Configuration for the capsule. The website is built from +# hugo.toml; see the readme for why the two are separate. + +baseURL = "gemini://example.com/" +languageCode = "en-us" +title = "A Journal" +# The directory name the theme is installed under in themes/. +theme = "journal" + +# "{currentYear}" is replaced with the year the site is built. +copyright = "Copyright (C) 2026 Example Author. Some rights reserved." + +# Lets entries use emoji shortcodes such as :smile: in their Markdown. +enableEmoji = true + +# A capsule has no use for either, and rendering the 404 page would pull +# the website's stylesheet into the capsule along with it. +disableKinds = ["404", "sitemap"] + +[params] + # Heading and opening paragraph of the homepage. + indexTitle = "A Journal" + indexIntro = "An example of the journal theme, an accessible, no-JS, minimalist, high-contrast theme that outputs both gemtext and HTML." + + # Atom feeds require at least the author name. + author = { name = "Example Author", email = "author@example.com" } + + # Used for the description meta element and as the feed subtitle. + description = "An example journal built with the journal theme." + + # Optional. Used for the keywords meta element. + keywords = "journal, example, gemini" + + # Optional. Any layout that time.Format accepts, or one of Hugo's + # named layouts. Defaults to ":date_long". + dateFormat = ":date_long" + +[taxonomies] + tag = "tags" + +# Each kind must list the formats it is rendered in. Leaving a kind out +# falls back to Hugo's defaults, which would render the kind as HTML +# into the capsule. +[outputs] + home = ["Gemini", "Gemini_Atom"] + section = ["Gemini"] + taxonomy = ["Gemini", "Gemini_Atom"] + term = ["Gemini", "Gemini_Atom"] + page = ["Gemini"] + +# Optional. Caps the number of entries in a feed; unlimited by default. +# [services.rss] +# limit = 20 + +[[menu.main]] + name = "About" + url = "/about/" + weight = 1 diff --git a/exampleSite/hugo.toml b/exampleSite/hugo.toml new file mode 100644 index 0000000..b964499 --- /dev/null +++ b/exampleSite/hugo.toml @@ -0,0 +1,58 @@ +# Configuration for the website. The capsule is built from +# hugo.gemini.toml; see the readme for why the two are separate. + +baseURL = "https://example.com/" +languageCode = "en-us" +title = "A Journal" +# The directory name the theme is installed under in themes/. +theme = "journal" + +# "{currentYear}" is replaced with the year the site is built. +copyright = "Copyright (C) 2026 Example Author. Some rights reserved." + +# Lets entries use emoji shortcodes such as :smile: in their Markdown. +enableEmoji = true + +[params] + # Heading and opening paragraph of the homepage. + indexTitle = "A Journal" + indexIntro = "An example of the journal theme, an accessible, no-JS, minimalist, high-contrast theme that outputs both gemtext and HTML." + + # Atom feeds require at least the author name. + author = { name = "Example Author", email = "author@example.com" } + + # Used for the description meta element and as the feed subtitle. + description = "An example journal built with the journal theme." + + # Optional. Used for the keywords meta element. + keywords = "journal, example, gemini" + + # Optional. Any layout that time.Format accepts, or one of Hugo's + # named layouts. Defaults to ":date_long". + dateFormat = ":date_long" + + # Optional. Replaces the theme's stylesheet with your own, resolved + # from the assets directory. Every entry must exist or the build fails. + # custom_css = ["css/my-theme.css"] + +[taxonomies] + tag = "tags" + +# Each kind must list the formats it is rendered in. Leaving a kind out +# falls back to Hugo's defaults, which include an RSS feed this theme +# has no template for. +[outputs] + home = ["HTML", "Atom"] + section = ["HTML"] + taxonomy = ["HTML", "Atom"] + term = ["HTML", "Atom"] + page = ["HTML"] + +# Optional. Caps the number of entries in a feed; unlimited by default. +# [services.rss] +# limit = 20 + +[[menu.main]] + name = "About" + url = "/about/" + weight = 1 diff --git a/exampleSite/templates/logo.txt b/exampleSite/templates/logo.txt new file mode 100644 index 0000000..f5d016d --- /dev/null +++ b/exampleSite/templates/logo.txt @@ -0,0 +1,5 @@ + _ _ _ + | |___ _ _ _ _ _ _ __ _| | | | + _ | / _ \ || | '_| ' \/ _` | | |_| +| |_| \___/\_,_|_| |_||_\__,_|_| _ + \___/ |_| -- cgit v1.2.3