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 and files unrelated to Hugo 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 and 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│   ├── contribute
 4│   ├── knowledge-base
 5│   ├── master
 6│   ├── v1.12
 7│   ├── v1.11
 8│   └── v1.10
 9├── themes                      # Entry point for theme-specific designs
10│   └── geekboot
11│       ├── assets              # JS and stylesheets
12│       │   ├── js              # Bundled and optmized Javascript
13│       │   └── scss            # Bootstrap SCSS overrides
14│       │       └── bootstrap   # Bootstrap original SCSS files
15│       ├── data
16│       ├── layouts             # HTML layouts and shortcodes
17│       │   ├── _default        # HTML layouts for page types
18│       │   │   └── _markup     # Hugo render hooks
19│       │   ├── partials        # HTML Template elements
20│       │   │   ├── icons
21│       │   │   └── utils
22│       │   └── shortcodes      # Shortcode features
23│       └── static              # Static files across the theme.
24│           ├── fonts           # Font files
25│           └── img             # Global images
26└── utils                       # Files unrelated to Hugo
27    └── vale                    # Files related to our Vale validation rules
28    └── webpack                 # Files managed or related to webpack
29        └── src
30            └── js
31                └── bootstrap/          # Original Bootstrap JavaScript
32                └── colorMode.js        # Color theme switcher
33                └── customClipboard.js  # Defines where to put a clipboard icon and what to copy
34                └── globalScripts.js    # The collection of things to load on all pages
35                └── hoverHighlight.js   # Enables hover to highlight
36                └── slackNotify.js      # Tooltip to prompt user to join the community Slack
37                └── tabDeepAnchor.js    # Enable anchors inside tabs