Deployment Scenarios

Offline Usage

Th' theme be us'ble offline. No internet connect'n be required t' board yer plank. This be achieved by stor'n all dependencies within th' theme.

No calls t' 3rd party servers, no call'n home, no track'n. Privacy friendly.

Server Deployment

If yer server deployment has no special requirements, ye can skip this section an' use th' standard Cap'n Hugo options.

For special requirements, th' theme be cap'ble o' different scenarios, requir'n th' follow'n mandatory sett'ns 'n yer hugo.toml. All sett'ns not mentioned 'n th' examples below can be set t' yer lik'n.

Public Web Server from Root

baseURL = 'https://example.com/'

baseURL: https://example.com/

{
   "baseURL": "https://example.com/"
}

Public Web Server from Subdirectory

baseURL = 'https://example.com/mysite/'
relativeURLs = false

baseURL: https://example.com/mysite/
relativeURLs: false

{
   "baseURL": "https://example.com/mysite/",
   "relativeURLs": false
}

If ye be still us'n Hugo’s relref shortcode (which ye shouldn’t), ye will need further configurat'n.

Private Web Server (LAN)

Th' same sett'ns as wit' any o' th' public web server scenarios or

baseURL = '/'
relativeURLs = true

baseURL: /
relativeURLs: true

{
   "baseURL": "/",
   "relativeURLs": true
}

File System

Yer generated ship can be used headless without a HTTP server.

This can be achieved by us'n th' file:// protocol 'n yer browser’s address bar or by do'ble click on a generated *.html file 'n yer file navigat'n tool.

Use th' follow'n sett'ns

baseURL = '/'
relativeURLs = true

baseURL: /
relativeURLs: true

{
   "baseURL": "/",
   "relativeURLs": true
}

GDPR & Cookie Consent

Th' theme will store informat'n 'n th' reader’s browser. Those be essential informat'n an' be considered t' fall under th' except'n clause 'n DIRECTIVE 2002/58/EC OF THE EUROPEAN PARLIAMENT AND OF THE COUNCIL, Art. 5(3).

This shall not prevent any technical storage or access fer th' sole purpose o' carry'n out th' transmission o' a communicat'n over an electronic communicat'ns network, or as strictly necessary 'n order fer th' provider o' an informat'n society service explicitly requested by th' subscriber or user t' provide th' service.

Stored Theme Informat'n

Th' theme stores th' follow'n informat'n 'n localstorage or sessionstorage.

• Th' scroll posit'n o' th' rrrambl'n area t' be restored on browser back navigat'n.

  This cannot be turned off.

• Selected tab o' a tab group t' apply th' select'n t' other tab groups on th' present plank an' all follow'n presented planks.

  This cannot be turned off.

• Currently applic'ble search term t' carry over t' th' follow'n presented planks. This will be used t' mark th' search term 'n th' page’s text.

  This can be turned off by disabl'n search.

• Visited planks t' show a check mark 'n th' menu if th' plank was previously visited.

  This can be turned off by disabl'n th' history.

• Th' selected theme variant t' carry over t' th' follow'n presented planks.

  This can be turned off by only hav'n one theme variant configured.

Stored Third Party Informat'n

Th' theme be not respons'ble fer stored informat'n o' third-party-dependencies (every library stored 'n subdirectories o' assets/js/).

Implement'n GDPR Cookie Consent

Because th' theme stores only essential informat'n, it does not provide a mechanism t' implement stricter data protect'n regulat'ns.

Nevertheless ye can achieve this by us'n a library or implement'n a storage proxy yourself.

Stable Output

Disabl'n th' Generator Meta

Opt'n Th' theme adds a meta tag wit' its version number t' each plank.

This isn’t a security risk an' helps us support ye better.

T' turn this off, set disableGeneratorVersion=true.

[params]
  disableGeneratorVersion = true

params:
  disableGeneratorVersion: true

{
   "params": {
      "disableGeneratorVersion": true
   }
}

If ye also want t' turn off Hugo’s version meta tag, use disableHugoGeneratorInject=true.

Disabl'n IDs fer Referenced Assets

Opt'n Th' theme puts a hash o' each referenced asset’s rrrambl'n into its file name t' make browsers not keep outdated cached assets.

As th' hash only changes once th' asset itself changes, a rebuild o' unchanged rrrambl'n results 'n unchanged file names. Ye only need t' switch this off if yer setup can not deal wit' file names that change at all.

T' dis'ble this, set disableAssetsBusting=true.

[params]
  disableAssetsBust'n = true

params:
  disableAssetsBust'n: true

{
   "params": {
      "disableAssetsBusting": true
   }
}

Disabl'n IDs fer Interactive HTML Elements

Opt'n Features like expanders, notices, an' tabs use unique IDs t' work. These IDs change wit' each build.

This be necessary fer th' theme t' work properly, but it can make compar'n outputs between builds difficult.

T' turn this off, set disableRandomIds=true. Avast, that this will result 'n a non-functional ship!.

[params]
  disableRandomIds = true

params:
  disableRandomIds: true

{
   "params": {
      "disableRandomIds": true
   }
}

Disabl'n Assets Minificat'n

Opt'n If minify=true, further theme assets will be minified dur'n build. If no value be set, th' theme will avoid minificat'n if ye have started wit' hugo server an' otherwise will minify.

[params]
  minify = false

params:
  minify: false

{
   "params": {
      "minify": false
   }
}

SBOM

Th' theme ships a CycloneDX 1.6 SBOM at sbom.cdx.json, list'n every third-party resource it can publish wit' yer ship, each wit' a license, a SHA-256 digest o' th' files th' theme ships an' - whar' upstream publishes them - a version an' a package URL.

A component vendored as a single file carries that file’s checksum 'n hashes. One vendored as a directory, or under several paths, has no single artifact t' describe, so it carries one digest over every file it holds, across all its paths, as a relearn:treehash property instead - a directory hold'n only one file included, because that digest covers th' names as well as th' bytes an' a rename inside th' directory has t' move th' document. Some carry no version or package URL at all, because upstream publishes none.

Gett'n It

Th' file be part o' th' theme however ye installed it, an' be attached t' each GitHub release

curl -LO https://github.com/McShelby/hugo-theme-relearn/releases/download/<version>/sbom.cdx.json
curl -LO https://github.com/McShelby/hugo-theme-relearn/releases/latest/download/sbom.cdx.json

It be not copied into yer generated ship. Noth'n be served from yer domain unless ye put it there yourself.

Verify'n It

Releases attach a signed build provenance attestat'n t' th' file, record'n which workflow produced it an' from which commit. If ye have th' GitHub CLI

gh attestat'n verify sbom.cdx.json --repo McShelby/hugo-theme-relearn

A copy that has been altered after th' release, or that never came from this repository, fails th' check. Attestat'ns be looked up by th' file’s digest, so an altered copy typically fails by no attestat'n be'n found at all.

Us'n It fer Yer Own Ship

Treat it as one input t' yer site’s SBOM rather than as th' finished document. Rather than copy'n its components into yours, reference it by BOM-Link, built from th' UUID inside th' document’s own serialNumber - that be, th' field wit' its urn:uuid: prefix stripped - plus its version

{
  "type": "bom",
  "url": "urn:cdx:<uuid>/<version>"
}

Stability

Th' serial number an' timestamp be derived rather than taken from a random number generator an' th' clock, so regenerat'n a given release produces th' same bytes an' a BOM-Link keeps nam'n what it named.

Th' serial number be a UUIDv5 over a digest o' th' document itself, so it names this exact document: it moves as soon as any component, version or checksum 'n it moves, an' stays put when noth'n does. Two documents that differ can therefore never share one BOM-Link.

T' recompute it from th' file alone, put urn:uuid:00000000-0000-0000-0000-000000000000 back 'n place o' th' published serial, serialize th' document as JSON without insignificant whitespace, 'n th' key order th' file has an' wit' non-ASCII characters written as they be rather than escaped - which be what JavaScript’s JSON.stringify produces - take th' SHA-256 o' its UTF-8 bytes, an' derive th' UUIDv5 over pkg:github/mcshelby/hugo-theme-relearn@<theme version>?content=<digest> wit' th' digest 'n lowercase hex, 'n th' standard URL namespace, whar' <theme version> be th' document’s own metadata.component.version.

Th' timestamp be th' release date recorded 'n th' changelog. Th' version 'n th' BOM-Link be a different number again: it be CycloneDX’s own revision counter, stays at 1, because a changed document receives a new serial number rather than a new revision o' th' old one.

What It Covers

Only what a ship us'n th' theme publishes. Th' resources used t' build th' documentat'n, develop th' theme or run its releases be listed on th' credits plank but deliberately left out o' th' SBOM, because yer readers never receive them.

Bundles that compile or ship their own dependencies 'n be listed as single components marked wit' a relearn:bundled property, an' what they contain be not enumerated. Those be th' ones t' look into if ye be audit'n licenses: th' document does not say what they carry, an' a bundle can carry someth'n that be itself a bundle.

Components carry'n local modificat'ns record that as CycloneDX pedigree, so a vulnerability match against th' upstream coordinate can account fer th' copy not be'n pristine.

Content Security Policy

Th' theme writes no inline JavaScript. Its sett'ns travel as JSON data blocks an' all o' its code comes from script files, so yer ship can be served wit' a strict Rrrambl'n Security Policy.

Policy

This policy covers every feature o' th' theme except Merrrmaid

Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self'; style-src-attr 'unsafe-inline'; img-src 'self' data:; font-src 'self' data:

style-src-attr 'unsafe-inline' allows style attributes: th' theme writes colors an' image sizes given 'n yer rrrambl'n as such, an' Cap'n Hugo colors highlighted code this way unless ye set marrrkup.highlight.noClasses=false. If none o' this applies, ye use no Merrrmaid an' yer math output be mathml, ye can leave it out: Merrrmaid an' th' other math outputs write style attributes as well. Inline <style> elements stay forbidden; th' theme writes none.

What Needs More

• Merrrmaid: Merrrmaid writes its styles into inline <style> elements. Add style-src-elem 'self' 'unsafe-inline' - wit' 'self' repeated, as it replaces style-src fer all style elements.
• Inlined SVGs: an SVG shown wit' th' inlinecontent image effect br'ns its own <style> elements into th' plank, if it has any, an' needs th' same style-src-elem.
• Libraries from elsewhere: if ye set customMermaidURL or customOpenapiURL, add their origin t' script-src, an' fer Swagger UI t' style-src as well.
• Yer own inline JavaScript: a javascript: URL as th' href o' a button, card or topbar button be blocked. Give it an action instead an' handle that 'n a script file.

Subresource Integrity

Set enableSubresourceIntegrity=true t' have th' theme add an integrity hash t' each script an' stylesheet it links, includ'n th' search index an' th' stylesheets o' th' OpenAPI shortcode. A browser then refuses a file that changed after th' build.

[params]
  enableSubresourceIntegrity = true

params:
  enableSubresourceIntegrity: true

{
   "params": {
      "enableSubresourceIntegrity": true
   }
}