Add thissite section with dates workflow explanation
New section documenting how this site works, starting with how created/lastmod dates flow through archetypes, git, and Hugo.
This commit is contained in:
parent
45b7bac831
commit
688fd8f16c
3 changed files with 117 additions and 0 deletions
4
site/content/thissite/_index.md
Normal file
4
site/content/thissite/_index.md
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
---
|
||||
title: "This Site"
|
||||
description: "How this site is built, configured, and maintained."
|
||||
---
|
||||
108
site/content/thissite/dates.md
Normal file
108
site/content/thissite/dates.md
Normal file
|
|
@ -0,0 +1,108 @@
|
|||
---
|
||||
title: "How Dates Work on This Site"
|
||||
date: 2026-04-03
|
||||
draft: false
|
||||
tags: ['hugo', 'git', 'workflow']
|
||||
---
|
||||
|
||||
Every page on this site has two dates: **Created** and **Last Modified**.
|
||||
Neither one is maintained by hand. Here's the full flow.
|
||||
|
||||
## Creating a new page
|
||||
|
||||
New content is created via Hugo's CLI (running in Docker):
|
||||
|
||||
```bash
|
||||
docker run --rm -v "${SITE_DIR}:/src" -w /src \
|
||||
ghcr.io/gohugoio/hugo:latest new content/thissite/my-page.md
|
||||
```
|
||||
|
||||
Hugo reads the archetype template at `archetypes/default.md`:
|
||||
|
||||
```yaml
|
||||
+++
|
||||
date = '{{ .Date }}'
|
||||
draft = true
|
||||
title = '{{ replace .File.ContentBaseName "-" " " | title }}'
|
||||
tags = []
|
||||
+++
|
||||
```
|
||||
|
||||
At creation time, Hugo substitutes `{{ .Date }}` with the current
|
||||
timestamp and writes it into the new file's front matter. The result
|
||||
looks like:
|
||||
|
||||
```yaml
|
||||
---
|
||||
date: 2026-04-03T14:30:00-04:00
|
||||
draft: true
|
||||
title: "My Page"
|
||||
tags: []
|
||||
---
|
||||
```
|
||||
|
||||
**That `date` value is baked into the file once and never changes.**
|
||||
It represents when the page was created. Nobody edits it afterward.
|
||||
|
||||
## How "Last Modified" works
|
||||
|
||||
The `lastmod` field is **not** stored in the file at all. It's resolved
|
||||
at build time by Hugo based on this config in `hugo.toml`:
|
||||
|
||||
```toml
|
||||
enableGitInfo = true
|
||||
|
||||
[frontmatter]
|
||||
date = [':default']
|
||||
lastmod = [':git', ':fileModTime']
|
||||
```
|
||||
|
||||
The resolution chain for `lastmod`:
|
||||
|
||||
1. **`:git`** — Hugo calls `git log` to find the author date of the most
|
||||
recent commit that touched the file. This is the primary source.
|
||||
2. **`:fileModTime`** — Fallback to the filesystem modification time
|
||||
(useful when the file hasn't been committed yet, e.g. during local
|
||||
preview).
|
||||
|
||||
So when Hugo builds the site, it inspects the git history for each
|
||||
content file and injects `.Lastmod` into the page context. Templates can
|
||||
then render it with `{{ .Lastmod }}`.
|
||||
|
||||
## What does git actually track?
|
||||
|
||||
Git records the **author date** on each commit. When you edit a file and
|
||||
commit it, that commit's date becomes the new `lastmod` for that file.
|
||||
The original `date` in front matter is untouched — it still reflects
|
||||
creation time.
|
||||
|
||||
```
|
||||
commit abc123
|
||||
Author: JM <jm@example.com>
|
||||
Date: Thu Apr 3 14:30:00 2026 -0400
|
||||
|
||||
Fix typo in dates page
|
||||
```
|
||||
|
||||
Hugo will see `Apr 3 14:30:00 2026` as the `lastmod` for any file
|
||||
modified in that commit.
|
||||
|
||||
## The full lifecycle
|
||||
|
||||
| Step | What happens | Where the date lives |
|
||||
|---|---|---|
|
||||
| `hugo new content/thissite/foo.md` | Archetype stamps `date` | In the file's front matter |
|
||||
| First `git commit` | Git records author date | In git history |
|
||||
| Edit the file later | `date` in front matter unchanged | Still in front matter |
|
||||
| `git commit` the edit | Git records a new author date | In git history |
|
||||
| `hugo build` | Hugo reads `date` from front matter, `lastmod` from git | Injected into page context at build time |
|
||||
|
||||
## Key points
|
||||
|
||||
- **Created date**: set once by the archetype, stored in front matter,
|
||||
never changes.
|
||||
- **Last modified**: not stored in the file. Resolved from git at build
|
||||
time. Zero maintenance.
|
||||
- **`enableGitInfo = true`** is required in `hugo.toml` for any of the
|
||||
git-based date resolution to work.
|
||||
- **No tracking needed** for `lastmod` — it's derived, not stored.
|
||||
|
|
@ -62,6 +62,11 @@ enableGitInfo = true
|
|||
name = "Config"
|
||||
url = "/config"
|
||||
weight = 11
|
||||
[[languages.en.menu.main]]
|
||||
identifier = "thissite"
|
||||
name = "This Site"
|
||||
url = "/thissite"
|
||||
weight = 12
|
||||
|
||||
[module]
|
||||
[[module.imports]]
|
||||
|
|
|
|||
Loading…
Reference in a new issue