Adding New Documentation Pages

Components

Adding new pages to your knowledge base is straightforward and collaborative, enabling you to expand your resources and customize the content to fit your specific needs.

Introduction

This knowledge base is designed to evolve with your team and project. As the design system grows, regular updates ensure all team members have access to consistent guidelines, enhancing efficiency. By continuously adding content and examples for components and sections, the knowledge base stays relevant and valuable.

There are two main types of pages: content-first and component-documentation. Content-first pages, like this one, provide text and guidelines, while component-documentation pages are interactive, showcasing React components, source code examples, and their supported props. Together, these pages enrich user understanding and foster a deeper grasp of the system.

Note: All pages are created using MDX.

Adding a new content page

Creating new pages is a simple process, though there’s significant backend logic involved. To streamline it, documentation is managed with Next.js’s built-in App Router, leveraging file-system-based routing. For components and examples, a registry file is used to ensure proper management and build of each component. This setup simplifies the overall workflow while maintaining organization behind the scenes.

Create the page

content
└── docs
    └── page-name.mdx

Provide meta data for the page

Once you've created a page, you'll need to add a markdown header that acts as metadata and provides Next.js with the necessary information to render the page. For basic content-based pages, this header must include at least a title and description to meet TypeScript requirements. These values will be used for the page's <title> and <meta name="description"> tags.

---
title: Documentation Introduction
description: The documentation provides a comprehensive guide to understanding, utilizing, and maximizing the potential of the design system, ensuring a seamless development process and consistent implementation of design elements.
links:
  doc: https://example.com
---

Note: By default there are two external links options that are rendered as badges. These are api and doc, and can be customized in app/(app)/docs/[[...slug]]/page.tsx

Link the page

The config/docs.ts file handles the navigation setup for the documentation. It contains two arrays: mainNav and sidebarNav, each providing type safety to ensure proper configuration. When working with the sidebarNav, adding new elements is straightforward—just follow the existing structure to maintain consistency and accuracy.

sidebarNav: [
    {
      title: "",
      items: [
        {
          title: "Introduction",
          href: "/docs/design-system-introduction",
          items: [],
        }
      ],
    },
    {
      title: "Design Resources",
      items: [
        {
          title: "Analytics",
          href: "/docs/analytics",
          items: [],
        },
        {
          title: "Figma",
          href: "/docs/design/figma",
          items: [],
        },
        {
          title: "Theming",
          href: "/docs/design/theming",
          items: [],
        },
        {
          title: "Typography",
          href: "/docs/design/typography",
          items: [],
        },
      ],
    },

Adding a new component page

There are several ways to build new components within the design system. One option is to extend existing components, adding new functionality while keeping the core structure intact. Another method is to create variations of existing components to meet specific needs while ensuring consistency across the system. For unique requirements, entirely new components can be built from scratch. This flexibility allows the design system to adapt and evolve, supporting a wide range of project needs.

Create the component page

Like with a content page, creating component pages is a breeze. The first step is to create the actual page that will contain your content:

content
└── docs
    └── components
      └── component-name.mdx

Create the component

The next step is to create the actual component that you wish to document.

registry
└── default
    └── ui
      └── component-name.tsx

Create an interactive component example

Once you've created the component and added it to your ui folder, you can use it with your documentation as you see fit. However, we must now create an additional example if we wish to provide users with an interactive example:

registry
└── default
    └── example
      └── component-name.tsx

Register the example

Now that the component has been created and an example exists within the example folder, it is time to add it to the registry. In the /registry/example.ts file, you will find a list of all components along with their respective examples and dependencies. This registry file ensures that all examples are properly bundled with their dependencies. Following the syntax outlined in the file, add your new component to the very bottom:

{
    name: "aspect-ratio-demo",
    type: "components:example",
    registryDependencies: ["aspect-ratio"],
    files: ["example/aspect-ratio-demo.tsx"],
},

Note: Pay attention to the name, as it will be needed in the next step. It's recommended to follow the component-name-demo naming convention to avoid duplicates. Since the registry file manages components, it's advisable to stop the development server before adding the component, then restart it after creation. Alternatively, you can add the component first and restart the server afterward, but doing it this way reduces the chance of caching errors.

Utilize the component

Now that your component has been created, registered, and documented, all that is left is to add the link to your navigation:

<ComponentPreview name="name-determined-in-last-step" />

Link the page

Now that your component has been created, registered and documented, all that is left is to add the link to your navigation:

The config/docs.ts file serves as a configuration file for the navigation of the site. Inside, you will find two arrays, mainNav, and sidebarNav. Each provides TypeSafety to ensure they are correctly configured. Focusing on the sideNav, adding new elements is as simple as following the existing format:

sidebarNav: [
    {
      title: "",
      items: [
        {
          title: "Introduction",
          href: "/docs/design-system-introduction",
          items: [],
        }
      ],
    },
    {
      title: "Design Resources",
      items: [
        {
          title: "Analytics",
          href: "/docs/analytics",
          items: [],
        },
        {
          title: "Figma",
          href: "/docs/design/figma",
          items: [],
        },
        {
          title: "Theming",
          href: "/docs/theming",
          items: [],
        },
        {
          title: "Typography",
          href: "/docs/components/typography",
          items: [],
        },
      ],
    },

Component Design Patterns Next.js Starter Application