Last updated

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:

  1. Add the files to your project's @theme folder.

  2. Load the assets in the @theme/styles.css file using the url() function.

  3. 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:

@theme/styles.css
@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:

@theme/components/ContactUsCard.tsx
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:

About.page.tsx
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

 
Next page