Vendored Bootstrap & Icon Assets

Bootstrap 5.3.3 CSS/JS and Bootstrap Icons are committed under assets/vendor/ rather than loaded from a CDN. This ensures:

• GitHub Pages safety — Pages’ default Jekyll build does not run npm or curl
• Offline development — works without an internet connection
• Version pinning — no surprise CDN updates breaking the theme

For full details on refreshing vendor files, see the Vendor Assets guide.

Directory Layout

assets/vendor/
├── bootstrap/
│   ├── css/
│   │   └── bootstrap.min.css
│   └── js/
│       └── bootstrap.bundle.min.js
└── bootstrap-icons/
    └── font/
        ├── bootstrap-icons.css
        └── fonts/

Additional vendor libraries (MathJax, Font Awesome, jQuery, GitHub Calendar) are also stored here and listed in vendor-manifest.json. Mermaid is the one exception: it lives under assets/vendor/mermaid/ but is not in the manifest — it is copied from the npm mermaid package via npm run vendor:mermaid instead of downloaded from a CDN.

How Assets Are Loaded

CSS (via _includes/core/head.html)

<link href="{{ '/assets/vendor/bootstrap/css/bootstrap.min.css' | relative_url }}" rel="stylesheet">
<link rel="stylesheet" href="{{ '/assets/vendor/bootstrap-icons/font/bootstrap-icons.css' | relative_url }}">
<link rel="stylesheet" href="{{ '/assets/css/main.css' | relative_url }}">

JavaScript (via _includes/components/js-cdn.html)

<script src="{{ '/assets/vendor/bootstrap/js/bootstrap.bundle.min.js' | relative_url }}"></script>

Refreshing Vendor Files

# Full vendor refresh (requires curl, jq, and shasum/sha256sum)
./scripts/vendor-install.sh

# Same thing via the npm script
npm run vendor:install

# Preview what would change without downloading
./scripts/vendor-install.sh --dry-run

# Refresh Mermaid (copied from the npm package, not the manifest)
npm install && npm run vendor:mermaid

vendor-manifest.json in the repo root lists every curl-downloaded asset with its expected SHA-256 checksum. The script is idempotent: it skips any file that already exists with a matching checksum, and re-downloads on mismatch (--force re-downloads everything).

How to verify

# Confirm the committed vendor tree is present
ls assets/vendor/bootstrap/css/bootstrap.min.css \
   assets/vendor/bootstrap/js/bootstrap.bundle.min.js \
   assets/vendor/bootstrap-icons/font/bootstrap-icons.css

# Dry-run reports "already up to date" when checksums match
./scripts/vendor-install.sh --dry-run

A clean checkout already ships these files, so a dry run should report nothing to download.

Custom CSS Override

Place site-specific CSS overrides in assets/css/user-overrides.css (you create this file; it is not shipped with the theme). It is linked from _includes/core/head.html only when you opt in by setting user_overrides: true in _config.yml — the link is wrapped in {% if site.user_overrides %}. Do not load a second full Bootstrap stylesheet.

Related

• Vendor Assets (Maintainer Guide)
• Bootstrap Integration
• Dependency Updates

See also

• [[Bootstrap Integration]]
• [[Development]]