# Docs overview

EvoHub Docs publishes your product documentation as a site of its own, on your own domain. You write pages in Markdown in the EvoHub console (or in a GitHub repository), arrange them into sections, and publish them when they are ready. This documentation is itself an EvoHub Docs site.

The Docs console lives at [https://evohub.io/docs-admin](https://evohub.io/docs-admin).

## How a site is organized

| Concept | What it is |
| --- | --- |
| **Docs site** | One documentation site, with its own name, logo, theme, domain and settings. |
| **Version** | A content space of the site, such as `v1` and `v2`. Every site starts with one version, and most sites never need more. |
| **Section** | A heading in the navigation that groups pages. Sections have no content of their own. |
| **Page** | One Markdown document. A page sits in a section or at the top level. |
| **API reference** | An OpenAPI document rendered as reference pages. See [API references and AI](https://docs-dev.evohub.io/api-references-and-ai.md). |
| **Snippet** | Reusable Markdown included in pages with `{{snippet:name}}`. See [Writing pages](https://docs-dev.evohub.io/writing-pages.md). |

A site can belong to the whole organization or to one team. A team site is visible only to that team and to organization Admins and Owners.

## Who can do what

Docs has no per-site members or roles. What you can do on every docs site of your organization comes from your organization role:

| Permission | Lets you |
| --- | --- |
| `docs:site:read` | Open sites, pages, drafts, history and analytics. |
| `docs:page:write` | Write and edit pages, sections, snippets, API references and files; open change requests. |
| `docs:page:publish` | Publish and unpublish, approve and merge change requests, roll back. |
| `docs:site:write` | Create sites and change their settings: domain, theme, navigation, review, access, GitHub. |
| `docs:site:delete` | Delete a whole site. |

Members get everything except deleting a site; Viewers can read. Deleting a site is for Admins. To split the work, build a custom role from the **Docs writer**, **Docs reviewer** or **Manages docs sites** presets. See [Roles and permissions](https://docs-dev.evohub.io/roles-and-permissions.md).

## Create a site

:::steps
### Open Docs
In the EvoHub console, open **Docs**. The **Docs sites** page lists every site you can reach.

### Create the site
Choose **New site**, give it a **Name** and an **Address**, and select **Create site**. The address is a short identifier (lowercase letters, digits and hyphens) that is unique across EvoHub. It names the site in the console and the API; it is not a web address.

You can also start with **From template** or bring existing docs in with **Import**. See [Import and export](https://docs-dev.evohub.io/import-and-export.md).

### Add pages
In the site editor, add sections and pages from the navigation tree on the left. New pages start as drafts.

### Publish
Publish each page when it is ready, then turn on **Published** for the whole site in **Settings**.

### Connect a domain
A site answers only on its own domain. Until you connect one, use **Preview** in the console. See [Connect a custom domain](https://docs-dev.evohub.io/docs-custom-domain.md).
:::

## Drafts and publishing

Every page has two copies:

- The **draft** is what you edit. **Save draft** stores your changes without showing them to anyone.
- The **live copy** is what readers see. **Publish** (or **Publish changes** for a page that is already live) copies the draft to the live copy.

Editing a published page changes nothing on the site until you publish again. The editor marks a page with **Unpublished changes** while the two copies differ. **Unpublish** takes a page off the site and keeps its draft.

Two things must be true before a reader sees a page: the page is published, and the site itself is **Published** (in **Settings**, **General**). A site that is not published is visible only to your organization.

If the site requires review, pages go live only through an approved change request. See [Review and change requests](https://docs-dev.evohub.io/review-and-change-requests.md).

### Editing together

The editor shows when someone else is editing the same page. If two people save the same page, the second save is stopped and you choose to keep your version, take theirs, or copy what you need across. Nothing is overwritten silently.

## Revisions and rollback

Every publish is kept as a revision; the newest 50 per page are kept. Open the page's publish history to see them. For each revision you can:

- **Restore** — copy that version into the draft. It does not publish.
- **Roll back** — make that version live again right away. On a site that requires review, a rollback opens a change request instead.

A rollback refuses to overwrite draft work that was never published unless you confirm that you want to discard it.

## Navigation

The editor's navigation tree sets the order readers see: move pages and sections up and down, rename sections, and move pages between sections. Deleting a section never deletes pages; its pages move to the top level.

Under **Settings**, **Navigation** you shape the rest of the site:

- **Tabs** across the top, each showing some sections or linking somewhere else.
- **Header** links and an optional highlighted button.
- **Footer** columns of links and social links.
- **Section icons** shown before each section title.
- **Page footer**: show **Last updated** and an **Edit this page** link built from a template such as `https://github.com/acme/docs/edit/main/{slug}.md`.
- **Home page**: the **First page**, **A chosen page**, or a **Landing page** with a headline, subtitle, button and cards.

Navigation and theme changes apply to the live site as soon as you save them.

Each page also has its own settings (the settings button in the editor): SEO title, description, link preview image, canonical address, **Hide from search engines**, **Sidebar title**, icon and **Hide from navigation**. Page settings go live when the page is published.

## Theme

**Settings**, **Theme** sets fonts (loaded from Google Fonts only when you pick one), the accent colour, corner radius, background, code theme, colour scheme (follow the reader's device, or always light or dark) and favicon. The logo is under **Settings**, **General** (PNG, JPEG or WebP, up to 2 MB).

## Versions

A version is a separate set of sections, pages, snippets, API references and redirects. The logo, theme, layout, domain, files and languages are shared by every version. Manage them in **Settings**, **Versions**:

- **New version** creates an empty version or a copy of an existing one.
- **Make default** chooses which version the short addresses (`/page`) show. Other versions live under `/<version>/page`.
- Each version can be published or not, tagged (for example **Latest** or **LTS**), marked **Deprecated** with a banner that points readers to the default version, or hidden from search engines.

A site holds up to 20 versions. Readers switch versions from the site's version switcher.

## Languages

Pages are written in the site's default language first. In **Settings**, **Languages** add up to 10 other languages; each page can then be translated in the editor's language tabs. A translation keeps its page's address under a language prefix (`/de/page`) and its place in the navigation, and is published like any other page.

The **Translations** page shows, for every page, which languages are missing, outdated (the source changed since) or up to date. For untranslated pages, choose to **Show the default language with a note** or **Hide untranslated pages**. Under **Interface text** you can reword the site's own labels, such as "On this page", per language.

EvoHub does not currently translate pages automatically; translations are written by people.

## Other site tools

- **Assets** — images, PDFs and icons uploaded to the site. See [Writing pages](https://docs-dev.evohub.io/writing-pages.md#files-and-images).
- **Redirects** — keep old links working. A redirect applies only where no page answers. Moving a published page adds one automatically.
- **Link health** — finds broken links on the published site. Links are checked after every publish; **Check now** runs it on demand, optionally including external links.
- **Activity** — who changed what on the site.
- **Notifications** — review requests and replies on your change requests.

## Delete a site

**Settings**, **General**, **Delete site** removes the site with every page and revision. Only Admins (or a custom role with `docs:site:delete`) can do this. Download an export first if you want a copy. See [Import and export](https://docs-dev.evohub.io/import-and-export.md).

## Billing

Docs is billed by usage, not per seat: any number of people can write and review. See [How billing works](https://docs-dev.evohub.io/how-billing-works.md) for what is metered.

## Related

- [Writing pages](https://docs-dev.evohub.io/writing-pages.md)
- [Review and change requests](https://docs-dev.evohub.io/review-and-change-requests.md)
- [Connect a custom domain](https://docs-dev.evohub.io/docs-custom-domain.md)
- [Docs as code with GitHub](https://docs-dev.evohub.io/github-sync.md)