Last updated

Customize styles

You can apply custom styling to change the appearance of your project. For example, things like typography, colors, and spacing.

The core theme is built using CSS variables. You can override those variables to add custom styling while benefiting from the theme's existing structure.

Before you begin

Make sure you have the following before you begin:

  • A new Realm, Reef, or Revel project updated to the latest version

Create a theme stylesheet

You need a @theme/styles.css file to customize the styling of your project.

  1. Add a folder named @theme to the root of your project.
  2. Create a styles.css file inside the @theme folder.

Your project structure should look similar to this:

your-awesome-project/
├──@theme/
│   └──styles.css
├──other-content.md
├──redocly.yaml
└──sidebars.yaml

Add CSS selectors

Inside the @theme/styles.css file, add two selectors::root and :root.dark. These selectors will keep styling changes scoped to light and dark mode, respectively.

@theme/styles.css
:root {
   /* light mode styling */
}

:root.dark {
   /* dark mode styling */
}

For a more detailed look at color modes, please review the Customize Color Modes guide.

Override CSS variables

Add custom styling to your project by overriding CSS variables.

  1. Run your Redocly project in development mode.

  2. Copy the following snippet into your @theme/styles.css file and save:

    @theme/styles.css
    :root {
--navbar-bg-color: #E7BE9E;
--h1-text-color: blue;
}

:root.dark {
   --navbar-bg-color: #BDC3EE;
   --h1-text-color: red;
}

  3. The styling changes should be visible. Toggle between color modes to check the difference.

Generally speaking, these are the steps you'll follow when styling your project:

Examples

Use the examples in this section as starter themes to quickly add styling to your

Have a request for a styling example? Please use the feedback form at the bottom of the page and tell us.

Example theme - "Full corporate"

The "Full corporate" styling uses a business font, has teal accents, and is very deliberate about spacing.

@theme/styles.css
:root {
  --teal-primary-1: #62D7A6;
  --teal-primary-2: #9BB0A5;
  --dark-green-primary-1: #384B42;
  --dark-green-primary-2: #005A23;
  --font-family-base: Times New Roman;

  --md-container-max-width: 860px;
  --md-container-padding-vertical: 18px;
  --md-container-padding-horizontal: 5px;
  --md-paragraph-margin-vertical: 6px;
  --h1-margin-top: 12px;
  --h2-margin-top: 8px;

  --menu-item-bg-color-active: var(--teal-primary-1);
  --toc-item-border-color-active: var(--teal-primary-1);
  --breadcrumbs-text-color-active: var(--teal-primary-1);

  --navbar-bg-color: var(--teal-primary-2);
  
  --search-trigger-color: var(--dark-green-primary-1);

  --link-color-primary: var(--teal-primary-1);
  --link-color-visited: var(--dark-green-primary-2);

}

:root.dark {
  --teal-primary-dark: #CDFBE4;
  --text-color-dark: #22232B;

  --navbar-text-color: #364133;

  --menu-item-color-active: var(--text-color-dark);
  --menu-item-text-color: var(--teal-primary-dark);
}

The following screenshots show the styling rules applied:

Screenshot of Redocly project with the full corporate styling example applied in light mode.

Example theme - "Trendy startup"

The styling for the "Trendy startup" example combines shocking pink and teeny tiny font sizes. Note the increased specificity used to style .menu-item-type-separator in dark mode. This approach can be used for styling elements that may not have a CSS variable defined yet.

@theme/styles.css
:root {
  --font-size-base: 12px;
  --font-size-sm: 10px;
  --font-size-lg: 14px;
  --font-size-xl: 20px;

  --pink-primary-1: #F15483;
  --pink-primary-2: #FAAEBD;
  --pink-primary-3: #FFE3ED;
  --purple-primary: #905B9F;

  --h1-text-color: var(--pink-primary-1);
  --heading-text-color: var(--pink-primary-2);
  
  --search-trigger-bg-color: var(--pink-primary-3);
  --sidebar-bg-color: var(--pink-primary-3);

  --toc-item-text-color-active: var(--purple-primary);
  --breadcrumbs-text-color-active: var(--purple-primary);
}

:root.dark {
  --purple-primary-dark: #BD9BF4;

  --menu-item-text-color: #22232B;
  
  --toc-item-text-color-active: var(--purple-primary-dark);
  --breadcrumbs-text-color-active: var(--purple-primary-dark);
}

:root.dark .menu-item-type-separator {
  --menu-item-text-color: #22232B;
}

The following screenshots show the styling rules applied:

Screenshot of Redocly project with the trendy startup styling example applied in light mode.

Example theme - Personal wellness

The "Personal wellness" example uses styling that emphasizes pastel colors and lots of space between elements. Note that the only spacing change in the following example is for --spacing-unit, but space between elements is increased throughout the theme.

@theme/styles.css
:root {
  --pastel-green: #d2e7d6;
  --pastel-green-secondary: #00A84E;
  --pastel-blue: #94B5E3;
  --pastel-purple: #B9C3FC;
  --pastel-active: #FFDF82;
  --text-color-dark-green: #3B4A3F;

  --navbar-bg-color: var(--pastel-green);  
  --navbar-item-bg-color-hover: var(--pastel-active);
  --navbar-item-bg-color-active: var(--pastel-active);
  --navbar-border-color: var(--pastel-purple);
  --search-trigger-border-color: var(--pastel-purple);
  --search-input-placeholder-color: var(--pastel-purple);

  --sidebar-bg-color: var(--pastel-blue);
  --menu-item-bg-color-hover: var(--pastel-active);
  --menu-item-bg-color-active: var(--pastel-active);

  --toc-bg-color: var(--pastel-blue);
  --toc-border-color: var(--pastel-purple);
  
  --text-color-secondary: var(--text-color-dark-green);
  --link-color-primary: var(--pastel-green-secondary);
  --link-color-visited: var(--pastel-purple);

  --spacing-unit: 6px;
}

:root.dark {
  --pastel-green-dark: #728576;
  --pastel-green-secondary: #00A84E;
  --pastel-blue-dark: #2F4858;
  --pastel-purple: #B9C3FC;
  --pastel-active-dark: #386C5F;
  --text-color-light-grey: #ECFEEF;

  --navbar-bg-color: var(--pastel-green-dark);
  --navbar-item-text-color-active: var(--pastel-green-dark);
  --navbar-item-text-color-hover: var(--pastel-green-dark);
  --navbar-item-bg-color-hover: var(--pastel-green);
  --navbar-item-bg-color-active: var(--pastel-green);

  --sidebar-bg-color: var(--pastel-blue-dark);
  --menu-item-color-active: var(--pastel-green-dark);
  --menu-item-color-hover: var(--pastel-green-dark);
  --menu-item-bg-color-active: var(--pastel-green);
  --menu-item-bg-color-hover: var(--pastel-green);
  --toc-bg-color: var(--pastel-blue-dark);

  --text-color-secondary: var(--text-color-light-grey);
}

The following screenshots show the styling rules applied:

Screenshot of Redocly project with the personal wellness styling example applied in light mode.

  • Customize color modes - Learn to style your project for color modes that your users switch between (light and dark)

Resources

 
Next page