Bootstrap Deployment & Usage Guide

Complete guide for building the Bootstrap framework and running the documentation site locally.

Prerequisites

Node.js: Version 18.14.1 or higher (required for Astro)
Package Manager: npm (v8+), Yarn (v1.22+), or pnpm
Git: For cloning and version control
Optional: Python 3.x (for some legacy build scripts if applicable)

Installation

Clone the repository:

git clone https://github.com/twbs/bootstrap.git
cd bootstrap

Install dependencies:
```
npm install
```
Verify data files (required for docs site): Ensure YAML data files exist in site/data/ (breakpoints.yml, colors.yml, config.yml, etc.). These are validated at runtime against Zod schemas.

Configuration

Site Configuration (`site/data/config.yml`)

The documentation site uses YAML-based configuration loaded via src/libs/data.ts:

docs_version: "5.3"        # Current documentation version
baseURL: "/"               # Base URL for deployment
anchors:
  min: 2                   # Minimum heading level for TOC
  max: 3                   # Maximum heading level for TOC

Environment Variables

BASE_URL: Override the base URL for subdirectory deployments (e.g., /bootstrap/)
NODE_ENV: Set to production for production builds (enables versioned docs path validation)

Auto-Imported Components

Components in site/src/components/shortcodes/ are auto-imported across all MDX files. Do not delete this directory or the dev server will fail to resolve placeholders and shortcodes.

Static File Aliases

The following paths are automatically aliased (configured in src/libs/astro.ts):

/apple-touch-icon.png → /docs/[version]/assets/img/favicons/apple-touch-icon.png
/favicon.ico → /docs/[version]/assets/img/favicons/favicon.ico

Build & Run

Development (Documentation Site)

Start the Astro dev server with hot reloading:

npm run dev

URL: http://localhost:4321 (default Astro port)
MDX files are processed with custom remark plugins (remarkBsConfig, remarkBsDocsref)
Auto-imported components from shortcodes/ directory are available globally

Production Build (Documentation)

Generate the static site:

npm run build

Output directory: dist/ (configurable via Astro)
Validates all versioned docs paths (throws error if [[docsref:...]] links point to non-existent files)
Generates sitemap (excludes /404, /docs, and current version root)

Build Framework Only (CSS/JS)

If you only need the Bootstrap framework assets:

npm run dist

This compiles Sass and bundles JavaScript to the dist/ folder without building the docs site.

Available Scripts

npm run css: Compile Sass files
npm run js: Compile JavaScript bundles
npm run test: Run JS test suite (Karma/Jest depending on version)

Deployment

Static Site Hosting (Documentation)

The Astro build generates static HTML suitable for any static host:

Netlify/Vercel:

Build command: npm run build
Publish directory: dist
Set BASE_URL environment variable if using a custom domain or subdirectory

GitHub Pages:

npm run build
# Deploy dist/ folder to gh-pages branch

Docker:

FROM node:18-alpine
WORKDIR /app
COPY . .
RUN npm ci && npm run build
FROM nginx:alpine
COPY --from=0 /app/dist /usr/share/nginx/html

CDN Deployment (Framework)

For distributing the compiled CSS/JS:

npm: Published as bootstrap package
jsDelivr: Automatic CDN from GitHub releases
Unpkg: https://unpkg.com/bootstrap@5.3.8/dist/css/bootstrap.min.css

Troubleshooting

"A versioned docs path was generated but does not point to a valid page"

Cause: A [[docsref:/path]] link in MDX files points to a non-existent file.
Solution: Check the path in the error message exists in site/content/docs/[version]/ or correct the link.

Placeholder components not rendering

Cause: Missing shortcode components or htmlparser2 errors.
Solution: Ensure site/src/components/shortcodes/Placeholder.astro exists. Restart dev server if you add new components to auto-imported directories.

YAML validation errors

Cause: Data files in site/data/ don't match Zod schemas defined in src/libs/data.ts.
Solution: Check that hex colors include the # prefix, arrays have required fields (breakpoint, abbr, name), and semver versions follow x.y.z format.

Sharp/image processing failures

Cause: Native dependency issues with image optimization.
Solution:

npm install sharp
# Or disable image optimization in astro.config if not needed

Config replacement not working

Cause: [[config:key]] syntax not being processed.
Solution: Ensure the remark plugin is loading. Check that config keys exist in site/data/config.yml. Nested keys use dot notation: [[config:anchors.min]].

Sass compilation errors

Cause: Node-sass compatibility issues.
Solution: Bootstrap uses Dart Sass. Ensure you're using sass package not node-sass:

npm ls sass

How to Deploy & Use twbs/bootstrap