hugo_bootstrap_theme/README.md

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:

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:

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

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