danielandClaude Sonnet 5
13fb67a0f8
Displays a page's file resources as a responsive grid of cards with a thumbnail (explicit param, name-matched image, or a generic file icon), title, size and download link. Meant for a downloads page offering a handful of PDFs. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
133 lines
3.8 KiB
Markdown
133 lines
3.8 KiB
Markdown
# hugo_bootstrap_theme
|
|
|
|
Simple Bootstrap-based theme for Hugo.
|
|
|
|
|
|
## Shortcodes
|
|
|
|
### `lead`
|
|
|
|
Wraps its content in a Bootstrap `.lead` paragraph (the Markdown
|
|
attribute syntax `{.lead}` cannot target a paragraph):
|
|
|
|
```
|
|
{{< lead >}}
|
|
An introductory paragraph that stands out.
|
|
{{< /lead >}}
|
|
```
|
|
|
|
Pass extra classes with `class`, e.g. `{{< lead class="mb-5" >}}`.
|
|
|
|
### `banner`
|
|
|
|
A full-bleed banner / hero image: it spans the entire viewport width
|
|
while the rest of the page stays within `.container`. Put it on the
|
|
first line of a page's content to get a hero flush against the navbar.
|
|
|
|
```
|
|
{{< banner src="hero.png" alt="…" >}}
|
|
```
|
|
|
|
`src` is resolved as a page resource first, then a global resource
|
|
(`assets/`), then as a plain link respecting the site's base URL.
|
|
Optional params: `title`, `height` (a CSS length such as `60vh`, which
|
|
crops the image with `object-fit: cover`) and `class`.
|
|
|
|
### `resource-tiles`
|
|
|
|
Displays a page's file resources as a responsive grid of cards
|
|
("tiles"), each with a thumbnail, a title, the file size and a download
|
|
link. Meant for a downloads page that offers a handful of PDFs,
|
|
spreadsheets, archives, …
|
|
|
|
```
|
|
{{< resource-tiles >}}
|
|
```
|
|
|
|
Params:
|
|
|
|
| Param | Default | Meaning |
|
|
|---------|---------|--------------------------------------------------------|
|
|
| `match` | `*.pdf` | glob selecting which page resources to show |
|
|
| `cols` | `3` | number of columns on large screens |
|
|
| `sort` | — | resource field to order by (`title`, `name`, `weight`) |
|
|
| `class` | — | extra CSS classes for the wrapping row |
|
|
|
|
Thumbnails are resolved per resource, in order of preference:
|
|
|
|
1. a `thumbnail` param on the resource, pointing at an image in the same
|
|
page bundle;
|
|
2. an image resource whose name matches the file, e.g. `report.png` or
|
|
`report.pdf.png` next to `report.pdf`;
|
|
3. a generic file icon showing the upper-cased extension.
|
|
|
|
Hugo cannot rasterise PDFs itself, so first-page previews have to be
|
|
produced as a build step. With poppler-utils installed, generating a
|
|
`<name>.png` next to every PDF under `content/` is a one-liner:
|
|
|
|
```sh
|
|
find content -name '*.pdf' -exec sh -c \
|
|
'pdftocairo -png -singlefile -scale-to-x 600 -scale-to-y -1 "$1" "${1%.pdf}"' _ {} \;
|
|
```
|
|
|
|
Run it before `hugo`; the tiles then use these as thumbnails
|
|
automatically. (`pdftoppm` takes the same flags; `mutool draw` is an
|
|
alternative.)
|
|
|
|
Per-resource title, description and thumbnail come from the page's front
|
|
matter:
|
|
|
|
```yaml
|
|
resources:
|
|
- src: report.pdf
|
|
title: Annual report
|
|
params:
|
|
description: Everything that happened last year.
|
|
thumbnail: report-cover.png
|
|
```
|
|
|
|
The whole tile is a click target (Bootstrap `.stretched-link`).
|
|
|
|
|
|
## Navigation
|
|
|
|
The navbar renders the `main` menu. A top-level entry that has child
|
|
entries (other entries pointing at it with `parent:`) is rendered as a
|
|
Bootstrap dropdown; entries without children stay as plain links. Only
|
|
one level of nesting is supported (Bootstrap 5 has no nested submenus).
|
|
|
|
```yaml
|
|
# hugo.yaml / menus.yaml
|
|
menu:
|
|
main:
|
|
- name: Home
|
|
pageRef: /
|
|
weight: 1
|
|
- name: Research
|
|
weight: 2
|
|
- name: Proposals
|
|
parent: Research
|
|
pageRef: /proposals
|
|
weight: 1
|
|
- name: History
|
|
parent: Research
|
|
pageRef: /history
|
|
weight: 2
|
|
```
|
|
|
|
The entry matching the current page (and its parent, for a dropdown
|
|
child) gets Bootstrap's `active` class. A parent entry acts only as the
|
|
dropdown toggle, so it does not need its own `url`/`pageRef`.
|
|
|
|
|
|
## Custom error page
|
|
|
|
The theme has a custom 404 error page.
|
|
|
|
If the site has an SVG image in `assets/svg/404.svg`,
|
|
this image will be displayed instead of a generic 404
|
|
code. Regardless of whether an SVG assets exists or not,
|
|
English and German explanations of what's going on will
|
|
be included on the page.
|
|
|