Theme static assets
Static assets play an important role in your documentation theme. This guide shows you how to use static assets in a theme when you add the files directly or they come from a Markdoc tag.
Before you begin
Make sure you have the following before you begin:
- Check for
@theme
folder. Add one if missing @redocly/realm
installed in project- Familiarity with CSS and React
Use theme assets in CSS
Using static assets, such as images, fonts, or other stylesheets, can enhance your theme's visual appeal and user experience.
To use theme assets in CSS:
Add the files to your project's
@theme
folder.Load the assets in the
@theme/styles.css
file using theurl()
function.Use the asset by overriding a CSS variable or adding it to a styling rule.
The following example uses static assets to change a theme's font and define a class with a full-width image:
@import url('other-custom-styles.css'); @font-face { font-family: 'CustomFont', sans-serif; src: url('../fonts/CustomFont.woff2') format('woff2'), url('../fonts/CustomFont.woff') format('woff'); font-weight: normal; font-style: normal; } .hero { background-image: url('../images/hero-image.jpg'); background-size: cover; background-position: center; height: 400px; } :root { --font-family-base: 'CustomFont', sans-serif; }
Use theme assets in React
You can import static assets into your React files (.tsx
) and use them in components. This is a great way to add custom icons or images.
The following example shows a React component using an imported static file:
import React from 'react'; import phoneIcon from '../images/phoneIcon.png'; export function ContactUsCard({ phoneNumber }){ return ( <div className="contact-card"> <img src={phoneIcon} alt="Phone icon" /> <h3>Contact us</h3> <p>Call during business hours: {phoneNumber}</p> </div> ) }
The phone icon will render everywhere the ContactUsCard
component is used.
The following example shows a React page that renders the ContactUsCard
and an image:
import React from 'react'; import { ContactUsCard } from './components/ContactUsCard'; import teamPhoto from './images/TeamPhoto-2024.png'; export function AboutPage() { return ( <> <h1>About our company</h1> <p>Check out our awesome photo!</p> <img src={teamPhoto} alt="Team photo from 2024" width="250" /> <ContactUsCard phoneNumber="+1 (123) 456-7890" /> </p> ); }
Use assets from authors
You can build Markdoc tags that allow authors to use their static assets with components. This can unlock powerful features for writing, such as the following examples:
- Allow authors to modify, format, or style an image, such as adding a caption or lightbox.
- Authors provide an image to render a pre-formatted element, such as a product card with a screenshot, price, and description.
Static assets as children
If a Markdown image is wrapped in a Markdoc tag, then the tag's component gets the image as a node on the children
prop. This behavior is useful for adding styling or wrapper elements around the entire image.
The following example shows a tag wrapping an image to add a border:
Here's _markdown_ content with a screenshot: {% image-border %} ![Picture of cat with glasses](../images/cat-with-glasses.jpg) {% /image-border %}
Static assets as attributes
If the author passes the asset's filepath as a Markdoc tag attribute, the tag's component receives the string as a prop. This behavior is useful for more advanced styling or when the image is part of another element.
This approach requires the author to pass a resolved path to the static asset. A relative path won't work.
The following example shows an image as a tag attribute:
--- image: ../images/cat-with-glasses.jpg --- Here's _markdown_ content with a screenshot: {% ui-card-tag title="See our products" file=$frontmatter.image /%}
Resources
- Add custom styling to your documentation using CSS.
- Explore the default theme settings to see how projects are configured.