Documentation Page 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).

Nextra currently supports only the /pages directory structure. While StartupBolt pages are placed in the App Router, Nextra pages are placed in the Pages Router. This separation allows us to keep the main app and documentation distinct.

Place your documentation pages inside /pages/docs.
Use /app for the main app pages.

Create your first MDX page in pages/docs/index.mdx.

_meta.json

Nextra uses _meta.json files to configure the site and page structure. The title and order of a page or folder shown in the sidebar should be configured in the _meta.json file as key-value pairs.

Pages and Folders

Configuring Pages

Use _meta.json to set page titles and order in the sidebar.
Example structure:
```
{
  "index": "My Homepage",
  "contact": "Contact Us",
  "about": "About Us"
}
```
- In the example above, create three files named index.mdx, contact.mdx, and about.mdx, and write the corresponding documentation in those files.
- The order of the pages in the sidebar menu will be as defined in the _meta.json object.
- The titles of the pages in the sidebar menu will be as defined in the _meta.json object (e.g., My Homepage, Contact Us, About Us).

Markdown

The MDX files accept content written in Markdown, a lightweight markup language widely used for documentation and blogs. Learn more about Markdown from this Wikipedia article (opens in a new tab). ChatGPT, Claude, and other LLMs can also generate Markdown for you.

Configuring Folders

Folders can be configured similarly to pages.

Example structure:
```
{
  "index": "My Homepage",
  "contact": "Contact Us",
  "software": "Best Software",
  "about": "About Us"
}
```
- In the example above, software can be a folder. You can have a _meta.json file inside the software folder with meta information for pages within it.
- Example _meta.json inside software folder:
```
{
  "word": "Microsoft Word",
  "photoshop": "Adobe Photoshop"
}
```
- Create word.mdx and photoshop.mdx inside the software folder and write the corresponding documentation in those files.
- To add an index page for a folder, create an MDX file with the same name as the folder in the same directory. For example, to add an index page for the software folder, create a software.mdx file in the same directory as the software folder.

External Links

You can add external links to the sidebar by adding an item with href in _meta.json. Use "newWindow": true to open links in a new tab.

{
  "github_link": {
    "title": "Nextra",
    "href": "https://github.com/shuding/nextra",
    "newWindow": true
  }
}

Sidebar Separators

You can use a "placeholder" item with "type": "separator" to create a separator line between items in the sidebar.

Example:

{
  "index": "My Homepage",
  "---": {
    "type": "separator"
  },
  "contact": "Contact Us"
}

Navigation Bar Customization

Menu Items

By defining a top-level page or folder as "type": "page", it will be shown as a menu item on the navigation bar instead of the sidebar. This feature allows you to have multiple "sub-docs" and special pages or links such as "Contact Us" that are always visible.

Example configuration:

{
  "index": {
    "title": "Home",
    "type": "page"
  },
  "frameworks": {
    "title": "Frameworks",
    "type": "page"
  }
}

Default StartupBolt Configuration

In the pages directory, we have a default /pages/_meta.json file. This configuration creates a hidden menu item that enables the docs folder as the root folder for our documentation. Additionally, there are two menu items named home and login that link to the homepage and login page of the main project.

Do not change this configuration unless necessary. Here is what the default _meta.json looks like:

{
  "docs": {
    "title": "Docs",
    "display": "hidden",
    "type": "page",
    "theme": {
      "breadcrumb": true,
      "footer": true,
      "sidebar": true,
      "toc": true,
      "pagination": true
    }
  },
  "home": {
    "title": "Home",
    "type": "page",
    "href": "/",
    "newWindow": false
  },
  "login": {
    "title": "Login",
    "type": "page",
    "href": "/login",
    "newWindow": false
  }
}

You can create documentation files such as MDX files and _meta.json files inside the /pages/docs folder. You can finally view the documentation website at https://yourdomain.com/docs.

Best Practices

Regularly update your _meta.json files to reflect site structure changes.
Use clear, descriptive titles for pages and folders.
Organize content logically to improve user navigation.
Utilize external links and separators to enhance sidebar functionality.

By following these guidelines, you can create a well-structured, easily navigable Nextra-based documentation site that provides an excellent user experience for your visitors.

Crisp Integration Theme Configuration