Customize theme styles

To customize a Hugo site theme, use a local file to override the theme setting.

The specific file depends on the change you want to make.

Here, we use a simple example to show how this works.

This site uses (Docsy) as its base theme, which sets paragraph margins as follows:

p {
    margin-top: 0;
    margin-bottom: 1em;
}

This appears to be an attempt to make text placement more predictable, which makes sense given the number of different browsers, devices, operating systems, versions, add-ons, and other variations that can impact display dimensions.

Unfortunately, this change does not affect all HTML elements, which means it leads to visual glitches in certain circumstances. (One key example is the use of indented paragraphs in list contexts, such as bulleted (<ul>) or numbered lists (<ol>).

In such cases, a more effective solution is:

p {
   margin-top: 1rem;
   margin-bottom: 0.3rem;
}

This approach assumes paragraphs and other text elements exist in a larger narrative and defines a natural amount of both leading and trailing whitespace for readability.

To override the default theme style:

1. In your project source, open assets/scss/_styles_project.scss.

   If you do not currently have an assets/scss folder or a _styles_project.scss file, create them.

2. Add the following CSS block:

   /*
   Override project style rules here. For details, see
   https://www.docsy.dev/docs/adding-content/repository-links/#disabling-links
   */
   
   p {
      margin-top: 1rem;
      margin-bottom: 0.3rem;
   }
   

3. Save and preview your changes.

Once built, your overrides follow traditional CSS rules for precedence (mozilla.org).

Background details

Strictly speaking, the initial style rule isn’t a Docsy problem, nor is it a bug.

It’s a side-effect consequence of a deliberate design decision by Bootstrap, which Docsy depends on.

Bootstrap is a web interface design framework that simplifies web design across multiple browsers, devices, operating systems, and versions. They use a “Reboot script” to reset basic design settings to create a level playing field.

Unfortunately, this design doesn’t work as well with complex formatting, such as nested paragraphs inside lists.

The Bootstrap design assumes that text should appear at the top of all bounding boxes. It moves leading and trailing whitespace below the text. As a result, noticeable (and unexpected gaps) appear when include nested paragraph list items with other HTML elements.

Per the original W3C spec, paragraphs are meant to have leading whitespace and the defaults by most browser vendors reflect this.

Hopefully, future iterations of the Bootstrap reboot script will more extensively test the side effects of various design changes. Until that happens, you can override the paragraph CSS rule in order to create a more consistent and visually pleasing experience.

Vital statistics

• 10 Sep 2024: Initial version for this site.