# Docs Portal

Docs Portal hosts branded documentation for your own product, with search, theming, an interactive API reference and custom domains. It handles pages, navigation and automatic SSL for you. The documentation you are reading right now is served by it.

## What you get

- **Authoring**: Markdown pages with full heading/code/table support, organised into sections you order freely; draft → publish per page or per portal.
- **API reference**: import an OpenAPI spec *or a Postman collection* and get a generated, always-in-sync reference with saved examples, response tabs and a live "Try it" playground (requests run through a masked proxy, so visitors never see your upstream secrets).
- **Reader experience**: instant full-text search (⌘K), table-of-contents scroll-spy, light/dark theming with your brand colours and logo, mobile navigation.
- **Hosting**: live immediately at `<your-slug>.docs.newinstance.cloud`; add your own domain with a CNAME and the platform provisions Let's Encrypt SSL automatically.

## Concepts

| Concept | What it is |
|---------|-----------|
| **Portal** | One documentation site (slug, theme, navigation, domains). An org can run several. |
| **Pages & sections** | Your content tree; you control all structure and ordering. |
| **API reference source** | The imported OpenAPI/Postman document; re-import to update, REPLACE or MERGE. |
| **Visibility** | PUBLIC portals are indexed; private ones are hidden from robots and links. |

Everything is managed in the merchant dashboard; this page is the setup guide.


## Create and configure your portal

1. Log in to the merchant dashboard
2. Navigate to **Dashboard → Org → Docs Portal** (`/dashboard/org/[orgId]/docs-portal`)
3. Click **Create Portal** and give it a name and a slug (e.g. `my-product-docs`)
4. Configure:
   - **Theme:** colours, logo, fonts; the dark theme uses pure black + brand accent
   - **Navigation:** create sections and order pages (you control all structure)
   - **SEO:** meta title, description, sitemap


## Create and publish content

- Click **New Page** in the sidebar to add a documentation page
- Write in Markdown with full heading/code/table support
- Heading anchors are auto-generated for TOC scroll-spy
- Use the **in-page search** (⌘K palette) for instant full-text search across published pages
- Publish individual pages or the entire portal at once


## API Reference integration

Import an **OpenAPI 3.x spec** to generate an interactive API reference:
1. Go to the portal's **API References** tab
2. Import a `.yaml` or `.json` OpenAPI file
3. The reference is published as a separate page with a no-code request playground (masked proxy)
4. Update the spec at any time; changes publish immediately


## Custom domain

Configure a custom domain in the **Domains** tab:

1. Add your domain (e.g. `docs.yourcompany.com`)
2. Add a CNAME DNS record: `docs.yourcompany.com → <generated-subdomain>.newinstance.cloud`
3. NewInstance provisions a Let's Encrypt SSL certificate automatically (HTTPS enforced)
4. Once DNS propagates and status shows **ACTIVE**, your portal is live on the custom domain

> [!NOTE]
> DNS propagation can take up to 48 hours. You can preview the portal at the generated subdomain (`<slug>.newinstance.cloud`) immediately after creation.


## Permission scopes for Docs Portal API keys

| Scope code | Description |
|------------|-------------|
| `full-access` | All docs-portal permissions |
| `content-management` | Create, edit, delete pages and sections |
| `publish-management` | Publish/unpublish portals and pages |
| `api-reference-management` | Import and manage OpenAPI specs |
| `portal-configuration` | Branding, theming, layout, SEO |
| `domain-management` | Manage custom domains and DNS |