Custom pages

If you want to include pages in your documentation that have greater flexibility than MDX pages, it is possible to include custom pages of your own.

These pages are typically built using standard React markup and can borrow from a set of prebuilt components that APIToGo already has such as buttons, links and headers.

Start by creating the page you want to add.

React pages in a project made by apitogo create

Put a .tsx file next to your Markdown pages, in apitogo/portal/pages/ (or any folder in portal.docs.content). Its default export is the page, and export const title is its label in the sidebar. The page's address follows its path, like a Markdown page: guides/quickstart.tsx is /guides/quickstart, under a Guides section.

apitogo/portal/pages/guides/quickstart.tsx
import { useState } from "react";
import { Button, Heading, Typography } from "@lukoweb/apitogo/components";

export const title = "Quickstart";

export default function QuickstartPage() {
  const [count, setCount] = useState(0);
  return (
    <Typography>
      <Heading level={1}>{title}</Heading>
      <Button onClick={() => setCount(count + 1)}>Clicked {count} times</Button>
    </Typography>
  );
}

• A file or folder whose name starts with _ is not a page, so keep shared components there, for example apitogo/portal/pages/_components/Chart.tsx. Test and story files are not pages either.
• When a Markdown page and a React page have the same address, the Markdown page wins.
• Nothing in apitogo.config.json changes: the sidebar is built from the files.

CLI scaffold

apitogo config creates a starter React page at apitogo/portal/pages/<slug>.tsx. Choose page in the wizard loop, or pass --page-slug and --page-title. Add --page-format mdx for a Markdown page instead.

Predefined UI components (Callout, Card, Button, Heading, and more) are documented under /docs/components.

Setup a custom page (version 1 projects)

Each custom page is a page component of its own and lives in a src directory at the root of your project. Let's create the <MyCustomPage /> component as an example.

From the root of your project run this command:

Code
touch src/MyCustomPage.tsx

You can now open /src/MyCustomPage.tsx in the editor of your choice. It will be empty.

Copy and paste this code to implement the page:

Code
import { Button, Head, Link } from "@lukoweb/apitogo/components";

export const MyCustomPage = () => {
  return (
    <section className="">
      <Head>
        <title>My Custom Page</title>
      </Head>
      <div>
        <p>Welcome to MyCustomPage</p>
      </div>
    </section>
  );
};

Configuration

In the APIToGo Configuration you will need to do the following:

Config that embeds JSX

If you embed React components in config (for example custom pages), use a JSX-capable config module and import your page component from there.

Import Your Module

Import the <MyCustomPage /> component that you created.

Code
import { MyCustomPage } from "./src/MyCustomPage";

Add a navigation entry

Add a custom-page item to the navigation configuration. Each page you want to add to the site must be its own object.

The path key can be set to whatever you like. This will appear as part of the URL in the address bar of the browser.

The element key references the name of the custom page component that you want to load.

Code
{
  // ...
  navigation: [
    {
      type: "custom-page",
      path: "/a-custom-page",
      element: <MyCustomPage />,
    },
  ]
  // ...
}

This configuration will allow APIToGo to load the contents of the <MyCustomPage /> component when a user clicks on a link that points to /a-custom-page.

Troubleshooting

Updating Your tsconfig.json

Your include property in tsconfig.json should automatically be updated to reflect the new custom pages, but in case it isn't, it should look like this:

Code
{
  ...
  "include": ["src", "src/MyCustomPage.tsx"]
}