# HyperDocs
> Generate documentation from your codebase, keep it updated as your product changes, and help users find answers through a built-in help center powered by your documentation.
---
# Home
Source: https://www.hyperdocs.io/docs/get-started/home
# Welcome to Hyperdocs' Documentation
Explore Our Documentation, tutorials, and changelog in one place.
---
# What is Hyperdocs
Source: https://www.hyperdocs.io/docs/get-started/what-is-hyperdocs
# What is Hyperdocs
Hyperdocs is an agent-ready documentation platform for SaaS teams
It helps you create, maintain, publish, and improve documentation without managing everything manually. Instead of treating documentation like a static website, Hyperdocs gives you a system that helps your docs stay aligned with your product as it changes.
With Hyperdocs, you can create product documentation, help center content, API documentation, and changelogs in one place. You can publish public documentation for customers, organize internal knowledge, and manage documentation with more structure and control.
Hyperdocs also includes built-in product intelligence for modern documentation workflows:
- Docs Agent helps draft new documentation and update existing content
- GitHub Sync helps keep documentation aligned with product changes
- Answer Agent helps users find answers directly from your docs
- Analytics and feedback help you understand what users are searching for, what content is missing, and where docs need improvement
Hyperdocs is also built for modern AI discovery. Features like AI SEO tags, `llms.txt`, markdown output, and automatic sitemaps help make your documentation easier for search engines, answer engines, and AI agents to understand.
## What you can use Hyperdocs for
Teams use Hyperdocs to:
- create product documentation
- build help centers
- publish API documentation
- maintain changelogs
- keep docs updated as products evolve
- improve self-serve support
- identify documentation gaps through analytics and feedback
- prepare documentation for AI agents and answer engines
## How Hyperdocs works
Hyperdocs combines documentation creation, maintenance, answering, and improvement into one workflow.
A typical flow looks like this:
1. You create or import your documentation into Hyperdocs
2. GitHub Sync helps detect product changes that may affect docs
3. Docs Agent helps draft new pages or update outdated content
4. Answer Agent helps users get answers from your documentation
5. Analytics and feedback show what users need and what your docs still miss
## Why teams use Hyperdocs
Most documentation gets outdated because product changes move faster than manual documentation workflows.
Hyperdocs is built to reduce that gap. It helps teams spend less time chasing documentation debt and more time publishing useful, accurate content.
Instead of using separate tools for docs, search, feedback, AI discoverability, and maintenance, Hyperdocs brings those workflows together in one platform.
## In short
Hyperdocs helps SaaS teams build documentation that is easier to create, easier to maintain, easier to search, and better prepared for both users and AI systems.
> **CHECK:** Docs Agent writes. GitHub Sync maintains. Answer Agent answers.
Together, Hyperdocs helps your documentation operate with your product.
---
# Create Your Account
Source: https://www.hyperdocs.io/docs/get-started/create-your-account
# Create Your Account
To get started with Hyperdocs, open the login page and choose how you want to sign in. There are two options: **Continue with Google** for one-click access, or your email address for a code-based sign-in. After signing in you complete a short setup flow, then land on your admin dashboard.
## Sign In with Google
Click **Continue with Google** on the login page. A Google authorization pop-up opens — approve it and you are signed in immediately. No password is created or stored.
## Sign In with Email
Enter your email address and click the send-code button. Hyperdocs emails you a one-time password (OTP). Enter the code on the verification screen to complete sign-in. Use the **Resend** option if the code does not arrive.
## Sign-In Options
| Method | Best For | What You Need |
| --- | --- | --- |
| Email | Users who prefer a standalone account not tied to a social provider. | A valid email address. |
| Google | Fast, one-click access without creating a separate password. | A Google account you can authorize. |
---
# Completing Onboarding
Source: https://www.hyperdocs.io/docs/get-started/completing-onboarding
# Completing Onboarding
Onboarding is the quick setup flow that prepares your Hyperdocs workspace and takes you straight to the admin dashboard. It helps you sign in, set up your account, and choose how you want to start building your documentation site so you can get going right away.
## How It Works
- You sign in with your email or a Google account to start the onboarding flow.
- A short setup sequence collects the basics needed to create your workspace.
- You choose a starting point for your docs, such as a documentation template or a connected GitHub repository.
- Once setup is complete, you land on the admin dashboard with quick links to the editor and your live site.
- Your dashboard greets you by name and shows recent activity and a preview of your starter docs.
## Steps
1. Log in to your account using your email address or by signing in with Google.
1. Follow the prompts in the onboarding flow to confirm your account details and create your workspace.
1. Choose how you want to start your documentation — pick a documentation template or connect a GitHub repository for auto-generated docs.
1. If prompted, configure basic branding such as your organization name so your workspace reflects your team.
1. Complete the final step to be taken to the admin dashboard, where you can open the editor or view your live site.
## Onboarding Choices
| Option | What It Does | Best For |
| --- | --- | --- |
| Documentation template | Sets up a ready-made docs structure you can edit in the block editor. | Writing docs by hand from scratch. |
| Connect GitHub repository | Links a repository so docs can be auto-generated from your code. | Teams that want docs drafted from code changes. |
| Import existing docs | Brings in documentation you already have (coming soon). | Migrating from another platform. |
## Tips
- Signing in with Google is the fastest way to get started if you don't want to set up a password.
- You can change your starting point later — picking a template now doesn't stop you from connecting GitHub afterward.
- Set your organization name early so your workspace and dashboard greeting feel personalized from the start.
> **TIP:** You can always revisit branding and general settings after onboarding to fine-tune your site's name, colors, and logos.
> **INFO:** After onboarding, your dashboard shows recent activity and quick links so you can jump straight into editing or previewing your site.
## Troubleshooting
- If sign-in fails, double-check your email and password, or try the Google sign-in option instead.
- If you don't reach the dashboard after onboarding, refresh the page and confirm you completed every step in the flow.
- If the GitHub option doesn't connect during onboarding, you can skip it and connect your repository later from the settings.
- If the import option appears unavailable, note that it's still coming soon — choose a template or GitHub for now.
Related topics: Choosing a Documentation Starting Point, Connecting a GitHub Repository, Configuring Branding and General Settings.
---
# Navigating the Admin Dashboard
Source: https://www.hyperdocs.io/docs/get-started/navigating-the-admin-dashboard
# Navigating the Admin Dashboard
The Hyperdocs admin dashboard is the control center for your entire documentation workspace. Every tool — from writing pages to publishing changelogs, running audits, and configuring SEO — is reachable from a persistent sidebar on the left. This page explains what each section is and where it lives so you can move around the admin confidently.
## The Admin Layout
The admin interface has two persistent elements that are always visible regardless of which section you are in:
- **Left sidebar** — the primary navigation. It lists every section of the admin in a fixed order. Click any item to navigate to that section.
- **Top bar** — runs across the top of every admin screen. It contains the language switcher, a notification bell, and your account menu.
## Sidebar Navigation Map
The table below lists every section in the sidebar, the route it opens, and what you do there.
| **Sidebar item** | **Route** | **What you do here** |
|---|---|---|
| **Dashboard** | `/admin/dashboard` | Your workspace home. See recent activity and quick links. |
| **Editor** | `/admin/editor` | Write, organize, and publish documentation pages and folders. |
| **Home** | `/admin/home` | Edit the landing page visitors see when they arrive at your docs site. |
| **Help Center** | `/admin/help-center` | Edit the help center hero, content blocks, and enable or disable the page. |
| **Changelog** | `/admin/changelog` | Add, edit, and publish dated changelog entries with tags. |
| **API Reference** | `/admin/api-reference` | Build and publish a structured public API reference. |
| **Git Sync** | `/admin/git-sync` | Connect a GitHub repository, review pending commits, and generate docs. |
| **Docs Audit** | `/admin/docs-audit` | Scan your codebase against your docs and get a documentation health score. |
| **Analytics** | `/admin/analytics` | View page views, unique visitors, and top pages across your site. |
| **Marketing → SEO** | `Marketing` group | Set site-wide meta title, description, OG image, scripts, CSS, and robots.txt. |
| **Marketing → Meta Tags** | `Marketing` group | Generate and manage per-page meta titles and descriptions with AI. |
| **Settings → Multilingual** | `Settings` group | Translate your docs into additional languages and manage published locales. |
| **Settings → Domain** | `Settings` group | Connect a custom domain to your documentation site. |
| **Settings → General Settings** | `Settings` group | Set your organization name, accent color, logos, favicon, and branding. |
| **Settings → Account** | `Settings` group | View your sign-in details, update your profile, and sign out. |
| **Upgrade / Billing** | `Settings` group | View your current plan, upgrade, and manage add-ons. |
## Dashboard
The **Dashboard** at `/admin/dashboard` is the first screen you land on after signing in. It shows a personalized greeting, recent activity across your workspace, and quick links to open the editor or view your live site. If you have not yet chosen a starting point for your documentation, the dashboard prompts you to do so before other sections become fully active.
## Editor
The **Editor** at `/admin/editor` is where you write and organize your documentation. The left sidebar inside the editor shows your page and folder tree. Clicking a page opens it in the block editor in the main panel. A right-hand settings panel lets you manage per-page SEO metadata and sharing options for the page you have open.
The editor top bar includes a **language switcher** that lets you switch between English (the source) and any translated locale you have set up. When a non-English locale is selected, the editor shows the translated copy of the page rather than the English source.
## Home, Help Center, and Changelog
These three sections each open a dedicated editor for a specific part of your public site:
- **Home** (`/admin/home`) — edit the landing page of your documentation site using the card-based block editor.
- **Help Center** (`/admin/help-center`) — configure the hero section (headline and supporting text), add content blocks, and toggle the help center on or off using the **Enable Help Center** switch in the header.
- **Changelog** (`/admin/changelog`) — add and edit dated changelog entries, manage tags, and organize entries by year using the year selector in the sidebar.
## API Reference
The **API Reference** section lets you build a structured, public-facing API reference inside Hyperdocs. The header contains **Edit** and **Preview** buttons to switch between building mode and a rendered preview, plus an **Enabled / Disabled** toggle that controls whether the API Reference tab appears on your public site.
## Git Sync
**Git Sync** (`/admin/git-sync`) connects your GitHub repository to Hyperdocs. From here you can check for pending commits, analyze changes with AI, generate documentation from your codebase, and configure sync settings such as the email digest. If no repository is connected, this screen shows the GitHub connection flow.
## Docs Audit
**Docs Audit** (`/admin/docs-audit`) scans your connected GitHub repository against your published documentation and produces a **documentation health score**, a list of undocumented areas, and a list of outdated claims. The left sidebar on this screen lists your audit history so you can load any past run.
## Analytics
The **Analytics** section (`/admin/analytics`) shows page view data for your published site. It has two tabs — **Overview** and **Pages** — and a set of range filters (**Today**, **Last 7 days**, **Last 30 days**, **Last 90 days**, **Last year**). A content-type filter lets you narrow data to **All**, **Documentation**, **Changelog**, **API Docs**, or **Help Center**.
> Analytics requires a starting point to be set for your documentation. If you have not yet chosen one, the analytics screen shows a prompt to go to the dashboard first.
## Marketing
The **Marketing** group in the sidebar contains two screens:
- **SEO** — configure site-wide defaults: Open Graph image, meta title, meta description, head scripts, body scripts, custom CSS, and a custom `robots.txt`. Changes take effect after you click **Save**.
- **Meta Tags** — view and manage per-page meta titles and descriptions across all your documentation pages in one table. You can generate tags in bulk with AI or edit individual rows. A language dropdown lets you switch the table to a translated locale. The **AI & Agents** tab on the SEO screen controls the **For Agents** menu and shows your AI-discovery resources (`llms.txt`, `llms-full.txt`, Markdown output, and `sitemap.xml`).
## Settings
The **Settings** group contains four screens:
- **Multilingual** — translate your documentation, changelog, and API reference into additional languages. Use the language dropdown to select a target locale, then translate and publish items from the pages table.
- **Domain** — connect a custom subdomain (for example, `docs.yourcompany.com`) and monitor its connection status.
- **General Settings** — set your organization name, description, brand accent color, light and dark logos, favicon, and the Hyperdocs branding toggle.
- **Account** — view your sign-in method (email or Google), update your profile details, and sign out. Your current plan and generation credit usage are also visible here.
## Top Bar Controls
The top bar is present on every admin screen and contains three controls:
- **Language switcher** — a dropdown showing the current editing language (for example, *English*). When you are viewing a translated locale, a **Translation** badge appears next to the language name. Switching here changes the language context for the editor, home, help center, and changelog screens simultaneously.
- **Notification bell** — shows a badge when a background job (such as a Docs Audit or Git Sync generation) has completed and results are ready. Opening the Docs Audit page clears the notification.
- **Account menu** — opens your account settings panel, where you can update your profile and sign out.
## Role-Based Access
Your workspace role controls what you can do in each section. Three roles exist: **Admin**, **Editor**, and **Viewer**.
| **Section** | **Admin** | **Editor** | **Viewer** |
|---|---|---|---|
| Editor — read content | ✓ | ✓ | ✓ |
| Editor — create, edit, delete pages | ✓ | ✓ | — |
| Home / Help Center / Changelog — edit and save | ✓ | ✓ | — |
| API Reference — edit content and toggle visibility | ✓ | ✓ | — |
| API Reference — toggle global Enabled / Disabled | ✓ | — | — |
| Git Sync — connect repo, generate docs | ✓ | — | — |
| Docs Audit — run audits, configure schedule | ✓ | — | — |
| Analytics — view data | ✓ | ✓ | ✓ |
| Marketing / SEO — save changes | ✓ | — | — |
| Meta Tags — generate and save | ✓ | — | — |
| Multilingual — translate and publish | ✓ | ✓ | — |
| General Settings — save changes | ✓ | — | — |
| Upgrade / Billing — manage plan | ✓ | — | — |
> Viewers can open and read every section of the admin but cannot create, edit, delete, save, or trigger any action. All input fields and action buttons are disabled for the Viewer role.
## Docs Agent
The **Docs Agent** is accessible from within the editor workflow. It includes an **About Company** panel where you provide context about your product — a company website URL and a free-text description — that the agent uses when drafting documentation. Admins and Editors can save and generate content here; Viewers can read but not save.
---
# Choose How to Start Your Documentation
Source: https://www.hyperdocs.io/docs/get-started/choose-how-to-start-your-documentation
# Choose How to Start Your Documentation
After you create a workspace, Hyperdocs gives you three ways to populate it with documentation. Each path leads into the same block editor, so you can switch approaches or combine them later. The choice you make here determines how your first content arrives — not what you can do afterward.
## The Three Starting Options
When your workspace is ready, you will see three options for getting documentation into it:
- **Template Docs** — open the block editor with a pre-built starter structure you can edit immediately.
- **Import existing Docs** — paste the URL of a live documentation site and Hyperdocs fetches, converts, and saves the pages for you.
- **Generate from GitHub** — connect your GitHub account, pick a repository and branch, and Hyperdocs generates a first draft of documentation from your codebase.
| Option | Best For | What You Get |
| --- | --- | --- |
| Template Docs | Writers who want to author content manually | A pre-built set of pages ready to edit in the block editor |
| Import Docs | Teams migrating existing documentation | A planned path to bring in content you already have |
| Generate from GitHub | Dev teams who want docs generated from code | Auto-drafted documentation based on repository commits |
## Option 1: Start with Template Docs
Choosing **Template Docs** opens the documentation editor with a ready-made page structure. No setup is required — you land directly in the block editor and can start writing, renaming pages, and organizing folders right away.
This option is best when you want to write documentation by hand from scratch, or when you do not yet have an existing site to import or a GitHub repository to connect.
- Select **Template Docs** from the starting options screen.
- The editor opens with a starter page tree. Click any page to begin editing its content.
- Add new pages and folders, rename items, and arrange the navigation tree to match your documentation structure.
- When you are ready, publish your changes to make the documentation live on your site.
## Option 2: Import Existing Documentation
The **Import existing Docs** option lets you bring in documentation from a live website by entering its URL. Hyperdocs detects the platform, discovers all pages, converts them to the block editor format, and saves the full tree to your workspace — without you copying and pasting anything manually.
Supported source platforms include **GitBook** and **Mintlify**. Hyperdocs fingerprints the site automatically, so you do not need to specify the platform yourself.
### How the Import Works
The import runs as a live streaming job with three stages you can watch in real time:
- *Detecting platform* — Hyperdocs reads the site's HTML to identify whether it is a GitBook, Mintlify, or other supported source.
- *Importing pages* — each page is fetched and converted. A counter shows how many pages have been fetched out of the total discovered (for example, `3 / 12`).
- *Saving to your workspace* — the converted page tree is persisted to your workspace as editable draft documentation.
Once the import completes, you are redirected to the documentation editor where all imported pages are ready to review, edit, and publish. A prompt also appears suggesting you run a **Docs Audit** to compare the imported content against your codebase.
### Steps to Import Documentation
- Select **Import existing Docs** from the starting options.
- In the **Import existing Docs** panel, enter the full URL of your existing documentation site in the URL field — for example, `https://docs.example.com`.
- Click **Import Documentation** to start the job. The button is disabled until a valid URL is entered.
- Watch the progress panel as it moves through the three stages. You will see the detected platform badge, a progress bar, and a live page counter.
- When the import finishes, you are taken to the editor. Review your imported pages, make any edits, and publish when ready.
### If the Import Fails
If the import cannot complete, an **Import Failed** screen appears with an error detail and a list of things to check:
- Confirm the URL points to a publicly accessible documentation site — login-gated sites cannot be crawled.
- JavaScript-rendered single-page applications may not be fully crawlable.
- Click **Try again with a different URL** to return to the URL input and try a corrected address.
### Replacing Existing Documentation
If your workspace already has documentation — either generated from GitHub or from a previous import — a confirmation dialog appears before the import starts. The dialog warns that the existing documentation will be replaced. Click **Import Docs** to proceed, or **Cancel** to keep the current content.
## Option 3: Generate Documentation from GitHub
The **Generate from GitHub** option connects your GitHub account, lets you pick a repository and branch, and then runs a generation job that produces a structured first draft of documentation from your codebase. The generated pages land in the block editor as editable drafts — nothing is published automatically.
### Connection Flow
The GitHub connection follows a step-by-step flow. Each step is shown in sequence:
- *Connect GitHub account* — click **Connect Frontend Repository** to open the GitHub App authorization flow in a new tab. Hyperdocs requests read-only access to your repositories. Your code is processed in memory and discarded after generation — it is never stored.
- *Waiting for GitHub* — after the tab opens, Hyperdocs polls for the authorization to complete. The screen shows a countdown and three steps to complete in GitHub: authorize the app, select repository access, and finish installation. The connection is detected automatically.
- *Reuse an existing account* — if you have already installed the Hyperdocs GitHub App on one or more accounts (from another workspace), a list of those accounts appears. Select one to link it to this workspace without going through the install flow again, or click **Connect a different GitHub account** to install on a new account.
- *Select a repository and branch* — once the account is linked, a searchable list of your repositories appears. Select the repository you want to generate docs from, then choose the branch to use. Each repository shows its name, visibility (Private badge if applicable), and a branch picker that loads available branches. The default branch is pre-selected.
- *Generate Documentation* — click **Generate Documentation** to start the generation job. The button is only active once a repository and branch are selected.
### Generation Progress
Once the job starts, a progress screen shows four stages in sequence:
- **Job queued** — your request has been received and is waiting to start.
- **Reading repository** — Hyperdocs scans the file tree and parses the code structure from GitHub.
- **Writing documentation** — code is sent to AI and structured documentation pages are generated.
- **Saving documents** — the generated pages are persisted to your workspace.
A progress bar and percentage counter update as the job advances. When generation completes, a success confirmation appears and you are redirected to the documentation editor. If the job fails, an error message is shown and you can try again.
### Privacy and Repository Access
Hyperdocs connects to GitHub with read-only access. Environment files and secret files are always skipped. Your repository code is processed in memory during generation and discarded immediately afterward — it is never written to disk or stored. Your code is never used to train AI models.
### If a Repository Does Not Appear
- If your repository is not in the list, click **Manage access on GitHub** (shown below the repository list) to open the GitHub App's installation settings and grant access to additional repositories.
- If generation fails with a plan error, your workspace may have reached its generation credit limit. Upgrade your plan to continue.
## Comparing the Three Options
All three options lead to the same block editor. The difference is how your initial content arrives:
- **Template Docs** — best when you are writing documentation from scratch and want a blank structure to fill in.
- **Import existing Docs** — best when you already have documentation published on a GitBook or Mintlify site and want to bring it into Hyperdocs without manual copying.
- **Generate from GitHub** — best when you have an active codebase and want a first draft generated automatically, so you start editing rather than writing from a blank page.
You are not locked into your initial choice. After setup, you can connect a GitHub repository from the Git Sync section, import additional content, or write new pages manually at any time.
---
# Editing the Home Page
Source: https://www.hyperdocs.io/docs/create-and-manage-content/editing-the-home-page
# Editing Docs Home Page
The home page is the landing page visitors see when they arrive at your documentation site. With the card-based block editor, you can shape this page to highlight key sections, welcome users, and guide them toward the content that matters most.
## How It Works
- Build your landing page using a flexible, card-based block editor that lets you arrange sections visually.
- Add headings, paragraphs, links, and content cards to organize how visitors navigate your docs.
- Apply your brand accent color, logos, and styling so the home page matches the rest of your site.
- Reset the page back to the default template at any time if you want to start fresh.
- Preview your changes before publishing, then push them live to your public site.
## Steps
1. Open the admin dashboard and select the home page editor.
1. Add or edit blocks by clicking into the canvas and choosing headings, text, links, or cards.
1. Arrange the cards and sections in the order you want visitors to see them.
1. Click Preview to see how the home page will appear on the live site.
1. When you are satisfied, publish your changes to update the public home page.
## Home Page Editing Options
| Option | What It Does |
| --- | --- |
| Content cards | Add highlighted cards that link to key pages or sections of your documentation. |
| Headings & text | Write a welcome message, introduction, or section titles to guide visitors. |
| Branding | Your accent color and logos from general settings are applied automatically. |
| Reset to default | Restore the original starter template if you want to begin again. |
## Tips
- Keep your home page focused — use cards to point visitors to your most-used sections rather than overcrowding the page.
- Set your brand accent color and logos in general settings first, so the home page reflects your branding from the start.
- Always preview before publishing to confirm the layout looks the way you expect on the live site.
> **TIP:** Use the reset option to quickly recover a clean layout if your edits get cluttered — but remember it replaces your current content.
> **WARNING:** Resetting to the default template cannot be undone, so consider previewing your current version before you reset.
## Troubleshooting
- Changes not appearing on the live site? Make sure you clicked Publish — saving alone may not push updates to visitors.
- Branding looks off? Confirm your accent color, logos, and favicon are set correctly in general settings.
- Lost your edits after a reset? Resetting restores the default template and replaces your custom content, so re-add your blocks as needed.
- Preview not loading? Try refreshing the editor and ensure your site has been published at least once.
Related topics: Configure Branding and General Settings, Preview and Publish the Site, Edit the Help Center.
---
# Editing the Help Center
Source: https://www.hyperdocs.io/docs/create-and-manage-content/editing-the-help-center
# Editing the Help Center
The help center is a dedicated page on your documentation site where readers can find answers, guides, and support resources in one welcoming place. With the help center editor you can craft an inviting hero section, arrange content blocks, and reset everything to a clean default layout whenever you need a fresh start.
## How It Works
- Configure a hero section at the top of the page with a headline and supporting text to greet your readers.
- Add and arrange content blocks below the hero to highlight key articles, categories, or quick links.
- Use the rich block editor to format text, add headings, lists, and other elements within each block.
- Reset the entire help center back to the default template at any time to start over.
- Preview your changes and publish them live so visitors see the updated help center on your site.
## Steps
1. Open the admin area and select the Help Center editor from the navigation.
1. Edit the hero section by updating the headline and supporting text that appear at the top of the page.
1. Add or rearrange content blocks below the hero, using the block editor to format each one with headings, text, and lists.
1. Use the live preview to check how the help center looks to your readers.
1. Publish your changes to make the updated help center visible on your public site.
## Help Center Sections
| Section | Purpose | Editable Options |
| --- | --- | --- |
| Hero | Welcomes visitors and sets the tone for the help center. | Headline and supporting text. |
| Content Blocks | Showcase guides, categories, and helpful links. | Headings, formatted text, lists, and arrangement. |
| Default Template | Provides a clean starting layout you can restore anytime. | Reset to default. |
## Tips
- Keep your hero headline short and clear so readers immediately understand they've reached the help center.
- Group related guides into separate content blocks to make the page easy to scan.
- Preview before publishing to confirm formatting and links look the way you expect.
> **WARNING:** Resetting to the default template replaces your current help center layout. Make sure you no longer need your existing content before resetting.
> **TIP:** Match your help center wording to your brand voice so it feels consistent with the rest of your documentation.
## Troubleshooting
- Changes not showing on the live site? Make sure you published after editing — saved drafts are not visible to readers until published.
- Hero text looks empty? Confirm you entered a headline and supporting text and saved the section.
- Accidentally reset the page? Re-add your content blocks manually, as resetting restores the default layout and cannot recover prior edits.
- Formatting appears incorrect in preview? Recheck the block editor and adjust headings or lists before publishing.
Related topics: Edit the Home Page, Manage a Changelog, Preview and Publish the Site.
---
# Editing Pages with the Block Editor
Source: https://www.hyperdocs.io/docs/create-and-manage-content/writing-documentation/editing-pages-with-the-block-editor
# Editing Pages with the Block Editor
The block editor is where you write and format your documentation content. Each page is built from individual blocks — headings, paragraphs, lists, quotes, code, and images — so you can shape clear, well-structured pages without any technical setup.
## How It Works
- Content is organized into stackable blocks, so you can add, rearrange, and remove sections independently.
- You can structure pages with multiple heading levels for titles, sections, and subsections.
- Inline text formatting includes bold, italic, underline, strikethrough, and inline code.
- Block types include bulleted and numbered lists, blockquotes, dividers, code blocks, and images.
- Your changes are saved with your page and shown exactly as written when the site is published.
## Steps
1. Open the documentation editor and select the page you want to edit from the navigation tree.
1. Click into the page and start typing, or add a new block where you want your content to appear.
1. Choose a block type — such as a heading, paragraph, list, quote, code block, or image — to format that section.
1. Highlight text to apply inline formatting like bold, italic, underline, or inline code.
1. Reorder, edit, or delete blocks until the page reads the way you want.
1. Preview the page, then publish to make your changes live on your site.
## Available Block Types
| Block | What it's for |
| --- | --- |
| Headings (H1, H2, H3) | Page titles, section headers, and subsections to organize content. |
| Paragraph | Standard body text with inline formatting. |
| Bulleted & numbered lists | Step-by-step instructions or grouped points. |
| Blockquote | Highlight callouts, tips, or quoted notes. |
| Code block & inline code | Display commands or code snippets with monospaced styling. |
| Divider & image | Separate sections visually or add screenshots and illustrations. |
## Tips
- Use a single H1 for the page title and H2/H3 for sections so readers can scan your content easily.
- Use inline code for short references like names or values, and code blocks for multi-line snippets.
- Break long paragraphs into lists or shorter sections to keep pages readable.
> **TIP:** Preview your page before publishing — it shows exactly how your formatting will appear to readers on the live site.
> **INFO:** Empty paragraphs are rendered as spacing, so you can add a blank block to create breathing room between sections.
## Troubleshooting
- Changes not appearing live? Make sure you published the page after editing — saved edits stay in the editor until published.
- Formatting looks off? Check that the correct block type is applied and that inline formatting wasn't accidentally left active.
- Image not showing? Confirm the image was added correctly and that its source is valid.
- Can't find a page to edit? Verify it exists in the navigation tree and hasn't been moved into a different folder.
Related topics: Organizing Your Docs Structure, Preview and Publish the Site, Editing the Home Page.
---
# Organizing Pages and Folders
Source: https://www.hyperdocs.io/docs/create-and-manage-content/writing-documentation/organizing-pages-and-folders
# Organizing Pages and Folders
The documentation editor lets you build and arrange your site's navigation by creating pages and folders in a flexible tree. Clear organization helps readers find what they need quickly and gives your docs a logical, professional structure.
## How It Works
- Create new pages to hold individual documentation topics within your site's tree.
- Group related pages inside folders to form sections and subsections in your navigation.
- Rename and delete pages or folders at any time to keep your structure current.
- Drag and drop items to reorder them or nest them under other folders.
- Changes to the navigation tree appear in your live preview before you publish.
## Steps
1. Open the documentation editor from your dashboard to view the current page and folder tree.
1. Click the add button to create a new page or folder, then give it a clear, descriptive name.
1. To rename an item, select it and edit its title; to remove it, choose the delete option and confirm.
1. Drag any page or folder up or down to reorder it, or drop it onto a folder to nest it inside.
1. Review the structure in the live preview, then publish to update the public navigation.
## Page and Folder Actions
| Action | What It Does | Applies To |
| --- | --- | --- |
| Create | Adds a new item to the navigation tree | Pages and folders |
| Rename | Changes the displayed title | Pages and folders |
| Reorder | Drag to change position in the list | Pages and folders |
| Nest | Places a page or folder inside another folder | Pages and folders |
| Delete | Permanently removes the item from the tree | Pages and folders |
## Tips
- Use folders to group related topics so readers can scan your navigation at a glance.
- Keep page names short and descriptive — they double as navigation labels on your published site.
- Order your most important pages near the top so visitors see them first.
> **TIP:** Preview your site after reordering to confirm the navigation flows the way you expect before publishing.
> **WARNING:** Deleting a folder removes the pages nested inside it, so move any pages you want to keep before deleting.
## Troubleshooting
- If a new page does not appear, refresh the editor to make sure the latest tree is loaded.
- If drag-and-drop will not nest an item, drop it directly onto the folder rather than between pages.
- If changes are missing on your live site, confirm you published after editing the navigation.
- If a deleted page reappears, check that the deletion was confirmed and the editor finished saving.
Related topics: Edit Documentation Pages, Preview and Publish the Site, Configure Branding and General Settings.
---
# Configuring Site Navigation
Source: https://www.hyperdocs.io/docs/create-and-manage-content/writing-documentation/configuring-site-navigation
# Configuring Site Navigation
Your documentation navigation is built from the pages and folders in your docs tree. By structuring this tree thoughtfully, you control the order readers encounter your content and how easily they move between topics on your published site.
## How It Works
- The docs editor displays your pages and folders in a navigable tree that mirrors the navigation readers see on your live site.
- You can create new pages and folders, rename them, and delete items you no longer need.
- Drag-and-drop reordering lets you change the sequence of pages and folders to match your preferred reading flow.
- Nesting pages inside folders creates grouped sections, giving your navigation a clear hierarchy.
- Changes to the tree are reflected in the live preview and on your public site once published.
## Steps
1. Open the documentation editor from your dashboard to view the current page and folder tree.
1. Create a new folder to group related topics, or add a new page where you want fresh content to live.
1. Rename pages and folders so their titles clearly describe what readers will find inside.
1. Drag items up or down, or into a folder, to set the order and nesting of your navigation.
1. Delete any outdated pages or folders to keep the navigation clean and focused.
1. Open the live preview to confirm the navigation reads the way you intended, then publish your changes.
## Navigation Actions
| Action | What It Does | Best Used For |
| --- | --- | --- |
| Create page | Adds a new content page to the tree | Individual topics or articles |
| Create folder | Adds a grouping container for pages | Sections with multiple related pages |
| Rename | Updates the title shown in navigation | Clarifying labels for readers |
| Drag-and-drop | Reorders or nests items | Setting reading sequence and hierarchy |
| Delete | Removes a page or folder from the tree | Clearing outdated content |
## Tips
- Order your most important pages near the top of the tree so readers find essential information first.
- Group related pages under clearly named folders to keep deep topics tidy and easy to scan.
- Use short, descriptive titles since they double as navigation labels on your live site.
> **TIP:** Always check the live preview before publishing to make sure your navigation flows logically for first-time readers.
> **WARNING:** Deleting a folder may remove the pages nested inside it, so move any content you want to keep before deleting.
## Troubleshooting
- If your navigation changes don't appear on the live site, confirm you published after editing the tree.
- If drag-and-drop doesn't drop an item where expected, release it directly over the target folder or position and try again.
- If a renamed page still shows the old title in preview, refresh the preview to load the latest structure.
- If a page seems missing, check whether it was accidentally nested inside a collapsed folder in the tree.
Related topics: Edit documentation pages, Preview and publish the site, Edit the home page.
---
# API Reference
Source: https://www.hyperdocs.io/docs/create-and-manage-content/api-reference/api-reference
# API Reference
API Reference lets you build and publish a structured, public-facing API reference directly inside Hyperdocs. You define your APIs, document their endpoints, parameters, request bodies, responses, and code samples in the admin editor, then publish the result alongside your product docs, changelog, and help center — all on the same site.
## How It Works
The API Reference editor lives at **API Reference** in your admin sidebar. It has two modes you switch between using the **Edit** and **Preview** buttons in the header:
- **Edit** mode is where you build your reference. A sidebar lists your API definitions, versions, and every category and endpoint. Selecting an item in the sidebar opens its editor in the main panel.
- **Preview** mode renders the full public-facing API reference exactly as visitors will see it, so you can review layout and content before saving.
A global **Enabled** / **Disabled** toggle in the header controls whether the API Reference tab appears on your public site. When disabled, the tab is hidden from visitors but your content is preserved in the editor.
## Admin Editor Structure
The editor is organized into four sections, each accessible from the sidebar: **API Definitions**, **Authentication**, **Versions**, and individual **Endpoints** grouped under categories.
### API Definitions
An API definition is the top-level container for one API. Each definition has a **title** and a **base URL** (for example, `https://api.example.com`). You can have more than one definition in a workspace — each appears as a separate selectable API in the sidebar.
Each definition card also has an **API Explorer** toggle. When on, a live *Try It* console is shown to visitors on each endpoint page, letting them send real requests from the browser.
To create a definition, click **New Definition**, enter a title and base URL, and save. To delete one, use the delete button on its card — at least one definition must always remain.
### Authentication
The **Authentication** section lets you define reusable authentication methods that can be attached to individual endpoints. Two types are supported:
- **API Key** — a key sent in a request header or query parameter. You set the **Type** to `apiKey`, the **Location** to `header` or `query`, and the **Key Name** (for example, `x-api-key`).
- **Bearer Token** — a token sent in the `Authorization` header. You set the **Type** to `bearer` and the **Key Name** to `Authorization`.
Add a method using the **+ API Key** or **+ Bearer Token** buttons. Each method has an editable name. Methods you create here become available to attach to any endpoint via the **Credentials** panel in the endpoint editor.
### Versions
The **Versions** section lists the API versions for the selected definition. Each version has a **name** (for example, `v1.0`) and three settings you can toggle:
- **Deprecated** — marks the version as deprecated for visitors.
- **Visibility** — controls whether the version is shown as **Default**, **Public**, or **Hidden** on the public site.
The active version is selected from the version dropdown at the top of the sidebar. The selected version determines which version prefix appears in endpoint URLs on the public site.
### Categories and Endpoints
Endpoints are organized into **categories**. A category groups related endpoints under a shared name and slug, which becomes the URL path on the public site (for example, `/api-reference/users`).
To add a category, click the **+** button next to the **Categories** heading in the sidebar and enter a name. To add an endpoint inside a category, select the category and use the **+** button next to it.
Each endpoint has the following fields you edit in the main panel:
- **Title** — the human-readable name shown in the sidebar and on the public endpoint page.
- **HTTP method** — select from `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`, or `TRACE` using the method dropdown. Each method is color-coded.
- **Path** — the endpoint path appended to the base URL, for example `/users/{id}`.
- **Description** — a plain-text summary of what the endpoint does.
- **Visibility** — set to **public** to show the endpoint to visitors, or **private** to hide it from the public site while keeping it in the editor.
- **Content** — a rich block editor area where you can write longer documentation for the endpoint, using headings, paragraphs, lists, blockquotes, and code blocks.
## Endpoint Detail Sections
Each endpoint editor has additional sections in the right-hand panel for documenting the full contract of the endpoint.
### Parameters
Parameters are grouped into three types: **Path Parameters**, **Query Parameters**, and **Header Parameters**. For each parameter you set:
- **Name** — the parameter key as it appears in the request.
- **Data type** — choose from types including `string`, `number`, `integer`, `boolean`, `array`, `object`, and format variants such as `date`, `date-time`, `password`, `byte`, `binary`, and `json`.
- **Required / optional** — click the label to toggle whether the parameter is required.
- **Default value** — an optional default shown in the public reference.
- **Description** — a short explanation of what the parameter does.
- **Enum values** — an optional list of allowed values. Click the enum control to add or remove values; they are displayed as chips on the public endpoint page.
### Request Body
Click **Add request body** to attach a request body to an endpoint. The request body has a **content type** field (for example, `application/json`) and an **example** field where you enter a JSON object. The example is shown to visitors on the public endpoint page.
To remove the request body, click **Remove** in the section header.
### Responses
Add one or more response definitions using the **+ Add Response** button. For each response you select a **status code** from a picker organized by category (success, warning, error). Each response also has a **content type** and a JSON **example** that visitors can expand to read.
Response rows are color-coded by category: green for success (2xx), amber for redirects and warnings (3xx), and red for errors (4xx / 5xx).
### Credentials
The **Credentials** panel lets you attach authentication methods to the endpoint. Click **+** to open a picker showing the auth methods you defined in the Authentication section. Attached methods are listed on the public endpoint page under the authentication details. Click the remove button on an attached method to detach it.
### Custom Code Samples
The **Custom Code Samples** section lets you add language-specific code examples for the endpoint. Click **+** to pick a language (Shell, JavaScript, Python, PHP, Go, Java, C#, C++, PowerShell, Ruby, or Swift), then type or paste the code into the editor area. Multiple languages appear as tabs that visitors can switch between.
## Public Visitor Experience
When the API Reference is enabled, it appears as a tab on your public documentation site. The public view has a left sidebar listing all categories and their endpoints. Visitors can:
- Browse categories — clicking a category shows a list of its public endpoints with their HTTP method badge and path.
- Open an endpoint — clicking an endpoint shows its full detail page: title, method, path, description, parameters table, request body example, response examples, authentication details, and code samples.
- View authentication — the **Authentication** page in the sidebar lists every auth method with its type, location, key name, and a formatted example header or query string.
- Only endpoints with **Visibility** set to **public** appear on the public site. Endpoints set to **private** are visible in the admin editor but hidden from visitors.
## Saving Changes
Changes to definitions, authentication methods, versions, and endpoint content are saved by clicking **Save** in the header. The **Save** button is context-aware:
- When **API Definitions** is selected in the sidebar, clicking **Save** saves all definition titles, base URLs, and API Explorer settings.
- When **Authentication** is selected, clicking **Save** saves all auth methods for the current definition.
- When **Versions** is selected, clicking **Save** saves all version names, deprecated flags, and visibility settings.
- When an **endpoint** is selected, clicking **Save** saves the entire category — including all its endpoints, parameters, request bodies, responses, and code samples — in a single operation.
The button label changes to **Saving…** while the request is in flight and to **Saved** briefly after a successful save. The public API reference cache is refreshed automatically after each save so visitor-facing pages reflect your changes immediately.
## Role-Based Access
Access to the API Reference editor is controlled by your workspace role:
- **Admin** and **Editor** roles can view the editor, add and edit all content, and toggle endpoint visibility.
- **Viewer** role can open the editor and read all content but cannot create, edit, delete, or save anything. All input fields and action buttons are disabled for Viewers.
- Only **Admins** can toggle the global **Enabled / Disabled** switch that controls whether the API Reference appears on the public site.
## Steps to Build and Publish an API Reference
- Open your admin dashboard and select **API Reference** from the sidebar.
- In the sidebar, select **API Definitions**. Click **New Definition**, enter a **title** and **base URL**, and save.
- Select **Authentication** and add any auth methods your API uses — click **+ API Key** or **+ Bearer Token**, fill in the fields, and save.
- Select **Versions** to review or rename the default version. Set its **Visibility** and **Deprecated** flag as needed, then save.
- In the sidebar, click **+** next to **Categories** to create your first category. Give it a clear name that describes the group of endpoints it will contain.
- Select the category and click **+** to add an endpoint. Set the **title**, **HTTP method**, **path**, **description**, and **Visibility** to `public`.
- In the endpoint editor, add **Parameters**, a **Request Body**, **Responses**, **Credentials**, and **Custom Code Samples** as needed.
- Click **Save** to persist the endpoint and its category.
- Repeat for each category and endpoint in your API.
- Switch to **Preview** mode using the button in the header to review the public layout. Confirm that categories, endpoints, parameters, and examples appear as expected.
- Return to **Edit** mode and turn on the **Enabled** toggle in the header to make the API Reference visible on your public site.
---
# Publishing Changelog Updates
Source: https://www.hyperdocs.io/docs/create-and-manage-content/changelog-and-pages/publishing-changelog-updates
# Publishing Changelog Updates
The changelog lets you share product updates with your users in a clean, chronological layout. Each entry has its own date, optional tags, and richly formatted content, so visitors can quickly scan what changed and when. Keeping your changelog current builds trust and keeps your audience informed about new features and fixes.
## How It Works
- Add dated entries that appear in chronological order, grouped by year, on your public changelog page.
- Write and format each entry using a rich block editor with headings, lists, quotes, code, and images.
- Apply custom tags with their own labels, colors, and icons to categorize updates such as New, Improved, or Fixed.
- Edit existing entries at any time to correct details or expand on a release.
- Preview your changelog and publish it to your live site so visitors can filter entries by tag.
## Steps
1. Open the changelog editor from your admin area.
1. Click to add a new entry and set its publication date so it lands in the correct spot on the timeline.
1. Give the entry a clear title that summarizes the update.
1. Apply one or more tags to categorize the update, choosing existing tags or creating new ones with custom labels, colors, and icons.
1. Write the entry content in the block editor, adding headings, bullet lists, code snippets, or images as needed.
1. Save your changes, preview the result, and publish to make the update visible on your public changelog.
## Entry Options
| Option | What It Does |
| --- | --- |
| Date | Sets when the update is shown; entries are grouped and ordered by year and date. |
| Title | A short headline shown at the top of the entry to summarize the release. |
| Tags | Custom labels with colors and icons that let visitors filter entries by category. |
| Content | Rich formatted body supporting headings, lists, quotes, code blocks, and images. |
## Tips
- Use consistent tag names like New, Improved, and Fixed so visitors can quickly filter updates.
- Lead each entry with a concise title and a short summary before diving into detailed bullet points.
- Pick distinct tag colors and icons so categories stand out at a glance on the public page.
> **TIP:** Always preview an entry before publishing to confirm formatting, tags, and the date appear exactly as you intend.
> **INFO:** Entries are organized by year, so setting an accurate date keeps your timeline tidy and easy to navigate.
## Troubleshooting
- Entry not appearing on the live site? Make sure you saved and published your changes after editing.
- Entry showing under the wrong year? Check the entry's date, since entries are grouped by the year you set.
- Tag colors or icons not displaying correctly? Reopen the tag settings and confirm a color and icon are selected.
- Formatting looks off in the preview? Return to the block editor and adjust the affected blocks, then preview again.
Related topics: Editing Documentation Pages, Editing the Home Page, Preview and Publish Your Site.
---
# Multilingual
Source: https://www.hyperdocs.io/docs/create-and-manage-content/multilingual/multilingual
# Multilingual
The **Multilingual** screen lets you translate your documentation into additional languages using AI. Each language is stored and published independently, so your English content is never changed. Translated content goes through a draft state before it is made visible to visitors, and you control exactly which languages appear on your public site.
## How It Works
Translations are generated by a background job that runs against the content you select. The job tracks progress in the database, so if you navigate away and return, the progress bar resumes from where it left off. Once a translation job finishes, each translated item enters a *draft* state — it is stored but not yet visible to visitors. A separate publish step makes it live.
Your English source content is never modified by a translation run. Re-translating an item replaces only that language's copy, including any manual edits you made to it. A confirmation dialog appears before any existing translation is overwritten.
The **Answer Agent** chat widget automatically follows the language a visitor is reading in. If a visitor is browsing your docs in French, the Answer Agent answers in French. You do not configure this separately — it is tied to whichever languages you switch on.
## Opening the Multilingual Screen
Open your admin dashboard and select **Settings** -> **Multilingual** from the sidebar. The page header shows a globe icon, the **Multilingual** title, and a count of how many languages are currently published on your public site, with a flag icon for each.
## Selecting a Language
Use the language dropdown at the top of the content panel to choose which language you are working with. Everything below it — the public toggle, the stats cards, and the pages table — is scoped to the language you select here. The dropdown shows a flag and the language name for each available language. A green dot next to a language in the list means it is currently live on your public site.
## Making a Language Public
Below the language dropdown is the public visibility toggle. This single switch controls whether visitors can read your site in the selected language.
The toggle has three states:
- **Locked** — the language has no translated content yet. The toggle is disabled and shows a *Locked* badge. Translate at least one page to unlock it.
- **Hidden** — the language has translated content but is not shown to visitors. Turn the toggle on to add it to the language switcher on your public site.
- **Live** — the language is active on your public site. Visitors can switch to it using the language switcher. A link to the public URL for that language appears below the toggle so you can verify it directly.
Turning a language off hides it from visitors without deleting any translation. You can turn it back on at any time.
## Content Tabs
Three tabs let you work on different content areas independently. Switching tabs changes which items appear in the stats and pages table below.
- **Docs** — your documentation pages and folders.
- **Changelog** — your changelog entries.
- **API Reference** — your API reference categories and endpoints.
## Translation Stats
Three stat cards appear below the tabs, scoped to the active tab and selected language. These counts reflect the full scope, not just the current page of the table.
- **Translated to [language]** — shows how many items have been translated out of the total (e.g. *4/12*).
- **Published** — the number of translated items that are live on your public site.
- **In draft** — translated items that have not been published yet. These are finished translations waiting to go live.
## The Pages Table
The pages table lists every translatable item in the active tab. Each row shows the item's name, its translated name (if one exists), and a status badge.
Status badges in the table:
- **Not translated** — no translation exists for this item in the selected language.
- **Draft** — the item has been translated but not yet published.
- **Published** — the translated version is live on your public site.
### Filtering and Searching
Filter chips above the table let you narrow the list. Each chip shows a count of how many items match.
- **All pages** — shows every item in the scope.
- **Not translated** — shows only items with no translation yet.
- **Published** — shows only items whose translation is live.
- **Draft** — shows only translated items waiting to be published.
Use the **Search pages...** field to find a specific item by name. The search is debounced and runs on the server, so results update automatically as you type.
### Per-Row Actions
Each row in the table has action buttons on the right side, depending on the item's current status.
- **Translate to [language]** — appears on rows that have not been translated yet. Clicking it starts a translation job for that single item without affecting your checkbox selection.
- **Publish** — appears on rows that are translated but still in draft. Clicking it publishes only that item.
- **Edit in [language]** — appears on translated rows in the **Docs** and **Changelog** tabs. Clicking it opens the admin editor already switched to the selected language, so you land directly on the translated copy.
---
# Translating Items
Source: https://www.hyperdocs.io/docs/create-and-manage-content/multilingual/translating-items
# Translating Items
### Translating Selected Items
Use the checkboxes in the table to select the items you want to translate, then click the **Translate [n] to [language]** button in the toolbar above the table.
- Select the items you want to translate using the checkboxes in the table. Checking a folder automatically selects everything nested inside it.
- If you have selected all visible rows and there are more rows on other pages, a **Select all [n] pages** link appears. Click it to escalate your selection to every item the current filter matches — including rows you have not downloaded.
- Click **Translate [n] to [language]** to queue the job. If any selected items already have a translation, a confirmation dialog appears before the job starts, warning that re-translating will replace the existing translation including any manual edits.
- Confirm by clicking **Re-translate**, or cancel to keep the existing translation..
### Translating a Single Item
Click **Translate to [language]** on any individual row to translate just that item without using the checkboxes. The button changes to *Translating…* while the job runs. If the item already has a translation, the same overwrite confirmation dialog appears first.
### Translation Progress
While a translation job is running, a progress bar appears between the stats cards and the table. It shows:
- The target language's flag and the message *Translating into [language]…*
- A completed/total counter (e.g. *3/10*) scoped to the items you selected, not the backend's internal count.
- A progress bar that fills as items complete.
- If any items could not be translated, a note appears below the bar: *[n] item(s) could not be translated and kept their English content.*
You can navigate away while a job is running. When you return to the Multilingual screen, the progress bar resumes from the correct position because progress is stored in the database, not in the browser.
## Publishing Translations
Translating an item puts it into draft. Publishing is a separate step that makes the translation visible to visitors. There are three ways to publish.
- **Publish all** — the button in the top-right of the table header. Publishes every translated-but-unpublished item in the active tab for the selected language in one action. The button is disabled when there are no draft items.
- **Publish [n] selected** — appears in the toolbar when you have checked rows that include at least one translated item. Publishes only the checked rows. Rows that are not yet translated are skipped.
- **Publish** (per row) — the green **Publish** button on an individual draft row. Publishes only that one item.
## Plan Limits and Language Add-ons
Your plan includes a set number of languages. A language slot is consumed the first time you either translate content into it or switch it on for the public site — whichever happens first. Re-translating or re-publishing a language you have already used does not consume an additional slot.
If you attempt to translate into or publish a new language that would exceed your plan's limit, a dialog appears showing how many languages are in use versus your plan's total. From this dialog you can:
- Click **Buy a language** to purchase an individual language add-on at a monthly per-language price (available on eligible plans).
- Click the upgrade action to move to a higher plan with a larger language allowance.
- Free workspaces see an upgrade banner at the top of the Multilingual screen. The controls remain active — the limit dialog appears on click rather than disabling the buttons.
## Steps to Translate and Publish a Language
- Open the admin dashboard and select **Multilingual** from the sidebar.
- Use the language dropdown to select the language you want to translate into.
- Select a content tab — **Docs**, **Changelog**, or **API Reference** — to choose which area to work on.
- Use the filter chips or **Search pages...** field to find the items you want to translate.
- Check the items you want to translate, or use **Select all [n] pages** to include every matching item.
- Click **Translate [n] to [language]**. If prompted to confirm an overwrite, click **Re-translate** to proceed.
- Watch the progress bar until the job completes. Review the translated items in the table — their status will show **Draft**.
- Click **Publish all** to publish every draft in the tab, or select specific rows and click **Publish [n] selected**.
- Turn on the **Show [language]** toggle to make the language available to visitors on your public site.
- Verify the result by clicking the public URL link that appears below the toggle.
## Editing a Translation Manually
For **Docs** and **Changelog** items, translated rows show an **Edit in [language]** button. Clicking it opens the admin editor already switched to the selected language, so you are editing the translated copy rather than the English source. Changes autosave. Use the publish bar inside the editor to take your edits live without returning to the Multilingual screen.
Re-translating an item that you have manually edited will replace your edits with a fresh AI translation. The overwrite confirmation dialog reminds you of this before the job starts.
---
# Previewing and Publishing the Site
Source: https://www.hyperdocs.io/docs/publish-customise/publishing-your-site/previewing-and-publishing
# Previewing and Publishing the Site
Previewing and publishing lets you see exactly how your documentation, changelog, and home pages will appear to visitors before they go live. When you're happy with the result, you can publish your changes to your public site with confidence.
## How It Works
- Open a live preview of your docs, changelog, home page, and help center to see them rendered just as visitors will.
- Review formatting, layout, branding, and navigation in context before anything is made public.
- Publish your changes to push the latest content to your live, public-facing site.
- Access your site on the default Hyperdocs subdomain or your connected custom domain once published.
- Jump straight from the dashboard or editor to open the live site in a new view.
## Steps
1. Open the editor and make the content changes you want across your docs, changelog, or home page.
1. Select the preview option to open a live view of the page you're working on.
1. Check that headings, text formatting, lists, images, branding, and navigation all appear the way you expect.
1. Return to the editor to fix anything that needs adjusting, then preview again.
1. When everything looks right, select Publish to make your changes available on the public site.
1. Open your live site on its Hyperdocs subdomain or custom domain to confirm the update is live.
## What You Can Preview and Publish
| Page Type | What You See in Preview |
| --- | --- |
| Documentation | Pages and folders rendered with full formatting and your navigation structure. |
| Changelog | Dated entries in chronological order with their tags, colors, and icons. |
| Home Page | Your landing page with card-based blocks and applied branding. |
| Help Center | The hero section and content blocks as visitors will experience them. |
## Tips
- Preview after every significant change so you catch layout or formatting surprises early.
- Check both light and dark appearances if you've uploaded separate logos, so your branding looks right in each.
- Use the quick links on the dashboard to open the editor or jump straight to your live site.
> **TIP:** Preview is the safest way to review changes — nothing you see in preview is visible to the public until you publish.
> **INFO:** Your site is always available on its default Hyperdocs subdomain, even before you connect a custom domain.
## Troubleshooting
- If your changes don't appear on the live site, confirm you selected Publish after saving your edits in the editor.
- If the live site still shows old content, refresh the page in your browser, as cached versions can linger briefly.
- If your custom domain isn't serving the site, check that the domain connection has been verified in your domain settings.
- If branding such as logos or accent color looks wrong in preview, revisit your general settings and confirm your uploads were saved.
Related topics: Connect a Custom Domain, Configure Branding and General Settings, Edit the Home Page.
---
# Connecting a Custom Domain
Source: https://www.hyperdocs.io/docs/publish-customise/publishing-your-site/connecting-a-custom-domain
# Connecting a Custom Domain
Connecting a custom domain lets you serve your documentation, changelog, and help center pages from your own branded web address instead of the default Hyperdocs subdomain. This makes your docs feel like a seamless part of your product and builds trust with your readers.
## How It Works
- Your site is always available on a default Hyperdocs subdomain, so it stays live even before you add a custom domain.
- You can connect a custom subdomain, such as docs.yourcompany.com, to point readers to your own address.
- After adding a domain, Hyperdocs walks you through verifying ownership and connection status.
- You can monitor whether the domain is pending, verified, or fully connected directly from your settings.
- Once connected, all your published docs, changelog, and home pages are served automatically on the new domain.
## Steps
1. Open your admin dashboard and go to the Domain settings section.
1. Enter the custom subdomain you want to use, for example docs.yourcompany.com.
1. Save the subdomain to begin the connection process.
1. Add the DNS records shown by Hyperdocs to your domain provider to point the subdomain to your site.
1. Return to the Domain settings and check the connection status until it shows as verified.
1. Once verified, publish your site to make it available on your custom domain.
## Domain Connection Status
| Status | What It Means |
| --- | --- |
| Default subdomain | Your site is live on the built-in Hyperdocs subdomain with no setup required. |
| Pending verification | You have added a custom subdomain, but DNS records have not yet been confirmed. |
| Verified | DNS records are confirmed and your domain is ready to serve docs. |
| Connected | Your published site is live on your custom domain. |
## Tips
- Use a clear, memorable subdomain like docs or help so readers can easily guess and remember your documentation address.
- DNS changes can take time to spread across the internet, so wait a little while before assuming the connection failed.
- Keep your default Hyperdocs subdomain in mind as a reliable fallback while you finish setting up the custom domain.
> **INFO:** Your site remains fully accessible on the default Hyperdocs subdomain at all times, even while a custom domain is still verifying.
> **TIP:** Double-check that the DNS records you copy into your domain provider exactly match the ones shown in Hyperdocs to avoid delays.
## Troubleshooting
- If your domain stays in pending verification, confirm the DNS records were added correctly at your domain provider and saved.
- If the verified domain does not show your latest content, make sure you have published the site after connecting it.
- If you mistyped the subdomain, remove it from Domain settings and add the correct address again.
- If readers reach an error page, verify the connection status is showing as connected before sharing the link.
Related topics: Configure Branding and General Settings, Preview and Publish the Site, View Dashboard Overview.
---
# Shareable Private Link
Source: https://www.hyperdocs.io/docs/publish-customise/shareable-private-link
# Shareable Private Link
A Shareable Private Link lets you share a specific documentation page with anyone using a secret URL — even if that page is not published on your public site. The link is tied to a unique token, so only people who have the URL can open the page. You can revoke the link at any time to cut off access instantly.
## How It Works
When you create a Shareable Private Link for a page, Hyperdocs generates a unique token and attaches it to that page. Anyone who visits the resulting URL can read the page regardless of whether it is live on your public documentation site. The link is per-page — each page has its own independent token. Revoking the link destroys the token, and the URL immediately stops working.
Shareable Private Links also work for translated pages. If you are editing a page in a non-English language, you can generate a separate private link scoped to that translated version without affecting the English page or any other language..
## Use Cases
Shareable Private Links are useful in several situations where you need to give someone access to a page without making it fully public:
- **Early review before publishing** — share a draft page with a teammate, stakeholder, or subject-matter expert so they can review and give feedback before the page goes live on your public site.
- **Customer-specific content** — share a page that covers a feature or configuration relevant only to a specific customer or partner, without exposing it to all visitors.
- **Internal documentation** — keep certain pages off the public site permanently and distribute them only via private links to internal team members.
- **Translation review** — share a translated page with a native-language reviewer before publishing the translation publicly, using the locale-scoped private link.
- **Time-limited access** — share a page temporarily and revoke the link once the review period or need has passed, without having to delete or unpublish the page itself.
## Creating a Shareable Private Link
- Open the documentation editor from your admin dashboard and navigate to the page you want to share.
- Open the share panel for that page. The **Sharable Private Link** section appears inside the panel, showing a description: *Anyone with the link can open this page, even while it's hidden from the public site.*
- Click **Create link**. Hyperdocs generates a unique token and builds the shareable URL for that page.
- The URL appears in a read-only field. Click the field to select the full URL, or click the copy button to the right of the field to copy it to your clipboard.
- Share the copied URL with whoever needs access. They can open the page in any browser without logging in to Hyperdocs.
## Copying the Link
Once a link has been created, the URL is shown in a read-only field in the **Sharable Private Link** section. You can retrieve it at any time by reopening the share panel for that page.
- Click the **copy** button to the right of the URL field to copy the link to your clipboard. The button briefly shows a checkmark to confirm the copy was successful.
- Alternatively, click into the URL field — it selects the full URL automatically — then use your keyboard shortcut to copy.
## Revoking a Shareable Private Link
Revoking a link destroys its token. Anyone who tries to visit the old URL after revocation will no longer be able to access the page. The page itself is not deleted or changed — only the private link is removed.
- Open the share panel for the page that has an active private link.
- Click the **revoke** button (the trash icon) to the right of the URL field.
- The link is removed immediately. The URL field and copy button disappear, and the section returns to its initial state with the **Create link** button.
- If you need to share the page again in the future, click **Create link** to generate a new token. The new URL will be different from the revoked one.
## Shareable Private Links for Translated Pages
If you are working on a translated version of a page, the **Sharable Private Link** section in the share panel generates a link scoped to that specific language. Creating or revoking a private link for a translated page does not affect the English page's link or any other language's link. Each language version of a page has its own independent token.
## Role-Based Access
- **Admins** and **Editors** can create and revoke Shareable Private Links.
- **Viewers** can see the share panel and the active URL if a link already exists, but the **Create link** and revoke buttons are not available to them.
---
# SEO Settings
Source: https://www.hyperdocs.io/docs/publish-customise/marketing/seo-settings
# SEO Settings
The SEO settings area in Hyperdocs has two parts: a global **SEO** panel where you configure site-wide metadata, scripts, and search-engine directives, and a separate **AI & Agents** tab where you control how your documentation is exposed to AI tools and crawlers. Both live under **Marketing** in the admin sidebar.
## Global SEO Panel
The global SEO panel sets defaults that apply across your entire published site. Open it from **Marketing → SEO** in the admin sidebar. Changes take effect on your live site after you click **Save**.
### Open Graph Image
The **Open Graph Image** is the preview image shown when a link to your docs is shared on social platforms or in messaging apps. Upload a custom image by clicking the upload area, or remove the current one with the remove button. If no image is uploaded, the default Hyperdocs favicon is used as the fallback.
### Meta Title
The **Meta Title** field sets the default page title used for pages that do not define their own — for example, the Help Center. If left empty, it falls back to your organization name set in General Settings.
### Meta Description
The **Meta Description** field sets the default description used for pages that do not define their own. If left empty, it falls back to a dash (`-`). Individual documentation pages can override this with their own per-page meta description.
### Head Scripts
The **Head Scripts** field accepts raw HTML injected into the `` of every public page — useful for verification tags, analytics snippets, or other scripts that must load early. Every `` tag, and all HTML tags must be properly closed. An inline validation error appears if the markup is malformed, and the save is blocked until it is corrected.
### Body Scripts
The **Body Scripts** field accepts raw HTML injected into the `` of every public page — suitable for chat widgets, tracking pixels, or other scripts that do not need to be in the head. The same tag-balance validation applies.
### Custom CSS
The **Custom CSS** field accepts raw CSS rules applied to your published site. Do not include `