# 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.