Customizing the Website
Cambium is designed to make good-looking websites by default, as well as have several levels of customization, which make small tweaks easy and entirely custom designs possible. This page covers the options you have for customizing the design of your website.
Configuration file options
A few options for website design are present in the configuration file. The theme entry allows you to select the all-in-one package to use as a starting point, and beyond that, there is the theme_config key. The site_name is also used by the theme.
theme_config allows for simple theme configuration, without creating any additional files. Currently it can have the key default_colour_mode which defines whether the website should default to dark or light mode. If default_colour_mode is not set, the default colourscheme is chosen by the theme designer.
An example snippet of a configuration file might be:
site_name: Cambium Documentation
theme: maple
theme_config:
default_colour_mode: dark
Reusable content
Cambium can read specially named files as custom pieces of re-usable content. These files are located in the .cambium/ folder, and are identified by the file name - without the extension.
Site menu
Cambium will automatically generate a list of links that can be used as a menu. All pages in the top level of your website (/page-name.html), and index pages of the next level down (/directory-name/index.html) will be included. Your theme may choose how and where to display the menu items.
If you would like to customize which pages are visible in the menu (or re-arrange the pages that are there), you can create a file in .cambium/ with the name menu.
If this file has a .md extension, Cambium will turn the contents into HTML before displaying it. Otherwise, the contents will be used directly in your website. This means that if you would like a very customized menu, you can create .cambium/menu.html and populate it however you like.
Note
When creating custom menu files, always use absolute links (starting with
/) rather than relative links.
An example menu.md might be:
- [Home](/index.html)
- [Get Started](/get-started.html)
- [Configuration File](/config-file.html)
- [PyPI](https://pypi.org/project/cambium/)
Favicon
Cambium provides a default favicon of the Cambium logo. To replace it, place your own image (must have the extension .png) at static/images/favicon.png. To use other filetypes see Advanced Customization.
Footer content
By default, Cambium generates some text that can be used as a copyright line, with the copyright symbol, site name, and current year. Maple displays this text in both the page footer and at the bottom of the site menu.
This text can be replaced in the same manner as the site menu with a .cambium/footer_content file. Like the menu, you can use any file extension, but .md will signal to Cambium to convert the contents to HTML, allowing for simple use of formatting and links.
Custom CSS
Cambium allows you to create additional CSS files which can add to or override the styling provided by your theme. If either of static/custom.css or .cambium/custom.css is present, Cambium will place it in the build directory at static/custom.css, and load it on every page.
To override the Cambium CSS variables, define your preferred versions inside the :root pseudo-class. For example, to set the primary colour to white when in dark mode:
:root {
--cambium-primary-colour-dark: #000000;
}
To assist in page-specific styling, Cambium applies a unique id to the html tag on each page. This id is generated from the final path to that page, for example, a when Cambium creates the file docs/extra-info.html, it will add id="cambium-page-docs-extra-info" to the html tag.
Combining CSS files
If you would like to use multiple CSS files, we recommend combining them with the @import rule. Keep in mind that from the .cambium/ folder, only custom.css will be copied to the build directory. Therefore, for this case, we recommend writing all of your CSS files in static/, and using relative imports from there.
Cambium CSS variables
Cambium and its themes define many CSS variables to ensure consistent styling and make customization easy. These are prefixed with either --cambium- or --cw-, to differentiate them from any variables you may wish to use separately.
The most useful CSS variables are listed below, along with their default values in the Maple theme.
Colours
The most commonly changed CSS variables are the colours. There are light and dark versions for each colour (for use in light and dark mode, respectively).
| Description | Variables | Maple Value |
|---|---|---|
| Primary colour, used for the main accents | --cambium-primary-colour-light--cambium-primary-colour-dark |
indianred#cba6a6 |
| Secondary colour, used mainly as a hover colour | --cambium-secondary-colour-light--cambium-secondary-colour-dark |
oklch(from var(--cambium-primary-colour-light) 45% calc(c * 1.1) h)oklch(from var(--cambium-primary-colour-dark) 85% calc(c * 0.8) h) |
| Background colour, used for all page backgrounds | --cambium-background-colour-light--cambium-background-colour-dark |
white#1a1a1a |
| Alternate background colour, used in places where a subtle difference from the main background is needed (i.e. tables) | --cambium-alternate-background-colour-light--cambium-alternate-background-colour-dark |
rgb(230, 230, 230)#333333 |
| Font colour | --cambium-font-colour-light--cambium-font-colour-dark |
black#f9f9f9 |
| Secondary font colour, used for places where the font should be less prominent | --cambium-secondary-font-colour-light--cambium-secondary-font-colour-dark |
#595959#a9a9a9 |
| Border colour | --cambium-border-colour-light--cambium-border-colour-dark |
Font
The font used across your Cambium website is set by the following variables. If you want to use a different font, MDN's styling fundamentals has a list of commonly available fonts and how to use them. To use font families outside of this list, you will have to import the font inside your custom.css file (see MDN's tutorial on font families for more information on how to go about this).
| Description | Variables | Maple Value |
|---|---|---|
| Font size for main body text. Font sizes for mobile and template are calculated from this value | --cambium-font-size |
16pt |
| The font family | --cambium-font-family |
"Source Sans 3 VF", sans-serif |
| The font weight, or how thick the font is | --cambium-font-weight |
400 |
| Monospace font family, used for code | --cambium-monospace-font-family |
"Intel One Mono VF", monospace |
Advanced customization
In some cases, you may wish to replace some of the files used by a theme in their entirety. This may include the CSS, JavaScript, image assets, or Jinja templates used to generate HTML. In this case, you can create the folder .cambium/theme/.
For non-template files, Cambium will copy anything from the directories .cambium/theme/static/ and static/ into the build directory under static/. If you include files which would overwrite ones provided by the theme, your files will always take precedence. This is the same principle as is used with the favicon.
If this theme directory contains a subfolder templates/, files there will override the Jinja templates provided by Cambium, assuming matching names. For example, the file .cambium/theme/templates/footer.html.jinja would be called in place of the footer.html.jinja provided by Maple.
To use a non-png file as a favicon, you would create .cambium/theme/templates/favicon.html.jinja, overriding the Cambium core template, and include your own link tag. You will need to use either an absolute link to the file, or the Jinja variable relative_path_modifier, which is calculated for each individual page on your site.
For example, to use an SVG favicon located at assets/favicon.svg, your template would contain:
<link
rel="icon"
type="image/svg+xml"
href="{{ relative_path_modifier }}assets/favicon.svg"
/>