> ## Documentation Index
> Fetch the complete documentation index at: https://labs.prompthon.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Website Publishing

<div className="not-prose my-4 rounded-md border border-gray-200 bg-gray-50 p-2 text-sm dark:border-gray-800 dark:bg-gray-900/40">
  <div className="mb-2 px-1 text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-400">Need help?</div>

  <div className="flex flex-wrap gap-2">
    <a className="inline-flex items-center gap-2 rounded-md border border-gray-200 bg-white px-3 py-1.5 font-medium text-gray-700 no-underline shadow-sm hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:bg-gray-950/60 dark:text-gray-200 dark:hover:bg-gray-900" href="https://discord.gg/sDE2HhGTg4" target="_blank" rel="noreferrer">
      <Icon icon="discord" iconType="brands" size={14} />

      <span>Ask in Discord</span>
    </a>

    <a className="inline-flex items-center gap-2 rounded-md border border-gray-200 bg-white px-3 py-1.5 font-medium text-gray-700 no-underline shadow-sm hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:bg-gray-950/60 dark:text-gray-200 dark:hover:bg-gray-900" href="https://github.com/Prompthon-IO/agent-systems-handbook/issues/new/choose" target="_blank" rel="noreferrer">
      <Icon icon="github" iconType="brands" size={14} />

      <span>Open a GitHub issue</span>
    </a>

    <a className="inline-flex items-center gap-2 rounded-md border border-gray-200 bg-white px-3 py-1.5 font-medium text-gray-700 no-underline shadow-sm hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:bg-gray-950/60 dark:text-gray-200 dark:hover:bg-gray-900" href="https://github.com/Prompthon-IO/agent-systems-handbook/blob/main/SUPPORT.md" target="_blank" rel="noreferrer">
      <Icon icon="life-ring" size={14} />

      <span>Support guide</span>
    </a>
  </div>
</div>

This repository is prepared for a Mintlify documentation site. Published handbook pages are MDX-first, while GitHub-only operating files such as `README.md`, `CONTRIBUTING.md`, `SECURITY.md`, and `SUPPORT.md` remain Markdown.

## Local Preview

Mintlify requires Node.js 20.17.0 or newer for the current CLI.

Run a local preview from the repository root:

```bash theme={null}
npx mint dev
```

Run quality checks before publishing:

```bash theme={null}
npx mint validate
npx mint broken-links
```

## Deployment

The primary Mintlify deployment should be connected through the Mintlify GitHub app. Mintlify reads `docs.json` and publishes the documentation site when changes are pushed.

The production documentation site is published at `https://labs.prompthon.io`.

If the handbook should appear under a Vercel-owned domain, configure Vercel as a reverse proxy after the Mintlify subdomain exists:

```json theme={null}
{
  "rewrites": [
    {
      "source": "/docs",
      "destination": "https://YOUR-MINTLIFY-SUBDOMAIN.mintlify.dev/docs"
    },
    {
      "source": "/docs/:match*",
      "destination": "https://YOUR-MINTLIFY-SUBDOMAIN.mintlify.dev/docs/:match*"
    }
  ]
}
```

Do not add that active `vercel.json` until the real Mintlify subdomain is known.

## Analytics and Search Console

Mintlify analytics should be used for documentation-native usage signals such as most-read pages, internal searches, search result clicks, feedback, and assistant activity. Access those reports in the Mintlify dashboard or from an authenticated CLI session with `npx mint analytics`.

GA4 is configured through the Mintlify `docs.json` integration with measurement ID `G-K26DVPPVLY`. Use GA4 for external reporting, referral/source analysis, and click-path exploration.

Google Search Console should use a URL-prefix property for `https://labs.prompthon.io/`. The verification token is committed in `docs.json` as the `google-site-verification` meta tag. After deployment, verify the property and submit `https://labs.prompthon.io/sitemap.xml`.

## Compatibility Policy

Mintlify is the student-facing reading layer. It should publish curated MDX pages, not every raw project artifact.

| Artifact type             | Repository policy                                                                                   | Website policy                                                            |
| ------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| MDX pages                 | Commit and maintain as source documentation                                                         | Publish curated pages through `docs.json`                                 |
| GitHub operating Markdown | Keep only for GitHub-native surfaces such as README, contributing, support, security, and templates | Link from the site only when needed                                       |
| Python source             | Commit as starter/source code                                                                       | Link from guide pages or convert selected files into tutorial pages later |
| Jupyter notebooks         | Keep out of the handbook repo unless deliberately promoted                                          | Convert selected notebooks to MDX before publishing as lessons            |
| HTML/CSS/JS examples      | Commit when they are source or demos                                                                | Link to GitHub or host curated demos separately                           |
| Built HTML/output files   | Avoid publishing by default                                                                         | Host separately only when intentionally promoted as a demo                |
| Raw references            | Keep outside the published site and ignored by this repo by default                                 | Keep out of the public docs site with `.mintignore`                       |

The raw `references/` archive is intentionally ignored by the repository-level `.gitignore`. Promote selected material into MDX pages when it is ready for the student-facing site.