# Author Guide

This guide is for people who want to publish documentation to a
Docroot instance via the web UI.

---

## Prerequisites

- An account with **write** access to the target namespace.
- A ZIP archive of your documentation.

---

## 1. Prepare Your Archive

The ZIP file must contain `index.html` at the **archive root**.
That is the only hard requirement.

A minimal archive:

```
docs.zip
└── index.html
```

---

## 2. Log In

Click **Login** in the top-right toolbar and authenticate with
your identity provider.  Write-access controls appear once you
are logged in.

---

## 3. Create a Namespace (first time only)

On the home page click **New namespace** and enter a name.

Two visibility flags control access:

- **Browsable** (default: on) — the namespace and its
  projects appear in the listing for everyone.  Visitors
  still need appropriate permission to open the
  documentation itself.
- **Public read** — anyone can browse, open, and read the
  documentation without logging in.  Enable this for fully
  public documentation.

---

## 4. Create a Project (first time only)

Navigate into the namespace and click **New project**.

---

## 5. Upload a Version

1. Navigate into the project.
2. Click **Upload**.
3. Select your ZIP file.
4. Enter the version string (e.g. `1.0.0` or `main`).
5. Select the locale (e.g. `en`).
6. Optionally enter a **Ref / tag** name (e.g. `latest`) to
   attach a named pointer to this version.  Leave the field
   blank to upload without any ref.
7. Click **Upload**.

The version appears in the list once processing completes.

---

## Refs (Tags)

A **ref** is a named pointer to a specific version, similar to
a git tag or a Docker tag.  Refs are stored in the project's
`refs/` directory as symlinks.

- Any ref name is valid.  `latest` is a conventional name
  with no special meaning beyond convention.
- Multiple refs can point to the same version.
- Refs can be created, updated, or deleted independently of
  the version through the **Manage refs** button (tag icon)
  on any version row.
- A visitor who navigates to a project using a ref URL
  (e.g. `.../ref/latest/en/`) is served the documentation
  for whichever version the ref currently points to.
- If a version is deleted while a ref still points to it,
  the ref is kept but returns a 404 until reassigned.