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"
|
name = "Config"
|
||||||
url = "/config"
|
url = "/config"
|
||||||
weight = 11
|
weight = 11
|
||||||
|
[[languages.en.menu.main]]
|
||||||
|
identifier = "thissite"
|
||||||
|
name = "This Site"
|
||||||
|
url = "/thissite"
|
||||||
|
weight = 12
|
||||||
|
|
||||||
[module]
|
[module]
|
||||||
[[module.imports]]
|
[[module.imports]]
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue