Skip to content

Add short download URLs for three PDFs (+ fix the local build)#19

Merged
jansroka merged 3 commits into
mainfrom
feat/pdf-download-redirects
Jul 13, 2026
Merged

Add short download URLs for three PDFs (+ fix the local build)#19
jansroka merged 3 commits into
mainfrom
feat/pdf-download-redirects

Conversation

@jansroka

@jansroka jansroka commented Jul 13, 2026

Copy link
Copy Markdown
Contributor

Adds short, shareable download URLs for three PDFs, and fixes a pre-existing build break found along the way.

Download URLs

Each document is reachable in both cases (GitHub Pages serves from a case-sensitive filesystem, so /BN24 and /bn24 are genuinely different URLs and both need to exist):

URL Document
/1MATAG, /1matag ATAG, 1. Monat (Stand 02.07.2024)
/EGOM, /egom EGOM Working Group — EUdI Wallet Infrastructures
/BN24, /bn24 Bildet Netze! — Konsultationsprozesse

Only these exact-case pairs are covered — mixed case (/Egom, /Bn24) will still 404. That's fine for URLs handed out deliberately; say so if you want them covered too.

The PDFs are renamed to ASCII slugs; they arrived with spaces and dots in the filenames, which would have forced percent-encoding in every link.

Two things worth knowing before merging

These are not real 301s, and cannot be. GitHub Pages serves static files and cannot set a Location header, so each vanity URL is a 200 HTML page with a <meta http-equiv="refresh">. Browsers follow it fine, but curl/wget (and some bots) get the HTML shim rather than the PDF. Fine for a mailing, a slide, or a QR code — but anything automated should link the /documents/… path directly. Getting true 301s would mean putting a CDN in front of the domain (today www.inoeg.de resolves straight to GitHub's Pages IPs, no CDN); that's worth considering separately, mainly because it would also let us serve CSP/HSTS as real headers instead of the current weaker <meta> CSP.

The redirect layout is overridden (_layouts/redirect.html). jekyll-redirect-from's bundled layout redirects with an inline script tag, which this site's CSP (default-src 'self', no script-src 'unsafe-inline') blocks. The meta-refresh is not subject to CSP, so the override is what makes this work at all.

The case aliases are separate files on purpose

They are not redirect_from: entries on the sibling page. On a case-insensitive filesystem (macOS) Jekyll writes _site/bn24.html and _site/BN24.html to the same path, so the alias silently overwrites the real page — which produced a self-redirect loop (/BN24/BN24) on the first attempt. Separate source files pointing straight at the PDF cannot collapse that way.

Because macOS cannot reproduce the production filesystem, this was verified on a case-sensitive APFS volume (matching GitHub Pages): all six pages are written as distinct files, and each returns HTTP 200 application/pdf at the correct document.

Build fix (separate commit)

bundle exec jekyll build crashed on any shell without a UTF-8 locale:

jekyll/url.rb:161:in 'String#encode': "\xC3" from ASCII-8BIT to UTF-8 (Encoding::UndefinedConversionError)

With no LANG/LC_ALL, Ruby's default_external is US-ASCII, so filenames come back as ASCII-8BIT — and three existing PDFs carry umlauts (InÖG, Prüfsteine, Stärkung). This predates this branch: a pristine build of main fails identically. CI only stayed green because GitHub's Ubuntu runners happen to default to UTF-8, i.e. the build had an undeclared dependency on the developer's environment.

Fixed by pinning the encoding in the Gemfile, which every bundle exec loads. This avoids renaming the three German PDFs, which would break their live URLs. (Jekyll's own encoding: config key does not fix this — it governs file contents, not filenames.)

Verification

  • env -u LANG -u LC_ALL bundle exec jekyll build — completes (previously crashed)
  • html-proofer — 28 internal links, no failures
  • prettier — clean
  • All six URLs → HTTP 200, application/pdf, correct byte counts, on a case-sensitive volume

🤖 Generated with Claude Code

jansroka and others added 3 commits July 13, 2026 12:21
`bundle exec jekyll build` crashed on any shell without a UTF-8 locale:

    jekyll-4.4.1/lib/jekyll/url.rb:161:in 'String#encode':
    "\xC3" from ASCII-8BIT to UTF-8 (Encoding::UndefinedConversionError)

Cause: with no LANG/LC_ALL set, Ruby's default_external is US-ASCII, so
filenames read from disk come back as ASCII-8BIT. Three PDFs in documents/
contain umlauts (InÖG, Prüfsteine, Stärkung), and Jekyll's URL escaping calls
String#encode on them, which cannot convert ASCII-8BIT to UTF-8.

This predates this branch — a pristine build of main fails identically. CI only
stayed green because GitHub's Ubuntu runners happen to default to a UTF-8
locale, i.e. the build had an undeclared dependency on the developer's
environment.

Pinning the encoding in the Gemfile fixes it for every `bundle exec` invocation,
locally and in CI, and does not require renaming the German PDFs (which would
break their live URLs).

Note Jekyll's own `encoding:` config key does NOT fix this — it governs file
contents, not filenames.

Verified: `env -u LANG -u LC_ALL bundle exec jekyll build` now completes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Adds vanity URLs for three documents, plus lowercase aliases:

    /1MATAG, /1matag  -> ATAG, 1. Monat (Stand 02.07.2024)
    /egom             -> EGOM Working Group, EUdI Wallet Infrastructures
    /BN24, /bn24      -> Bildet Netze! Konsultationsprozesse

The PDFs are renamed to ASCII slugs (they arrived with spaces and dots in the
filenames, which forced percent-encoding in links).

Two non-obvious constraints shaped the implementation:

1. These cannot be real 301s. GitHub Pages serves static files and cannot set a
   Location header, so a vanity URL is a 200 HTML page with a meta-refresh.
   Browsers follow it; curl/wget get the HTML shim, not the PDF. Anything
   automated should use the /documents/... path directly.

2. The layout is overridden (_layouts/redirect.html). jekyll-redirect-from's
   bundled layout redirects with an inline script tag, which this site's CSP
   (default-src 'self', no script-src 'unsafe-inline') blocks. The meta-refresh
   is not subject to CSP.

The lowercase aliases are separate source files rather than `redirect_from:` on
the uppercase page. On a case-insensitive filesystem (macOS) Jekyll writes
_site/bn24.html and _site/BN24.html to the SAME path, so the alias silently
overwrites the real page and leaves a self-redirect loop (/BN24 -> /BN24).
Separate files pointing straight at the PDF cannot collapse that way.

Verified on a case-sensitive APFS volume (matching GitHub Pages, which macOS
cannot reproduce): all five pages are written as distinct files and each
redirects to the correct PDF, each returning HTTP 200 application/pdf.
Build, prettier and html-proofer all pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
/egom had no uppercase counterpart, unlike /1MATAG and /BN24 which both got
lowercase aliases. GitHub Pages serves from a case-sensitive filesystem, so
/EGOM would have 404'd.

Separate source file rather than `redirect_from:` for the same reason as the
other aliases: on a case-insensitive filesystem Jekyll writes _site/egom.html
and _site/EGOM.html to the same path, and the alias silently overwrites the
real page, leaving a self-redirect loop.

Verified on a case-sensitive APFS volume: all six URLs (/1MATAG, /1matag,
/BN24, /bn24, /EGOM, /egom) return HTTP 200 application/pdf at the correct
document.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@jansroka jansroka merged commit 9266cef into main Jul 13, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant