Documentation Theme Configuration

Overview

We use Nextra to set up the documentation pages for your StartupBolt website. For more detailed Nextra configuration, refer to the official documentation (opens in a new tab).

The theme.config.jsx file, located in the root directory, is used to configure the Nextra Docs theme. This configuration file allows you to tailor various aspects of your documentation, including the logo, SEO settings, sidebar structure, and more.

Key Configuration Sections

Logo

The logo for your business, displayed in the top left of the documentation site, is set here. It combines an image and text.

Import the logo image:
```
import logo from "@/app/icon.png";
```
Ensure that icon.png exists. For more information on setting up the icon, check the documentation in docs/seo/files/icons.mdx.
Display the app name beside the logo: Set APP.name in /settings.js located in the root directory.

Customize the logo's size and style if required:

logo: (
  <>
    <div style={{ display: 'flex', alignItems: 'center', gap: '0.5rem' }}>
      <Image
        src={logo}
        alt={`${settings.APP.name} logo`}
        width={40}
        height={40}
        style={{ width: 'auto', height: '2rem' }}
      />
      <span style={{ fontWeight: 800, fontSize: '1.2rem' }}>{settings.APP.name}</span>
    </div>
  </>
),

Use logoLink to set the logo's link URL:
- Set logoLink to ${settings.APP.url}/docs to link to the documentation.
- Set logoLink to true for the homepage.
- Set logoLink to false to remove the logo link.

SEO Configuration

You can configure SEO-related settings via the useNextSeoProps hook.

Title and Description Metadata

Include title and description metadata at the beginning of each .mdx documentation file.

---
title: "Write your title for the documentation file here."
description: "Write a good description for your documentation file here."
---

Use the useConfig hook to get the frontMatter object. Front matter is a section at the beginning of a Markdown or MDX file that contains metadata about the document.

useNextSeoProps generates title and description metadata from the page front matter or default settings from /settings.js.

useNextSeoProps() {
  const { frontMatter } = useConfig();
  return {
    title: frontMatter.title || settings.APP.name,
    description: frontMatter.description || settings.APP.description,
    // ... (Other configurations)
  };
}

Canonical URL
- Canonical URL metadata is automatically set using useRouter. No changes are needed.
- Import useRouter from 'next/router' as Nextra uses the Pages Router.
- Use the asPath property of the useRouter object to derive the canonical path for SEO.
```
useNextSeoProps() {
  const { asPath } = useRouter();
  return {
    canonical: `${settings.APP.url}${asPath}`,
  };
}
```
Other Metadata
- Open Graph and Twitter card metadata are also configured by useNextSeoProps.
Settings.js
- Ensure the following values are correctly entered in /settings.js located in the root directory:
  - APP.name
  - APP.description
  - APP.url
  - APP.twitterProfile

Head Tags

Add custom meta tags to the <head> of each page:

Set the viewport for responsiveness.
Define the theme color.

Link the favicon.

head: (
  <>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="theme-color" content={settings.COLORS.backgroundColor || '#ffffff'} />
    <link rel="icon" href="/favicon.ico" />
  </>
),

To customize the theme-color, navigate to the settings.js file located at the root of the project (/settings.js). Adjust the COLORS.backgroundColor property as needed. Setting the theme-color is beneficial for defining the color of the browser's UI elements, such as the address bar and splash screen on mobile devices. Note that this feature is not supported by all browsers. The default color is set to #fff (white).

Dark Mode

Set darkMode to true to enable the dark mode toggle.

Set forcedTheme to 'dark' or 'light'. Currently, it is set to undefined.

darkMode: true,
nextThemes: {
  forcedTheme: undefined,
},

Search Functionality

Set the placeholder text for the search input:

search: {
  placeholder: 'Search documentation...'
},

Sidebar Configuration

Defines the behavior and appearance of the documentation sidebar:

Default Menu Collapse Level
- defaultMenuCollapseLevel sets the default menu collapse level.
- By default, the sidebar menu is collapsed at level 1, meaning every folder is collapsed by default.
- You can change it by setting sidebar.defaultMenuCollapseLevel to a different number. For example, when set to 2, every top-level folder will be expanded by default. If set to a higher number, deeper folders are also expanded by default.
```
sidebar: {
  defaultMenuCollapseLevel: 1,
},
```

Title Component

titleComponent is a custom render for sidebar titles. It can be used to set an icon or emoji next to a sidebar title.

sidebar: {
  titleComponent({ title, type }) {
    let content;
    switch (title) {
      case 'Introduction':
        content = <>🌟 {title}</>;
        break;
      // ... (Switch statement for different section emojis)
    }
    return content;
  }
},

Footer Customization

Set up the footer content. Currently, it displays copyright information with the current year and app name. You can customize it as desired.

footer: {
  text: `© ${new Date().getFullYear()} ${settings.APP.name}. All rights reserved.`
},

Additional Configurations

Disable certain Nextra default features. This is useful only if you are maintaining the documentation in GitHub.

Remove the edit link component.

Disable feedback functionality.

editLink: {
  component: null
},
feedback: {
  content: null
}

Usage Notes

Ensure that the settings.js file is properly configured with your application's details.
Adjust the SEO settings to optimize your documentation's search engine visibility.

By leveraging this configuration file, you can create a highly customized and visually appealing documentation site that aligns with your brand and provides an excellent user experience for your readers.

Page Configuration Favicon & App Icons