runtimeterror/content/posts/the-slash-page-scoop/index.md at 293dbd13c57ef755a29791118edc9dfe47b254e7

john/runtimeterror

Fork 0

mirror of https://github.com/jbowdre/runtimeterror.git synced 2024-11-22 23:12:19 +00:00

John Bowdre 293dbd13c5 update draft

2024-06-01 21:27:25 -05:00

9.2 KiB

Raw Blame History

title

date

draft

description

featured

toc

Implementation

All of my typical blog posts get created within the site's Hugo directory under content/posts/, like this one at content/posts/the-slash-page-scoop/index.md. They get indexed, automatically added to the list of posts on the home page, and show up in the RSS feed. I don't want my slash pages to get that treatment so I made them directly inside the content directory:

content
├── categories
├── posts
├── search
├── 404.md
├── _index.md
├── about.md [tl! ~~]
├── changelog.md  [tl! ~~]
├── colophon.md  [tl! ~~]
├── homelab.md  [tl! ~~]
├── save.md  [tl! ~~]
├── simplex.md
└── uses.md  [tl! ~~]

Easy enough, but I didn't then want to have to worry about manually updating a list of slash pages so I used Hugo's Taxonomies feature for that. I simply tagged each page with a new slashes category by adding it to the post's front matter:

# torchlight! {"lineNumbers":true}
---
title: "/changelog"
date: "2024-05-26"
lastmod: "2024-05-30"
description: "Maybe I should keep a log of all my site-related tinkering?"
categories: slashes # [tl! ~~]
---

{{% notice note "Category Names" %}} I really wanted to name the category /slashes, but that seems to trip up Hugo a bit when it comes to creating an archive of category posts. So I settled for slashes and came up with some workarounds to make it present the way I wanted. {{% /notice %}}

Hugo will automatically generate an archive page for a given taxonomy term (so a post tagged with the category slashes would be listed at $BASE_URL/category/slashes/), but I like to have a bit of control over how those archive pages are actually presented. So I create a new file at content/categories/slashes/_index.md and drop in this front matter:

# torchlight! {"lineNumbers":true}
---
title: /slashes
url: /slashes
aliases:
  - /categories/slashes
description: >
  My collection of slash pages.  
---

The slashes in the file path tells Hugo which taxonomy it belongs to and so it can match the appropriately-categorized posts.

Just like with normal posts, the title field defines the title (duh) of the post; this way I can label the archive page as /slashes instead of just slashes.

The url field lets me override where the page will be served, and I added /categories/slashes as an alias so that anyone who hits that canonical URL will be automatically redirected.

Setting a description lets me choose what introductory text will be displayed at the top of the index page, as well as when it's shown at the next higher level archive (like /categories/).

Of course, I'd like to include a link to slashpages.net to provide a bit more info about what these pages are, and I can't add hyperlinks to the description text. What I can do is edit the template which is used for rendering the archive page. In my case, that's at layouts/partials/archive.html, and it starts out like this:

# torchlight! {"lineNumbers":true}
{{ $pages := .Pages }}
{{ if .IsHome }}
  {{ $pages = where site.RegularPages "Type" "in" site.Params.mainSections }}
{{ end }}
<header class="content__header">
{{ if .IsHome }}
  <h1>{{ site.Params.indexTitle | markdownify }}</h1>
{{ else }}
  <h1>{{ .Title | markdownify }}{{ if eq .Kind "term" }}&nbsp;<a target="_blank" href="{{ .Permalink }}feed.xml" aria-label="Category RSS"><i class="fa-solid fa-square-rss"></i></a>&nbsp;</h1> <!-- [tl! ~~] -->
  {{ with .Description }}<i>{{ . }}</i><hr>{{ else }}<br>{{ end }}
{{ end }}{{ end }}
  {{ .Content }}
</header>

Line 9 is where I had already modified the template to conditionally add an RSS link for category archive pages. I'm going to tweak the setup a bit to conditionally render designated text when the page .Title matches /slashes:

# torchlight! {"lineNumbers":true}
{{ $pages := .Pages }}
{{ if .IsHome }}
  {{ $pages = where site.RegularPages "Type" "in" site.Params.mainSections }}
{{ end }}
<header class="content__header">
{{ if .IsHome }}
  <h1>{{ site.Params.indexTitle | markdownify }}</h1>
{{ else }}
  {{ if eq .Title "/slashes" }} <!-- [tl! **:3 ++:3 ] -->
    <h1>{{ .Title | markdownify }}</h1>
    <i>My collection of <a target="_blank" title="what's a slashpage?" href="https://slashpages.net">slash pages</a>.</i><hr>
  {{ else }}
    <h1>{{ .Title | markdownify }}{{ if eq .Kind "term" }}&nbsp;<a target="_blank" href="{{ .Permalink }}feed.xml" aria-label="Category RSS"><i class="fa-solid fa-square-rss"></i></a>&nbsp;</h1>
    {{ with .Description }}<i>{{ . }}</i><hr>{{ else }}<br>{{ end }}
  {{ end }} <!-- [tl! ** ++ ] -->
{{ end }}{{ end }}
  {{ .Content }}
</header>

So instead of rendering the description I defined in the front matter the archive page will show:

My collection of slash pages.

While I'm at it, I'd like for the slash pages themselves to be listed in alphabetical order rather than sorted by date (like everything else on the site). The rest of my layouts/partials/archive.html already handles a few different ways of displaying lists of content:

# torchlight! {"lineNumbers":true}
{{- if eq .Kind "taxonomy" }} <!-- [tl! reindex(15) ] -->
  {{- if eq .Title "Tags" }} <!-- [tl! **:1 ] -->
  {{/* list of all tags */}}
    <div class="tagsArchive">
    {{- range $key, $value := .Site.Taxonomies }}
      {{- $slicedTags := ($value.ByCount) }}
      {{- range $slicedTags }}
        {{- if eq $key "tags"}}
          <div><a href='/{{ $key }}/{{ (replace .Name "#" "%23") | urlize }}/' title="{{ .Name }}">{{ .Name }}</a><sup>{{ .Count }} </sup></div> <!-- [tl! ** ] -->
        {{- end }}
      {{- end }}
    {{- end }}
  </div>
  {{- else }}
  {{/* list of all categories */}} <!-- [tl! ** ] -->
    {{- range .Pages.ByDate.Reverse }}
      {{- $postDate := .Date.Format "2006-01-02" }}
      {{- $updateDate := .Lastmod.Format "2006-01-02" }}
      <article class="post">
        <header class="post__header">
          <h1><a href="{{ .Permalink }}">{{ .Title | markdownify }}</a></h1>
          <p class="post__meta">
            <span class="date">["{{ with $updateDate }}{{ . }}{{ else }}{{ .$postDate }}{{ end }}"]</span> <!-- [tl! ** ] -->
          </p>
        </header>
        <section class="post__summary">
          {{ .Description }} <!-- [tl! ** ] -->
        </section>
        <hr>
      </article>
    {{ end }}
  {{- end }}
{{- else }}
  {{/* regular posts archive */}} <!-- [tl! ** ] -->
    {{- range (.Paginate $pages).Pages }}
    {{- $postDate := .Date.Format "2006-01-02" }}
    {{- $updateDate := .Lastmod.Format "2006-01-02" }}
    <article class="post">
      <header class="post__header">
          <h1><a href="{{ .Permalink }}">{{ .Title | markdownify }}</a></h1>
          <p class="post__meta">
              <span class="date">["{{- $postDate }}"{{- if ne $postDate $updateDate }}, "{{ $updateDate }}"{{ end }}]</span> <!-- [tl! ** ] -->
          </p>
      </header>
      <section class="post__summary">
          {{if .Description }}{{ .Description }}{{ else }}{{ .Summary }}{{ end }} <!-- [tl! ** ] -->
      </section>
      <hr>
    </article>
    {{- end }}
    {{- template "_internal/pagination.html" . }}
{{- end }}

The tags archive (list of all tags) uses a very condensed format for displaying all the tags in one place.
Other archives of taxonomy pages (like the list of all categories) have the

9.2 KiB Raw Blame History

Implementation

9.2 KiB

Raw Blame History