Styles and CSS Classes

MyST has basic support for styling your content with CSS. This page describes some common ways to do so.

Add a Style Sheet (CSS) to your website¶

The default MyST website themes support bundling a custom style-sheet. This can be used to introduce custom CSS styling to your website. To include a custom CSS file as part of your website build, you can define the style (file) option, e.g.

myst.yml

1
2
3
site:
  options:
    style: ./my-style.css

For example, the style-sheet could contain styling for em elements nested below a particular text-gradient class:

style.css

.text-gradient em {
  background: -webkit-linear-gradient(#eee, #333);
  -webkit-background-clip: text;
  -webkit-text-fill-color: transparent;
}

Add CSS Classes to content and blocks¶

The intended way to apply custom styling to your MyST website is to use CSS classes to connect your content to the style sheet. There are several ways to do this.

Use content blocks¶

Content blocks allow you to attach arbitrary metadata to chunks of content. You can attach one or more CSS classes by defining a class attribute for a block. For example the following:

Use `div` and `span` elements¶

You can attach classes directly to div and span elements.

{div} and {span} are analogous to their HTML counterparts. Unlike their directive/role, the HTML elements can also be given style options, e.g.

Add CSS classes to directives¶

Many directives and content blocks have a :class: option that can be used to add arbitrary CSS classes. For example, below we add a CSS class to an admonition directive to snap it to the right:

Add CSS classes in-line to role and directive titles¶

You can add CSS classes directly to roles and divs using Inline Options syntax.

Built-in CSS Classes¶

The HTML themes come with a grid system of CSS classes, which can be used out-of-the-box to position content.

Provide Light and Dark Mode images¶

You can use Tailwind CSS classes to make certain content show up in light vs. dark mode. By default items are shown in light mode, so here is how you can control light vs. dark behavior:

To only show in dark mode, attach the CSS class hidden dark:block. This hides the element by default, and sets its display to block when the Dark theme is active.

To only show in light mode, attach the CSS class dark:hidden. The element will be hidden when Dark mode is active.

For example, here is how you can make two elements swap visibility during light and dark mode. This is useful if you have two versions of an image that are meant for light and dark modes, but the same approach could be applied to any element you can attach CSS classes to.

Websites

Search Engines & Social