Upbound Docs - Docs Infrastructure

Docs Infrastructure

The Upbound document website is in a unique website GitHub repository.

Upbound uses Hugo, a static site generator. Hugo influences the directory structure of the website repository.

The /content directory is the root directory for all documentation content.

The /themes/upbound directory is the root directory for all website related files, like HTML templates, shortcodes and global media files.

The /utils/ directory is for JavaScript source code used in the website.

The /themes/upbound/assets folder contains all (S)CSS and compiled JavaScript for the website.

CSS

Upbound documentation uses Bootstrap 5.3. Unmodified Bootstrap SCSS files are in /themes/upbound/assets/scss/bootstrap/. Any docs-specific overrides are in per-element SCSS files located one directory higher in /themes/upbound/assets/scss/.

Important

Don’t edit the original Bootstrap stylesheets. It makes the ability to upgrade to future Bootstrap versions difficult or impossible.

Color themes

Crossplane docs support a light and dark color theme that’s applied via CSS variables.

Universal and default variables are defined in /themes/upbound/assets/scss/_variables.scss.

Provide theme specific color overrides in /themes/upbound/assets/scss/_color-mode-dark.scss or /themes/upbound/assets/scss/_color-mode-light_.scss.

Note

When creating new styles rely on variables for any color function, even if both themes share the color.

SCSS compilation

Hugo compiles the SCSS to CSS. Local development doesn’t require SCSS installed.

For local development (when using hugo server) Hugo compiles SCSS without any optimizations.

Production deployments use the command hugo --environment production to trigger SCSS optimization.

Hugo compiles SCSS and optimizes the CSS with PostCSS. The PostCSS configuration is in /postcss.config.js. The optimizations includes:

postcss-lightningcss - for building, minimizing and generating a source map.
PurgeCSS - removes unused styles to reduce the CSS file size.
postcss-sort-media-queries- to organize and reduce CSS media queries to remove duplicate and unused CSS.

Optimizing CSS locally with PostCSS requires installing extra packages.

Sass
NPM
NPM packages defined in /package.json with npm install.

JavaScript

A goal of the documentation website is to use as little JavaScript as possible. Unless the script provides a significant improvement in performance, capability or user experience.

For local development, there are no run-time dependencies for JavaScript.

Runtime JavaScript is in /themes/upbound/assets/js/. Webpack has bundled, minified and compressed the JavaScript.

The source JavaScript is in /utils/webpack/src/js and requires Webpack to bundle and optimize the code.

colorMode.js provides the ability to change the light/dark mode color theme.
customClipboard.js creates the ability to define which lines to copy in code boxes.
globalScripts.js is the point of entry for Webpack to determine all dependencies. This bundles instant.page and Bootstrap’s JavaScript.
hoverHightlight enables the hover shortcode.
tabDeepAnchor.js rewrites anchor links inside tabs to open a tab and present the anchor.

Bootstrap JavaScript builder

The entire Bootstrap JavaScript source is in /utils/webpack/src/js/bootstrap.

Adding a new Bootstrap feature requires importing it in globalScripts.js.