Skip to main content

Custom Functionality

This site has a number of custom features that are not part of Docusaurus out of the box. This page explains what they are and how to use them.

Custom Components​

Home Page Components​

The home page is defined in src/pages/index.tsx, with its layout and card styles in src/pages/index.module.scss. The curated links, topic cards, and contribution links are maintained there. The older Homepage* components in src/components/ are not used by the current home page.

Shared colours, typography, navigation, and light/dark styling are defined in src/scss/_community-theme.scss, loaded by src/scss/custom.scss. The repository README also covers the logo and social share image.

Documented Components​

A number of components are described in the "Knowledge" section of the site, these components will all be present in src/components/ to enable them to be used in the MDX files to demonstrate their usage. They will not be detailed here and you should look at the Knowledge section of the site to see how they are used and find their source code.

DocusaurusButton​

The DocusaurusButton component is a custom button component that is used throughout the site. It is a styled button that can be used to link to the documentation on the Docusaurus website. It is defined in src/components/DocusaurusButton/index.tsx.

Swizzled Components​

Admonition​

We run a custom version of the Admonition component that is part of Docusaurus. This component is used to display information boxes in the documentation. The custom version of this component is defined in src/theme/Admonition/. You'll find in-depth documentation in the Knowledge section of the site on how to "decode" our customised Admonitions or create your own.

DocItem/Footer​

The wrapper in src/theme/DocItem/Footer/index.tsx keeps the standard Docusaurus document footer and adds a contributor list. Its helper components fetch contributors from the document's GitHub commit history and include any additionalContributors from frontmatter. This is inspired by the unleash team who added contributors to their documentation.

The component in src/theme/Logo/index.tsx renders the community mark and two-tone wordmark in the navbar and mobile menu. The logo assets and their light/dark variants are configured in docusaurus.config.ts.

Custom Plugins​

Plugin Directory​

The plugin directory is powered by @homotechsual/docusaurus-plugin-showcase. Each plugin is defined as a YAML file in data/plugins/. See Adding a Plugin for how to submit a new entry.

Custom Frontmatter​

To support our contributor display on docs pages we sometimes use a custom frontmatter field called additionalContributors. This field is used to display additional contributors to a document. It is an array of objects with the following structure:

type AdditionalContributor = {
    login: string;
    html_url: string;
    avatar_url: string;
};

An example of how this is used in a document is:

---
title: Custom Functionality
description: Learn about the custom functionality you'll find on this site.
additionalContributors:
  - login: github-bot
    html_url: https://github.com/github-bot
    avatar_url: https://avatars.githubusercontent.com/u/6031226?v=4
---