Key concepts
Understand the building blocks of Typemark: projects, pages, typemark.json, repo modes, publishing, and roles.
Actualizado el 19 nov 20263 min de lectura
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, 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 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:
---
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.
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
{
"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 for the full reference.
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
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 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.
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:
- Reads
typemark.jsonfor navigation and settings - Compiles your pages from MDX to HTML
- Highlights code blocks
- 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.