{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"theme-static-assets","__idx":0},"children":["Theme static assets"]},{"$$mdtype":"Tag","name":"ConfigOptionRequirements","attributes":{"products":["Redoc","Revel","Reef","Realm"],"plans":["Pro","Enterprise","Enterprise+"]},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-you-begin","__idx":1},"children":["Before you begin"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Make sure you have the following:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@theme"]}," folder in your project"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@redocly/realm"]}," installed in the project"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["familiarity with CSS and React"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"use-theme-assets-in-css","__idx":2},"children":["Use theme assets in CSS"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Using static assets, such as images, fonts, or other stylesheets, can enhance your theme's visual appeal and user experience."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To use theme assets in CSS:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add the files to your project's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@theme"]}," folder."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Load the assets in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@theme/styles.css"]}," file using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["url()"]}," function."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the asset by overriding a CSS variable or adding it to a styling rule."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example uses static assets to change a theme's font and define a class with a full-width image:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"css","data-title":"@theme/styles.css","header":{"title":"@theme/styles.css","controls":{"copy":{}}},"source":"@import url('other-custom-styles.css');\n\n@font-face {\n font-family: 'CustomFont', sans-serif;\n src: url('../fonts/CustomFont.woff2') format('woff2'),\n url('../fonts/CustomFont.woff') format('woff');\n font-weight: normal;\n font-style: normal;\n}\n\n.hero {\n background-image: url('../images/hero-image.jpg');\n background-size: cover; \n background-position: center; \n height: 400px;\n}\n\n:root {\n --font-family-base: 'CustomFont', sans-serif;\n}\n","lang":"css"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"use-theme-assets-in-react","__idx":3},"children":["Use theme assets in React"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can import static assets into your React files (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".tsx"]},") and use them in components."," ","This is a great way to add custom icons or images."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example shows a React component using an imported static file:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","data-title":"@theme/components/ContactUsCard.tsx","header":{"title":"@theme/components/ContactUsCard.tsx","controls":{"copy":{}}},"source":"import React from 'react';\nimport phoneIcon from '../images/phoneIcon.png';\n\nexport function ContactUsCard({ phoneNumber }){\n return (\n
\n \n
Contact us
\n
Call during business hours: {phoneNumber}
\n
\n )\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The phone icon will render everywhere the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ContactUsCard"]}," component is used."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example shows a React page that renders the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ContactUsCard"]}," and an image:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","data-title":"About.page.tsx","header":{"title":"About.page.tsx","controls":{"copy":{}}},"source":"import React from 'react';\nimport { ContactUsCard } from './components/ContactUsCard';\nimport teamPhoto from './images/TeamPhoto-2024.png';\n\nexport function AboutPage() {\n return (\n <>\n
About our company
\n
Check out our awesome photo!
\n \n \n \n );\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"use-assets-from-authors","__idx":4},"children":["Use assets from authors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you build ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/learn/markdoc"},"children":["Markdoc tags"]},", you can create components that use static assets provided by the author, such as images."," ","This can unlock powerful capabilities for authors, such as the following examples:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Modify the styling or behavior of an image, for example, adding a caption, border, or lightbox behavior."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Pass an image to render as part of a more complex component, such as a product card with a screenshot, price, and description."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"static-assets-as-children","__idx":5},"children":["Static assets as children"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If a Markdown image is wrapped in a Markdoc tag, then the tag's component receives the image as a node on the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["children"]}," prop."," ","This behavior is useful for adding styling or wrapper elements around the entire image."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example shows a tag wrapping an image to add a border:"]},{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":false,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here's ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["markdown"]}," content with a screenshot:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"Image","attributes":{"src":"../images/cat-with-glasses.jpg","alt":"Picture of cat with glasses"},"children":[]}]}],"rawContent":"Here's _markdown_ content with a screenshot:\n\n{% image-border %}\n \n{% /image-border %}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"static-assets-as-attributes","__idx":6},"children":["Static assets as attributes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If an author passes an asset's filepath as an ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://redocly.com/docs/learn-markdoc/write-with-markdoc#attributes-control-tags"},"children":["attribute"]}," on the Markdoc tag, the component receives the string as a prop."," ","This behavior allows for more advanced styling or when the image is part of a more complex element."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Allow authors to pass a ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["relative path"]}," to a static asset by setting the attribute's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["resolver"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["link"]}," in the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/customization/build-markdoc-tags"},"children":["Markdoc tag schema"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example shows a schema that accepts an image attribute from authors:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ts","data-title":"tag-schema.ts","header":{"title":"tag-schema.ts","controls":{"copy":{}}},"source":"import type { MarkdocTagSchema } from '@redocly/theme/markdoc/tags/types';\n\nconst schema: MarkdocTagSchema = {\n render: 'YourComponent',\n attributes: {\n image: {\n type: String,\n resolver: 'link',\n },\n },\n};\n\nexport const customTag = {\n schema,\n tagName: 'custom-tag',\n};\n","lang":"ts"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Setting the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["resolver"]}," property in the tag schema allows authors to provide a ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["relative path"]}," to a static asset as an attribute."," ","The underlying component receives a ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["resolved path"]}," to the file."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example shows a Markdoc tag that accepts an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["image"]}," attribute:"]},{"$$mdtype":"Tag","name":"MarkdocExample","attributes":{"renderDemo":false,"language":"markdoc","demoContent":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here's ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["markdown"]}," content with a screenshot:"]}],"rawContent":"---\nseo:\n title: Awesome guide\n---\n\nHere's _markdown_ content with a screenshot:\n\n{% ui-card-tag title=\"See our products\" image=\"../images/product-img.png\" /%}\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources","__idx":7},"children":["Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/branding"},"children":["Style your site"]}]}," - Learn to customize your documentation appearance using CSS variables, custom stylesheets, and theme-specific styling"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/customization/build-markdoc-tags"},"children":["Build Markdoc tags"]}]}," - Create custom authoring tools and interactive components that can reference your theme static assets"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/customization"},"children":["Extend with code"]}]}," - Discover customizable components and customization options for your project"]}]}]},"frontmatter":{"products":["Redoc","Revel","Reef","Realm"],"plans":["Pro","Enterprise","Enterprise+"]},"tagList":["configOptionRequirements","markdoc-example"],"title":"Theme static assets","lastModified":"2026-10-01T23:00:57.000Z"}