wip own theme

- examples
- link to anatomy

.gitignore

@@ -6,4 +6,4 @@
 _gen
 
 # downloaded by nix
-themes
+themes/poison

content/posts/why-i-do-not-use-flake-utils.md

@@ -11,7 +11,9 @@ For me the biggest advantage flakes bring is not additional functionality. Inste
 
 When learning flakes, you often see [flake-utils]( https://github.com/numtide/flake-utils) being used. With it, you can shorten your flakes by not having to specify everything per system.
 
-### Without anything
+_Edit_: The patterns described here as well as `flake-parts` are also compared in [Practical Nix flake anatomy](https://vtimofeenko.com/posts/practical-nix-flake-anatomy-a-guided-tour-of-flake.nix/#flake-utils-flakeparts-etc).
+
+## Without anything
 
 ```nix
 {
@@ -33,7 +35,7 @@ When learning flakes, you often see [flake-utils]( https://github.com/numtide/fl
 }
 ```
 
-### With flake-utils
+## With flake-utils
 
 ```nix
 {
@@ -54,7 +56,7 @@ When learning flakes, you often see [flake-utils]( https://github.com/numtide/fl
 }
 ```
 
-### With function in flake
+## With function in flake
 
 To make a long story short, here is what I usually do instead:
 
@@ -94,16 +96,24 @@ For me, it wasn’t a problem to ignore boilerplate like this at first, slowly l
 At **[1]**, the supported systems are specified. I personally use `x86_64-linux` and `aarch64-linux`, but I also usually support `x86_64-darwin` and `aarch64-darwin` in public projects.
 If you want to support any system, you can use [`nixpkgs.lib.system.flake-exposed`](https://github.com/NixOS/nixpkgs/blob/374e6bcc403e02a35e07b650463c01a52b13a7c8/lib/systems/default.nix#L58) at **[2]** instead of defining your own list.
 
-Because the definition is right inside the flake, you can tweak what gets passed to the function. For example, the [flake for RedoxOS-development](https://gitlab.redox-os.org/redox-os/redox/-/blob/cb34b9bd862f46729c0082c37a41782a3b1319c3/flake.nix#L38) I contributed[^1] this to passes the custom rust-toolchain.
+### Example variations
+
+Because the definition is right inside the flake, you can tweak what gets passed to the function.
+By doing that, you have to explicitly add the new identifier to each part that uses it, instead of having a global `let` binding that is implicitly used.
+`system` being available here is another bonus, as otherwise this would require duplicate `let`s everywhere.
+
 An example for how to do it is already right there: at **[3]**, `pkgs` is provided.
+Some real-world usages I wrote or encountered:
+
+- [servicepoint-life flake](https://git.berlin.ccc.de/vinzenz/servicepoint-life/src/commit/5f5e10d39f09f4d60b4301e76f0158636afee6d1/flake.nix): passes in initialized `naersk` instance and a shorthand to refer to packages defined in the flake itself
+- [RedoxOS development flake](https://gitlab.redox-os.org/redox-os/redox/-/blob/cb34b9bd862f46729c0082c37a41782a3b1319c3/flake.nix#L38): uses it to pass a custom rust-toolchain
+- [my NixOS flake](https://git.berlin.ccc.de/vinzenz/nixos-configuration/src/commit/3d27f554015ece713fa22fe829d711b430d6bbda/flake.nix): uses something similar for per-host config
 
 Another possible tweak: You may want to define separate supported systems for each output.
 This is useful, for example, if the target environment you're developing for cannot support a development shell.
 
+## Conclusion
+
 For me, the trade-offs are worth it, as they provide greater transparency and control over the flake configuration.
-
-That being said, I fully acknowledge that `flake-utils` can still be a great choice for many people.
-It simplifies things and reduces the need to write boilerplate code, which can be a plus depending on your needs and workflow.
+For you, this may be different, in which case keep using it!
 Ultimately, it's also matter of personal preference.
-
-[^1]: If you check the history, you will see I am not mentioned. I am still a bit salty about that, as it was my first contribution to a bigger OSS project.

content/projects/servicepoint/servicepoint.md

@@ -1,5 +0,0 @@
-+++
-date = '2025-04-06T12:24:08+02:00'
-draft = true
-title = 'servicepoint'
-+++

flake.lock

@@ -2,16 +2,16 @@
   "nodes": {
     "nixpkgs": {
       "locked": {
-        "lastModified": 1748037224,
-        "narHash": "sha256-92vihpZr6dwEMV6g98M5kHZIttrWahb9iRPBm1atcPk=",
+        "lastModified": 1748437600,
+        "narHash": "sha256-hYKMs3ilp09anGO7xzfGs3JqEgUqFMnZ8GMAqI6/k04=",
         "owner": "nixos",
         "repo": "nixpkgs",
-        "rev": "f09dede81861f3a83f7f06641ead34f02f37597f",
+        "rev": "7282cb574e0607e65224d33be8241eae7cfe0979",
         "type": "github"
       },
       "original": {
         "owner": "nixos",
-        "ref": "nixos-24.11",
+        "ref": "nixos-25.05",
         "repo": "nixpkgs",
         "type": "github"
       }

flake.nix

@@ -2,7 +2,7 @@
   description = "Flake for the contents of https://zerforschen.plus";
 
   inputs = {
-    nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-24.11";
+    nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-25.05";
   };
 
   outputs =
@@ -28,12 +28,14 @@
       devShells = forAllSystems (
         { pkgs, system, ... }:
         {
-          default = pkgs.mkShellNoCC rec {
+          default = pkgs.mkShellNoCC {
             inputsFrom = [ self.packages.${system}.default ];
 
             shellHook = ''
               mkdir -p themes
               ln -snf "${self.packages.${system}.hugo-theme-poison}" themes/poison
+
+              alias hugo="hugo --baseURL=http://localhost/"
             '';
           };
         }

hugo.toml

@@ -2,41 +2,41 @@
 baseURL = '/'
 #languageCode = 'en-us'
 title = 'zerforschen+'
-theme = 'poison'
+theme = 'own-theme'
 pluralizelisttitles = false
 
 [params]
-    brand = "zerforschen+"
-    description = ""
-    dark_mode = true
-    front_page_content = ["posts", "projects"]
-    menu = [
-        # Dict keys:
-            # Name:         The name to display on the menu.
-            # URL:          The directory relative to the content directory.
-            # HasChildren:  If the directory's files should be listed.  Default is true.
-            # Limit:        If the files should be listed, how many should be shown.
+brand = "zerforschen+"
+description = ""
+dark_mode = true
+front_page_content = ["posts", "projects"]
+menu = [
+    # Dict keys:
+    # Name:         The name to display on the menu.
+    # URL:          The directory relative to the content directory.
+    # HasChildren:  If the directory's files should be listed.  Default is true.
+    # Limit:        If the files should be listed, how many should be shown.
 
-        {Name = "About", URL = "/about/", HasChildren = false},
+    { Name = "About", URL = "/about/", HasChildren = false },
 
-        {Name = "Posts", URL = "/posts/", HasChildren = true, Limit = 99},
+    { Name = "Posts", URL = "/posts/", HasChildren = true, Limit = 99 },
 
-        # {Name = "Projects", URL = "/projects/"},
-    ]
+    # {Name = "Projects", URL = "/projects/"},
+]
 
-    #email_url = "mailto://user@domain"
-    github_url = "https://github.com/kaesaecracker"
-    mastodon_url = "https://chaos.social/@vinzenz"
-    matrix_url = "https://matrix.org"
-    forgejo_url = "https://git.berlin.ccc.de/vinzenz"
-    rss_icon = true
+#email_url = "mailto://user@domain"
+github_url = "https://github.com/kaesaecracker"
+mastodon_url = "https://chaos.social/@vinzenz"
+matrix_url = "https://matrix.org"
+forgejo_url = "https://git.berlin.ccc.de/vinzenz"
+rss_icon = true
 
 [taxonomies]
-    series = 'series'
-    tags = 'tags'
+series = 'series'
+tags = 'tags'
 
 [params.meta]
-    favicon = true
+favicon = true
 
 [pagination]
-    pagerSize = 10
+pagerSize = 10

themes/own-theme/archetypes/default.md

@@ -0,0 +1,5 @@
++++
+title = '{{ replace .File.ContentBaseName "-" " " | title }}'
+date = {{ .Date }}
+draft = true
++++

themes/own-theme/assets/css/main.css

@@ -0,0 +1,19 @@
+body {
+    font-family: sans-serif;
+    line-height: 1.5;
+    margin: 1rem;
+}
+
+header {
+    border-bottom: 1px solid;
+    margin-bottom: 1rem;
+}
+
+footer {
+    border-top: 1px solid;
+    margin-top: 1rem;
+}
+
+a {
+    text-decoration: none;
+}

themes/own-theme/assets/js/main.js

@@ -0,0 +1 @@
+console.log('This site was generated by Hugo.');

themes/own-theme/hugo.toml

@@ -0,0 +1,23 @@
+baseURL = 'https://example.org/'
+languageCode = 'en-US'
+title = 'My New Hugo Site'
+
+[[menus.main]]
+name = 'Home'
+pageRef = '/'
+weight = 10
+
+[[menus.main]]
+name = 'Posts'
+pageRef = '/posts'
+weight = 20
+
+[[menus.main]]
+name = 'Tags'
+pageRef = '/tags'
+weight = 30
+
+[module]
+  [module.hugoVersion]
+    extended = false
+    min = "0.116.0"

themes/own-theme/layouts/_default/baseof.html

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html lang="{{ site.Language.LanguageCode }}" dir="{{ or site.Language.LanguageDirection `ltr` }}">
+<head>
+  {{ partial "head.html" . }}
+</head>
+<body>
+  <header>
+    {{ partial "header.html" . }}
+  </header>
+  <main>
+    {{ block "main" . }}{{ end }}
+  </main>
+  <footer>
+    {{ partial "footer.html" . }}
+  </footer>
+</body>
+</html>

themes/own-theme/layouts/_default/home.html

@@ -0,0 +1,7 @@
+{{ define "main" }}
+  {{ .Content }}
+  {{ range site.RegularPages }}
+    <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+    {{ .Summary }}
+  {{ end }}
+{{ end }}

themes/own-theme/layouts/_default/list.html

@@ -0,0 +1,8 @@
+{{ define "main" }}
+  <h1>{{ .Title }}</h1>
+  {{ .Content }}
+  {{ range .Pages }}
+    <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+    {{ .Summary }}
+  {{ end }}
+{{ end }}

themes/own-theme/layouts/_default/single.html

@@ -0,0 +1,10 @@
+{{ define "main" }}
+  <h1>{{ .Title }}</h1>
+
+  {{ $dateMachine := .Date | time.Format "2006-01-02T15:04:05-07:00" }}
+  {{ $dateHuman := .Date | time.Format ":date_long" }}
+  <time datetime="{{ $dateMachine }}">{{ $dateHuman }}</time>
+
+  {{ .Content }}
+  {{ partial "terms.html" (dict "taxonomy" "tags" "page" .) }}
+{{ end }}

themes/own-theme/layouts/partials/head.html

@@ -0,0 +1,6 @@
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width">
+<title>{{ if .IsHome }}{{ site.Title }}{{ else }}{{ printf "%s | %s" .Title site.Title }}{{ end }}</title>
+{{ partialCached "head/css.html" . }}
+{{ partialCached "head/js.html" . }}
+<meta name="color-scheme" content="light dark">

themes/own-theme/layouts/partials/head/css.html

@@ -0,0 +1,9 @@
+{{- with resources.Get "css/main.css" }}
+  {{- if eq hugo.Environment "development" }}
+    <link rel="stylesheet" href="{{ .RelPermalink }}">
+  {{- else }}
+    {{- with . | minify | fingerprint }}
+      <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+    {{- end }}
+  {{- end }}
+{{- end }}

themes/own-theme/layouts/partials/head/js.html

@@ -0,0 +1,12 @@
+{{- with resources.Get "js/main.js" }}
+  {{- if eq hugo.Environment "development" }}
+    {{- with . | js.Build }}
+      <script src="{{ .RelPermalink }}"></script>
+    {{- end }}
+  {{- else }}
+    {{- $opts := dict "minify" true }}
+    {{- with . | js.Build $opts | fingerprint }}
+      <script src="{{ .RelPermalink }}" integrity="{{- .Data.Integrity }}" crossorigin="anonymous"></script>
+    {{- end }}
+  {{- end }}
+{{- end }}

themes/own-theme/layouts/partials/header.html

@@ -0,0 +1,3 @@
+<h1>{{ site.Title }}</h1>
+{{ partial "menu.html" (dict "menuID" "main" "page" .) }}
+{{ partial "socials.html" . }}

themes/own-theme/layouts/partials/menu.html

@@ -0,0 +1,51 @@
+{{- /*
+Renders a menu for the given menu ID.
+
+@context {page} page The current page.
+@context {string} menuID The menu ID.
+
+@example: {{ partial "menu.html" (dict "menuID" "main" "page" .) }}
+*/}}
+
+{{- $page := .page }}
+{{- $menuID := .menuID }}
+
+{{- with index site.Menus $menuID }}
+  <nav>
+    <ul>
+      {{- partial "inline/menu/walk.html" (dict "page" $page "menuEntries" .) }}
+    </ul>
+  </nav>
+{{- end }}
+
+{{- define "partials/inline/menu/walk.html" }}
+  {{- $page := .page }}
+  {{- range .menuEntries }}
+    {{- $attrs := dict "href" .URL }}
+    {{- if $page.IsMenuCurrent .Menu . }}
+      {{- $attrs = merge $attrs (dict "class" "active" "aria-current" "page") }}
+    {{- else if $page.HasMenuCurrent .Menu .}}
+      {{- $attrs = merge $attrs (dict "class" "ancestor" "aria-current" "true") }}
+    {{- end }}
+    {{- $name := .Name }}
+    {{- with .Identifier }}
+      {{- with T . }}
+        {{- $name = . }}
+      {{- end }}
+    {{- end }}
+    <li>
+      <a
+        {{- range $k, $v := $attrs }}
+          {{- with $v }}
+            {{- printf " %s=%q" $k $v | safeHTMLAttr }}
+          {{- end }}
+        {{- end -}}
+      >{{ $name }}</a>
+      {{- with .Children }}
+        <ul>
+          {{- partial "inline/menu/walk.html" (dict "page" $page "menuEntries" .) }}
+        </ul>
+      {{- end }}
+    </li>
+  {{- end }}
+{{- end }}

themes/own-theme/layouts/partials/terms.html

@@ -0,0 +1,23 @@
+{{- /*
+For a given taxonomy, renders a list of terms assigned to the page.
+
+@context {page} page The current page.
+@context {string} taxonomy The taxonomy.
+
+@example: {{ partial "terms.html" (dict "taxonomy" "tags" "page" .) }}
+*/}}
+
+{{- $page := .page }}
+{{- $taxonomy := .taxonomy }}
+
+{{- with $page.GetTerms $taxonomy }}
+  {{- $label := (index . 0).Parent.LinkTitle }}
+  <div>
+    <div>{{ $label }}:</div>
+    <ul>
+      {{- range . }}
+        <li><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></li>
+      {{- end }}
+    </ul>
+  </div>
+{{- end }}

themes/own-theme/theme.toml

@@ -0,0 +1,31 @@
+name = 'the theme'
+# license = ''
+# licenselink = 'https://github.com/owner/repo/LICENSE'
+# description = 'Theme description'
+#
+# # The home page of the theme, where the source can be found
+# homepage = 'https://github.com/owner/repo'
+#
+# # If you have a running demo of the theme
+# demosite = 'https://owner.github.io/repo'
+#
+# # Taxonomy terms
+# tags = ['blog', 'company']
+# features = ['some', 'awesome', 'features']
+#
+# # If the theme has multiple authors
+# authors = [
+#   {name = 'Name of author', homepage = 'Website of author'},
+#   {name = 'Name of author', homepage = 'Website of author'}
+# ]
+#
+# # If the theme has a single author
+# [author]
+#   name = 'Your name'
+#   homepage = 'Your website'
+#
+# # If porting an existing theme
+# [original]
+#   author = 'Name of original author'
+#   homepage = 'Website of original author'
+#   repo = 'https://github.com/owner/repo'