Vowel

Design

Vowel styles your website with a theme, and your own CSS can change anything the theme does.

Themes

Choose a theme in settings.md:

theme: Default
Theme Stylesheets
Reset A CSS reset
Typography Reset, plus typographic defaults
Default Reset, typography, colours and layout. The theme when none is set.

The name isn't case-sensitive. A theme applies to its folder and every folder beneath it, so a section can use a different theme from the rest of the site.

Colours

The Default theme generates a colour scheme from two colours:

theme:
  name: Default
  colors: ["#5119ff", "#00edc6"]

The scheme has eight roles, primary, secondary, tertiary, accent, success, info, warning and danger, each with ten shades from --color-<role>-01 (darkest) to --color-<role>-10 (lightest). Use them in your own CSS:

blockquote {
  border-color: var(--color-secondary-05);
}

Without colors, the scheme is built from Vowel's own pair. If the colours you give can't make a scheme, the build logs the reason and uses Vowel's pair instead.

Four more settings shape the scheme. Each is a number from 0 to 1:

theme:
  name: Default
  colors: ["#5119ff", "#00edc6"]
  darkest-shade: 0.2
  contrast: 0.5
Key Default Meaning
darkest-shade 0.3 The lightness of shade 01
lightest-shade 0.99 The lightness of shade 10
min-saturation 0.2 The least saturation any shade may have
contrast 0 Above 0, the shades in between crowd toward the darkest and lightest

A value that isn't a number from 0 to 1 is logged and ignored, and so are a darkest shade and a lightest shade the wrong way round.

Typography

The Typography and Default themes compute every heading size, weight and letter spacing from a few numbers. Set any of them under theme:

theme:
  name: Default
  heading-size: 2.5
  h1-weight: 900
Key Default Meaning CSS variable
heading-size 1.5 How much larger h1 is than body text, as a multiple of it: 1.5 makes h1 2.5 times the size --fontsize-scale
heading-size-decay 3 Higher makes lower-level headings smaller --fontsize-decay
h1-weight 800 Font weight of h1 --fontweight-h1
h6-weight 600 Font weight of h6 --fontweight-h6
weight-decay 2 How the weight steps from h1 down to h6 --fontweight-decay
h1-letter-spacing -0.01 Letter spacing of h1, in ch --letterspacing-h1
h6-letter-spacing 0 Letter spacing of h6, in ch --letterspacing-h6
letter-spacing-decay 2 How the spacing steps from h1 down to h6 --letterspacing-decay

A stylesheet can set the CSS variables instead, with a unit where the setting has one (-0.02ch). Set them on :root, where the heading sizes are worked out once for the whole page: setting one on another element, such as article, changes nothing. To change headings for one page or folder, set them on :root in a stylesheet linked only there, with styles.

:root {
  --fontsize-scale: 2;
}

Fonts

Vowel ships no fonts; pages use the system font stack. To use your own, add the font files to your project (see Files), declare them, and name them in these variables:

@font-face {
  font-family: "Mona Sans";
  src: url("/mona-sans.ttf");
}

:root {
  --fontfamily-sans-brand: "Mona Sans";
}

The variables are --fontfamily-sans-brand, --fontfamily-serif-brand and --fontfamily-monospace-brand. Each falls back to the system font stack.

CSS

A file named styles.css is linked from every page in its folder and the folders beneath it. A styles.css at the root styles the whole site; blog/styles.css styles only the blog.

Any other .css file is published, but only linked where you ask for it, with styles. In a folder's settings.md it applies to the pages in that folder and beneath it; in a page's frontmatter, to that page:

styles:
  - ./gallery.css
  - /print.css

Paths work like every other path: /print.css is from the root of the site, and ./gallery.css is beside the file that names it. A path to a file that isn't in your project is skipped, with a warning.

Every page's <body> has a class for each folder it's in and one for the page itself, so a rule can target a whole section or a single page. A page's card in a listing carries the same classes.

The homepage is page_home. A post at /blog/travel/hello-world has three classes: folder_blog, folder_blog_travel and page_blog_travel_hello-world. A secret folder's class uses its name without the salt.

.folder_blog h1 {
  font-style: italic;
}

article.page_about {
  display: none;
}

The header's menu, the sidebar, the breadcrumb trail and the table of contents are each a <nav>, and each is left out of the page when it would have fewer than two links. The homepage has no breadcrumb trail, and a page with one heading has no table of contents. In the menu and the sidebar, the link to the page you're on has aria-current=page, and the links to the folders above it have aria-current=true. Each <li> has the page class of the page it links to, such as page_blog_hello-world, and each <ul> that lists a folder has that folder's class, such as folder_blog.

A page's slogan, date, description and image are direct children of <main>, marked with itemprop ([itemprop="slogan"], [itemprop="date"]), and so are the date, description and image in each card. Every property from the frontmatter also carries its key as a class: fm_date, fm_description, fm_client.

Theme stylesheets are wrapped in cascade layers, and yours aren't, so your rules win over the theme's regardless of specificity. There is no need for !important.

Your CSS is prefixed for older browsers and minified when it is built. Its link carries a hash of its content, so browsers fetch it again only when it changes.