Docs Infrastructure

On this page

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

Crossplane 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/geekboot 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/geekboot/assets folder contains all (S)CSS and compiled JavaScript for the website.

CSS

Crossplane documentation uses Bootstrap 5.2. Unmodified Bootstrap SCSS files are in /themes/geekboot/assets/scss/bootstrap/. Any docs-specific overrides are in per-element SCSS files located one directory higher in /themes/geekboot/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/geekboot/assets/scss/_variables.scss.

Provide theme specific color overrides in /themes/geekboot/assets/scss/light-mode.scss or /themes/geekboot/assets/scss/light-mode.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.

For production (publishing on Netlify or using hugo server --environment production) 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.

To make local development there are no run-time dependencies for JavaScript.

Runtime JavaScript is in /themes/geekboot/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.
tabDeepAnchor.js rewrites anchor links inside tabs to open a tab and present the anchor.
globalScripts.js is the point of entry for Webpack to determine all dependencies. This bundles instant.page and Bootstrap’s JavaScript.

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.

By importing only the necessary Bootstrap JavaScript features, reduces the bundle size.

Annotated website tree

Expand the tab below to see an annotated tree output of the website repository.

 1tree .
 2├── content                     # Root for all page content
 3│   ├── master
 4│   ├── v1.10
 5│   ├── v1.8
 6│   └── v1.9
 7├── themes                      # Entry point for theme-specific designs
 8│   └── geekboot
 9│       ├── assets              # JS and stylesheets
10│       │   ├── js              # Bundled and optmized Javascript
11│       │   └── scss            # Bootstrap SCSS overrides
12│       │       └── bootstrap   # Bootstrap original SCSS files
13│       ├── data
14│       ├── layouts             # HTML layouts and shortcodes
15│       │   ├── _default        # HTML layouts for page types
16│       │   │   └── _markup     # Hugo render hooks
17│       │   ├── partials        # HTML Template elements
18│       │   │   ├── icons
19│       │   │   └── utils
20│       │   └── shortcodes      # Shortcode features
21│       └── static              # Static files across the theme.
22│           ├── fonts           # Font files
23│           └── img             # Global images
24└── utils                       # Files unrelated to Hugo
25    └── webpack                 # Files managed or related to webpack
26        └── src
27            └── js
28                └── bootstrap/          # Original Bootstrap JavaScript
29                └── colorMode.js        # Color theme switcher
30                └── customClipboard.js  # Defines where to put a clipboard icon and what to copy
31                └── hoverHighlight.js   # Enables hover to highlight
32                └── tabDeepAnchor.js    # Enable anchors inside tabs