Theme APIComing Soon

Learn how to use Theme API

While theme settings provide a quick way to customize your documentation, using the Theme API gives you more flexibility and programmable control.

This approach allows you to build upon the existing design while adding your own customizations, all while maintaining the core functionality of the default theme.

All built-in themes like poetry or opener are based on the default theme and use the Theme API.

Getting Started

To use Theme API you need to create .docs/theme/index.ts file:

import {BaseTheme} from "xyd-js/themes"

export default class MyTheme extends BaseTheme {
    constructor() {
        super();

        // you can access theme API here
        // this.theme # do stuff what u want with `theme`
    }
}

for example:

this.theme.Update({
    markdown: {
        syntaxHighlight: "github-dark"
    }
})

Style Customization

Create an index.css file in your .docs/theme directory and import that to add custom styles:

import {BaseTheme} from "xyd-js/themes"

import './index.css';

export default class MyTheme extends BaseTheme {
...
}

You can add as many style file as you want. Also names of your imported styles are your own.

Overriding ComponentsComing Soon

  export default {
      components: {
          Badge: MyCustomBadge
      }
  }

  function MyCustomBadge({size, children}) {
      return <div class={`badge size-${size}`}>
          {children}
      </div>
  }

Custom ComponentsComing Soon

Here's an example of how to add a custom component to your theme:

  export default {
      customComponents: {
          CustomBanner
      }
  }

  function CustomBanner({kind, children}) {
      return <div class={`banner banner-${kind}`}>
          {children}
      </div>
  }

You can then use this component in your markdown:

:::custom-banner{kind="info"}
    Welcome to our documentation!
:::

or you can use a MDX syntax too:

<CustomBanner kind="info">
    Welcome to our documentation!
</CustomBanner>

If you not set name in customComponents function, it will convert PascalCase to kebab-case for markdown syntax.

SurfacesComing Soon

If you want to add your custom components into specific place inside docs, you can use surface:


  export default {
      customComponents: {
          CustomBanner: {
              component: CustomBanner,
+
              surface: "page.footer"
          }
      }
  }

  function CustomBanner({kind, children}) {
      return <div class={`banner banner-${kind}`}>
          {children}
      </div>
  }

if you still want to have this component available inside your content:


{
    surface: "page.footer"
+
    content: true
}

Plugins Custom Theme