Theming Guide

Most of the visual attributes in the default template can be changed through CSS variables defined in this file. You can override these variables in your own projects by redefining some or even all of the variables. This way you can customize the appearance of your documentation making it look unique.

Font Settings

Having clear, legible fonts goes a long way making documentation readable and easy for eyes. The default template ensures that fonts look consistent for all users by downloading them from Google Fonts.

Customizing fonts begins with selecting three font families from three specific categories: sans, serif, and mono. Sans font is used for titles and captions, serif font for main text, and mono font for code snippets. Change the family attribute in the url below to import the desired font families and their weights and styles. After selecting these, copy the names of the font families to the CSS variables below.

@import "./samples.css";
@import "./basic-themes.css";
@import url('https://fonts.googleapis.com/css2?family=Source+Serif+4:ital@0;1&family=Cousine:wght@400;700&family=Nunito+Sans:opsz,wght@6..12,500;6..12,700&display=swap');

body {
    --sans-font: "Nunito Sans";
    --serif-font: "Source Serif 4";
    --mono-font: "Cousine";

Below are font samples for families used in the default template.

Sans Font

Serif Font

Mono Font

Color Scheme

Another easy way to make your documentation look unique is to change the color scheme. The scheme employed by the default template uses two main colors as a basis, and calculates light and dark variants automatically.

Primary and Secondary Colors

The primary color is used as a background color for page elements such as menus and separators. It is typically somewhat muted color that isn't too glaring. The secondary color is used to highlight things, so it should be the darker one. If the primary and sec colors are at the opposite sides of the color wheel, they usually look more pleasant to the eye.

    --col-prim: hsl(29, 69%, 92%);
    --col-prim-light: hsl(29, 69%, 100%);
    --col-prim-dark: hsl(29, 69%, 83%);
    --col-sec: hsl(5, 21%, 42%);
    --col-sec-light: hsl(5, 21%, 51%);
    --col-sec-dark: hsl(5, 21%, 33%);

Below are samples of the default prim and sec colors.

Primary Colors

Secondary Colors

Text and Background Colors

The main part of the page contains your actual documentation, and it is colored traditionally in black and white. However, you can tweak how black or white by overriding the @color-black and @color-white variables. The default colors are pretty close to absolute black and white.

When text is rendered on top of prim or sec colors, we use either black or white color depending on the luminance of the background color.

    --col-prim-text: var(--col-sec);
    --col-prim-text-light: var(--col-sec-light);
    --col-prim-text-dark: var(--col-sec-dark);
    --col-sec-text: var(--col-prim);
    --col-sec-text-light: var(--col-prim-dark);
    --col-sec-text-dark: var(--col-prim-light);

Navbar Styles

The first customizable UI element is the navigation bar, or navbar for short. It provides quick links to most important resources.

Text Transform

The transformation applied to navbar captions. Here are the valid options.

    --nav-text-transform: capitalize;

Padding and Margin

Horizontal and vertical padding and margin of navbar buttons are stored in these variables. Padding controls how much empty space is added inside buttons and margin outside the buttons. Note that horizontal margin is not editable. Horizontal layout of buttons is controlled by the @nav-button-justify variable.

    --nav-horz-padding: 0.5rem;
    --nav-vert-padding: 0.5rem;

Font Size

Navbar uses the @sans-font. This is not changeable. Nevertheless, you can set the size of the font with the following variable.

    --nav-font-size: 1.2rem;

Animation Speed

The speed for animations is controlled by @nav-transition variable.

    --nav-transition: 0.3s;

Button Justification and Spacing

Buttons are laid out using a flexbox. You can change how buttons are justified inside the flexbox by editing the @nav-button-justify variable. Its valid values can be found here.

To increase or reduce space between buttons, change the @nav-button-spacing variable.

    --nav-button-justify: flex-start;
    --nav-button-spacing: 0.5rem;
    --nav-border-radius: 4px;

Navbar Colors

The colors used in the buttons are listed below. There are separate background colors for normal and hover (nav-hl-backgound) state.

    --nav-bg-color: var(--col-sec-light);
    --nav-border-color: var(--col-sec);
    --nav-text-color: var(--col-prim);
    --nav-title-color: var(--col-prim-light);
    --nav-text-hover: var(--col-prim-light);
    --nav-icon-color: var(--col-prim-dark);

Calculated Values

The total height of the navbar and the size of the hamburger icon are calculated automatically. The only reason for changing the following variables is if the calculated sizes are not big enough for some reason.

    --nav-text-height: calc(1.3 * var(--nav-font-size));
    --nav-height: calc(var(--nav-text-height) + (var(--nav-vert-padding) * 2));
    --hamburger-height: var(--nav-text-height);

TOC Menu Styles

The table of contents is shown in a pane that is automatically hidden if the screen size is not big enough to show it. When it is hidden it can be opened using a hamburger icon.

Animation Speed

The speed of animations can be changed with this variable.

    --toc-transition: 0.3s;

Scrollbar Width

TOC menu uses a custom narrow scrollbar (works only in Chrome). You can set its width with this variable.

    --scrollbar-width: 4px;
    --scrollbar-color: var(--col-prim);
    --scrollbar-hover: var(--col-prim-dark);

Font Sizes

The sizes of the header and TOC items can be changed with following variables.

    --toc-header-font-size: 1rem;
    --toc-font-size: 0.9rem;
    --toc-border-width: 2px;

Hamburger Radius

The border radius of the hamburger icon can be changed with this variable. To keep a consistent look we use the same radius as for the navbar buttons by default.

    --toc-sideicon-radius: @nav-button-radius;

Colors and Transparency

The colors of the TOC menu can be changed with variables below. @toc-fadeout controls the transparancy of the backgound color.

    --toc-bg-color: var(--col-prim);
    --toc-text-color: var(--col-sec);
    --toc-link-color: var(--toc-text-color);
    --toc-ruler-color: var(--col-prim-dark);
    --toc-hover-color: var(--col-sec-light);
    --toc-hover-bg: var(--col-prim-light);
    --toc-scrollbar-color: var(--col-prim-dark);
    --toc-scrollbar-hover: var(--col-sec-light);

Page Menu Styles

Page menu provides navigation menu inside the current page. It is dynamically generated by collecting all the header tags in the page.

Animation Speed

As for other page elements the animation speed is controlled by transition variable.

    --pm-transition: 0.3s;

Fonts

Page menu uses the @sans-font. You can change the font sizes with these variables.

    --pm-header-font-size: 1rem;
    --pm-font-size: 0.9rem;

Colors

The colors are defined with the following variables.

    --pm-bg-color: var(--cnt-bg-color);
    --pm-text-color: var(--col-sec);  
    --pm-ruler-color: var(--col-prim-dark);
    --pm-hover-color: var(--col-sec-dark);

Content Area Styles

The content area is where your actual documentation lives. A lot of styling are applied to it, but to keep things simple, only the most important ones are controlled by variables. If you wish to have completely different styling for the content area, I recommend writing a new template for that.

Fonts

Content area uses the @serif-font in main text, and @sans-font in headers. You can change these or font sizes with the variables below.

    --cnt-font: var(--serif-font);
    --cnt-header-font: var(--sans-font);
    --cnt-font-size: 1.1rem;
    --cnt-mono-font-size: 0.9rem;

Width and Margins

Content area width should be adjusted according to the font size so that horizontal space is enough. *

    --cnt-width: 80ch;
    --cnt-margin: 1rem;

Colors

The @cnt-color is the "black" text color used and @cnt-bg-color is the background color.

    --cnt-color: var(--col-sec-dark);
    --cnt-header-color: var(--col-sec);
    --cnt-bg-color: var(--col-prim-light);
    --cnt-pre-color: var(--col-prim);
    --cnt-border-color: var(--col-prim);
    --cnt-dark-border: var(--col-prim-dark);
    --cnt-link-color: blue;
    --cnt-link-visited-color: darkblue;
    --cnt-link-hover-color: dodgerblue;
    --cnt-link-active-color: orange;

Footer Colors and Font

Footer is a simple block of text that contains copyright message. You can change its color and font with these variables.

    --ftr-color: var(--col-prim);
    --ftr-dark-color: var(--col-prim-dark);
    --ftr-bg-color: var(--col-sec);
    --ftr-font-family: var(--sans-font);
    --ftr-font-size: 1rem;
    --ftr-padding: 1rem;
    --ftr-border-color: var(--col-sec-light);
    --ftr-text-hover: var(--col-prim-light);

Tooltip Colors

Tooltips are popping up in code blocks and menus. You can change their colors with following variables.

    --tooltip-color: var(--col-sec-text);
    --tooltip-bg-color: var(--col-sec);
    --tooltip-border-color: var(--col-sec-light);

Landing Page Styles

A landing page has completely different layout than normal page. You can change the style of few elements in the landing page.

Background

The background of the landing page can either be a picture or solid color.

    --lnd-background: var(--col-prim);
    --lnd-background-attachment: fixed;
    --lnd-background-repeat: no-repeat;

Title Text

The title font size and color can be changed with following variables.

    --lnd-title-color: var(--col-prim-text);
    --lnd-title-font-size: 12vw;
    --lnd-title-font-weight: bold;

Info Boxes

The boxes that contain information about the project can by styled with these variables.

    --lnd-info-background-color: @color-white;
    --lnd-info-text-color: @color-text;
}

Narrow Scrollbars

Add class narrow-scrollbars to elements which should have narrow scrollbar thumbs.

.narrow-scrollbars::-webkit-scrollbar {
    background: transparent;
}
.narrow-scrollbars::-webkit-scrollbar:horizontal {
    height: var(--scrollbar-width);
}
.narrow-scrollbars::-webkit-scrollbar:vertical {
    width: var(--scrollbar-width);
}
.narrow-scrollbars::-webkit-scrollbar-thumb {
    border-radius: calc(var(--scrollbar-width) / 2);
}
.narrow-scrollbars::-webkit-scrollbar-thumb:hover {
    background-color: var(--scrollbar-hover) !important;
}
.narrow-scrollbars:hover::-webkit-scrollbar-thumb {
    background-color: var(--scrollbar-color);
}