Documentation Template

This repository is a reusable documentation template built on the current docs shell from the Tonconsole docs codebase.

It keeps the existing visual design, layout, and overall UX, but moves shell-level concerns into centralized configuration so future projects can adopt the template without rewriting theme files for every new site.

For repository-native content authoring guidance, see AUTHORING.md. For starter-content migration guidance, see ADOPTION.md. For upstream maintenance workflow, see UPSTREAM.md.

What This Template Covers

• Static documentation site built with Next.js, Nextra, and MDX
• Centralized shell configuration in site.config.ts
• Template-owned shell branding assets in public/brand/
• File-based navigation and content in pages/** with _meta.json
• Reusable MDX primitives for callouts, code tabs, spoilers, and OpenAPI-backed sections
• Static export workflow for GitHub Pages or other static hosting targets

Stack

• next@13
• nextra@2
• nextra-theme-docs
• React 18
• MDX pages via the pages/ router
• Static export to dist/

Getting Started

Prerequisites

Use a current Node.js LTS release. Node 18+ is the safest baseline for this repository.

Install and run locally

npm ci
cp .env.example .env.local
npm run dev

The local dev server starts on the default Next.js port.

Create a production export

npm run build

This builds the site and exports static files to dist/.

Repository Structure

This is the practical layout you will work with most often:

site.config.ts          Central shell configuration
theme.config.tsx        Nextra theme wiring for logo, metadata, footer, TOC CTA, edit links
next.config.js          Next.js + Nextra config, including GitHub Pages deploy behavior
.env.example            Environment-facing overrides for OpenAPI and GitHub Pages

pages/                  Documentation pages and navigation structure
pages/_meta.json        Top-level sidebar/navigation labels
pages/**/_meta.json     Nested section labels, ordering, and hidden items
pages/**/*.mdx          Page content

examples/               Reusable MDX code snippets imported into pages
components/             Custom MDX/UI primitives used by docs pages
utils/                  Helpers for links and OpenAPI data loading
.github/workflows/      GitHub Actions deployment workflow

public/brand/           Template-owned shell brand assets
public/assets/          Content assets used by docs pages
public/robots.txt       Static robots file

Shell Configuration

The main template entry point is site.config.ts.

Use this file for shell-level settings only:

• Site identity: site name, title suffix, base URL, locale
• SEO metadata: description, keywords, Open Graph, Twitter metadata
• Community links: header chat link, support/contact links, TOC CTA
• Repository links: project URL, edit link base, issues/feedback link
• Footer links and labels
• Analytics and verification values
• GitHub Pages deploy defaults
• OpenAPI source URLs
• Shell brand asset paths

Current top-level config sections:

• site
• seo
• verification
• community
• repository
• footer
• analytics
• deploy.githubPages
• openApi
• brand

Keep product copy, tutorials, API explanations, and section content out of site.config.ts. That content belongs in MDX pages under pages/.

Optional integrations such as analytics and verification can be disabled by setting their values to null in site.config.ts.

Branding Assets

Shell-owned branding files live in public/brand/:

• favicon.ico
• icon.svg
• apple-touch-icon.png
• icon-192.png
• icon-512.png
• manifest.json
• og-image.png

To rebrand the template:

1. Replace the files in public/brand/ with your own assets.
2. Update the brand section in site.config.ts only if file names or paths change.
3. Update shell text and metadata in site.config.ts.

Do not move page-specific screenshots, videos, diagrams, or other doc content into public/brand/. Those assets should stay content-local in public/assets/ or another content-oriented location.

Navigation and Pages

This repository uses the Next.js pages/ router and Nextra's file-based docs model.

How navigation works

• Every .mdx file under pages/ becomes a route.
• Each section can define a _meta.json file to control labels and ordering.
• Nested folders become nested docs sections.
• Hidden routes are declared in _meta.json with "display": "hidden".

Example:

• pages/tonapi/rest-api/accounts.mdx becomes /tonapi/rest-api/accounts
• pages/tonapi/rest-api/_meta.json controls the sidebar labels and order for that section

Adding a page

1. Create a new .mdx file in the correct folder under pages/.
2. Add the page key to the nearest _meta.json.
3. Give the page an # H1 heading.
4. Import any MDX components you need.

Editing navigation labels

Update the relevant _meta.json file:

• Top-level sections: pages/_meta.json
• Nested sections: pages/**/_meta.json

Authoring Content

Most day-to-day authoring should happen in MDX files under pages/.

Use MDX for:

• Page body copy
• Guides and tutorials
• Product/API explanations
• Tables, lists, and headings
• Embedded reusable components
• Code examples imported from examples/

Use site.config.ts for:

• Site-wide shell settings
• Metadata and social links
• Footer and repository links
• Brand asset paths
• Deploy/OpenAPI defaults

This distinction is intentional: shell behavior is centralized, but documentation content remains normal MDX.

Reusable Docs Primitives

The template already includes a small set of authoring primitives in components/.

Callouts

Pages use Nextra's built-in Callout component:

import { Callout } from 'nextra-theme-docs';

<Callout type="info" emoji="ℹ️">
  Important note.
</Callout>

The current docs use info and warning variants, but you can use any variant supported by nextra-theme-docs.

Example tabs

Use ExampleTabs and ExampleTab to switch between multiple examples on the same page:

import { ExampleTabs, ExampleTab } from '@/components';

<ExampleTabs>
  <ExampleTab label="TypeScript">Content here</ExampleTab>
  <ExampleTab label="Python">Content here</ExampleTab>
</ExampleTabs>

These are typically paired with snippet files from examples/.

Spoilers

Use Spoiler for collapsible supporting content:

import { Spoiler } from '@/components';

<Spoiler title="Glossary">Hidden content here</Spoiler>

External links

Use ExternalLink when you want a consistent external-link wrapper:

import { ExternalLink } from '@/components';

<ExternalLink href="https://example.com">External resource</ExternalLink>

OpenAPI-backed sections

The repo includes a pattern for REST/API pages backed by an OpenAPI schema:

• loadStatic in utils/schemas.ts fetches the configured schema at build time
• SchemaLoader renders operations for a given tag
• SwaggerLink links the page heading to the corresponding Swagger UI section

Typical pattern:

import { SwaggerLink, SchemaLoader } from '@/components';
import { SWAGGER_TAGS } from '@/constants';
import { loadStatic } from '@/utils';

export const getStaticProps = loadStatic;

# Accounts<SwaggerLink tag={SWAGGER_TAGS.ACCOUNTS} />

<SchemaLoader tag={SWAGGER_TAGS.ACCOUNTS} />

If you do not need OpenAPI-backed pages for your project, you can leave those sections unused and keep the rest of the template as a standard MDX docs site.

Reusable Snippets

The examples/ directory contains MDX snippet files that can be imported into multiple pages.

Use it for:

• Shared code samples
• Multi-language snippets
• Repeated instructional blocks

This keeps large example blocks out of page files and avoids duplication across related docs.

Local Environment

Start from .env.example:

cp .env.example .env.local

Current environment-facing settings:

• NEXT_PUBLIC_TONAPI_LANDING_PAGE_URL
• NEXT_PUBLIC_TONAPI_OPENAPI_JSON_URL
• NEXT_PUBLIC_TONAPI_OPENAPI_YAML_URL
• Optional NEXT_PUBLIC_GITHUB_PAGES_* overrides

These values currently support the existing OpenAPI-backed docs and GitHub Pages deployment path.

Deployment

Static export

The main build command exports a static site:

npm run build

Output goes to dist/.

This makes the template suitable for static hosting platforms that can serve prebuilt files.

GitHub Pages

The repository includes a GitHub Actions workflow for GitHub Pages at .github/workflows/deploy-pages.yml.

The workflow:

• enables GHPAGES=1
• derives NEXT_PUBLIC_GITHUB_PAGES_* from the current repository name
• uses / automatically for <owner>.github.io repositories and /<repo> for project pages
• runs npm ci and npm run build
• uploads dist/ as the Pages artifact and adds .nojekyll so exported Next.js assets under _next/ are served correctly

To use it:

1. Enable GitHub Pages in the repository settings and choose GitHub Actions as the source.
2. Push to master or main, or run the workflow manually from the Actions tab.

The repository also keeps a manual GitHub Pages build path:

npm run gh-deploy

That command enables GHPAGES=1, builds the site, exports it, and publishes dist/ directly.

GitHub Pages-related defaults are aligned between site.config.ts, next.config.js, and .env.example:

• NEXT_PUBLIC_GITHUB_PAGES_REPO_NAME
• NEXT_PUBLIC_GITHUB_PAGES_BASE_PATH
• NEXT_PUBLIC_GITHUB_PAGES_ASSET_PREFIX
• NEXT_PUBLIC_GITHUB_PAGES_TRAILING_SLASH

Override these only if your published path differs from the default repository-based path.

Practical Customization Checklist

For a new project, the usual setup order is:

1. Update site.config.ts with your site name, metadata, links, and repository values.
2. Replace shell assets in public/brand/.
3. Update top-level navigation in pages/_meta.json.
4. Replace or reorganize the starter MDX content under pages/.
5. Add or remove sections by editing pages/** and _meta.json.
6. Update .env.local if you use different OpenAPI or deploy settings.
7. Run npm run build before publishing.

Notes for Template Maintainers

• Keep shell concerns centralized in site.config.ts.
• Keep page content in MDX.
• Keep shell brand files in public/brand/.
• Keep content assets separate from shell assets.
• Avoid changing framework, router, or docs engine unless there is a strong compatibility reason.
• Prefer thin changes that preserve upstream mergeability.