Copy page

Configuration

Portal

The portal section is your developer portal: the docs, the API page, the home page and the console where people sign in, pick a plan and get API keys.

apitogo.config.json
{
  "portal": {
    "name": "Books API",
    "docs": { "content": ["apitogo/portal/pages/**/*.{md,mdx}"] },
    "landing": "apitogo/portal/landing/LandingPage.tsx",
    "footer": "apitogo/portal/footer/Footer.tsx",
    "logo": "apitogo/portal/public/logo.svg",
    "theme": "apitogo/portal/theme.json",
    "search": "pagefind",
    "requireAuth": false
  }
}

"portal": {} is enough: every setting has a default. apitogo add portal writes the section and its starter files.

Settings

Setting	Default	What it does
name	project.name	The name in the header and the page titles
docs	apitogo/portal/pages/**/*.{md,mdx}	Where the docs pages are, or an external docs site (below)
landing	none	A React file shown at /, the home page
footer	none	A React file shown under every page except the console's
logo	none (the header shows name)	The header logo (below)
header	none	Your own links in the header's top menu (below)
theme	apitogo/portal/theme.json	Colors and fonts (Colors & theme)
console	{ "enabled": true }	The sign-in, plans, keys and usage pages, when identity or plans is on
search	pagefind	pagefind, inkeep or none
requireAuth	false	Only signed-in people may see the portal (below)
dir	apitogo/portal	The portal's folder, if you keep it somewhere else
enabled	true	false keeps the section but leaves the portal out of deploys

docs

The docs pages are the Markdown and React files in apitogo/portal/pages/. Name other places with content (globs, relative to the config):

Code
"docs": { "content": ["docs/**/*.{md,mdx}", "guides/**/*.md"] }

React pages (.tsx) in the same folders are found too. The sidebar is built from the files: a folder becomes a section, and order in a page's frontmatter sorts it. See Writing and Custom pages for React pages.

If your docs live on another site, link it instead. The portal then has no docs pages of its own:

Code
"docs": { "provider": "external", "url": "https://docs.example.com" }

Home page and footer

landing and footer each name a React file in your folder. apitogo add portal writes both, built from the sections of @lukoweb/apitogo-module-landing, and you change them freely. Remove the setting to have none. See Landing page and Footer.

When there is a home page, / shows it, and an index page of the docs opens at /index.

Header links

header.links adds your own links to the top menu, after Documentation and API Reference (the plans service adds Pricing itself). A link is either a page of its own or an address:

Code
"header": {
  "links": [
    { "label": "Partners", "page": "apitogo/portal/header-pages/partners.tsx" },
    { "label": "Status", "to": "https://status.example.com" }
  ]
}

• page: a React page (.tsx, its default export is the page) or a Markdown page (.md, .mdx), served at /<file name> (partners.tsx is /partners). It is a page of its own: the docs sidebar does not list it. It needs hosted docs, and a portal with requireAuth keeps it behind sign-in like the docs.
• to: a path on the portal (/blog) or an https:// address, which opens in a new tab.

The CLI makes the file and the link in one step:

Code
apitogo config --page-slug partners --page-title Partners --page-header

The page is a React component in apitogo/portal/header-pages/partners.tsx; add --page-format mdx for a Markdown page instead. Its title (export const title) is the link's label. --page-update --page-title with --page-header renames the page and its link and leaves your code as it is. Links show in the order of the list; edit it to reorder them.

apitogo check refuses a page that is missing, is not .tsx, .md or .mdx, or would take an address the portal already uses (/pricing, /account, /api, /login, /signup or a docs page).

logo

An image in the portal's public/ folder, or an https:// address:

Code
"logo": "apitogo/portal/public/logo.svg"

One image per color scheme, with the text read out by screen readers. dark and alt are optional; without dark the light image is shown in both:

Code
"logo": {
  "light": "apitogo/portal/public/logo.svg",
  "dark": "apitogo/portal/public/logo-dark.svg",
  "alt": "Books API"
}

apitogo check refuses a file that does not exist or is not in public/.

Who may see the portal

By default everyone may read the docs and the API page. requireAuth asks people to sign in first (it needs identity):

Code
"requireAuth": true

Keep some pages public:

Code
"requireAuth": { "exclude": ["/introduction", "/pricing"] }

Console

The console pages appear on their own when the project has identity (sign-in) or plans (pricing, API keys, usage). Turn them off with:

Code
"console": { "enabled": false }