# Key concepts

> Understand the building blocks of Typemark: projects, pages, typemark.json, repo modes, publishing, and roles.

## Projects

A **project** is one documentation site. Each project has:

- A Git repository, hosted by Typemark or synced with your GitHub
- An address at `{slug}.typemark.dev`, plus your own domain if you add one
- Pages, organized by the navigation in `typemark.json`
- Its own team, with a role for each member

Switch between projects from the project menu at the top of the dashboard sidebar. Each one opens on its **overview**: a box to [ask AI for a change across your docs](https://docs.typemark.dev/editor/ai-writing#from-the-overview), what needs your attention (questions readers couldn't find answered, a failed publish, build warnings), the history of your publishes, your site's address and settings, and the URLs AI tools use to read your docs. On Pro and Enterprise, the overview also shows how many people read your docs over the last seven days, how many Ask AI questions were answered from a page, and your most-read pages.

## Pages

A **page** is an `.mdx` file in the project's repository. The file path becomes the URL:

| File | URL |
|------|-----|
| `introduction.mdx` | `/introduction` |
| `guides/authentication.mdx` | `/guides/authentication` |
| `api-reference/users.mdx` | `/api-reference/users` |

A site in [several languages](https://docs.typemark.dev/configuration/languages) keeps each translation in a folder named after its language code: `fr/introduction.mdx` is the French version of `introduction.mdx`, at `/fr/introduction`.

Each page starts with **frontmatter**, YAML metadata at the top of the file:

```yaml
---
title: "Authentication"
description: "How to authenticate API requests."
icon: "lock-closed"
---
```

The body is **MDX**: Markdown plus components like `<Callout>`, `<Tabs>`, and `<Card>`. In the visual editor, you edit the title and description right at the top of the page. Other frontmatter fields live in [source mode](https://docs.typemark.dev/editor/source-mode).

## typemark.json

Every project has a `typemark.json` file at the root of the repository. It controls:

- **Navigation**: the sidebar structure (tabs, groups, page order)
- **Branding**: primary color, logo
- **Features**: search, theme toggle, table of contents, and more

```json
{
  "name": "Acme Docs",
  "colors": { "primary": "#3b82f6" },
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "groups": [
          {
            "group": "Getting Started",
            "pages": ["introduction", "quickstart"]
          }
        ]
      }
    ]
  },
  "features": {
    "search": true,
    "table_of_contents": true,
    "copy_code_button": true
  }
}
```

You rarely need to edit it by hand. Reordering pages in the editor sidebar and changing **Settings** both update it for you. See [typemark.json](https://docs.typemark.dev/configuration/typemark-json) for the full reference.

<Callout type="info">
  Pages listed in the navigation appear in the sidebar. Pages that aren't listed still open by direct URL.
</Callout>

## Repo modes

Your project's overview shows where its content lives under **Source**.

### Hosted by Typemark (default)

Typemark hosts the Git repository for you. You edit in the web editor, and you don't need a GitHub account.

- Set up automatically when you create a project
- Every save is a Git commit, so your history is always there

### GitHub

Your project syncs with a GitHub repository in both directions:

- Push to GitHub and Typemark pulls the change and rebuilds
- Save in Typemark and the change is pushed to GitHub
- Use the web editor, your local editor, or both

<Callout type="tip">
  You can start hosted and connect GitHub later. Your content comes with you. See [Connecting GitHub](https://docs.typemark.dev/github/connecting).
</Callout>

## Site status and deploy mode

Every project has two publishing controls:

- **Site status** (Live or Offline): whether your address serves your docs or a "coming soon" page. New projects start offline so you can prepare content first.
- **Deploy mode** (Auto-deploy or Manual deploy): whether saves go live right away or wait until you click **Publish**. Auto-deploy is the default.

Both live under **Settings** > **Publishing**. See [Publishing](https://docs.typemark.dev/configuration/publishing) for details.

## Roles

Everyone on a project has a role: **owner**, **editor**, or **viewer**. Editors write and organize pages. Viewers can look but not change anything. Only the owner manages settings, publishing, and the team. See [Team members](https://docs.typemark.dev/team/members).

Plan features follow the project owner's plan. If the owner is on Pro or Enterprise, everyone on the project gets that plan's features there.

## Builds

When content changes, from the editor or a GitHub push, Typemark:

1. Reads `typemark.json` for navigation and settings
2. Compiles your pages from MDX to HTML
3. Highlights code blocks
4. Updates the search index

Saves return right away and the page builds in the background. The editor shows **Building** while it runs and **Build failed** if something goes wrong. Recent publishes are listed on your project's overview.
