如何使用 Thally 建立並發佈產品文件網站

Most product docs start well and then go out of date. The code changes, and nobody updates the pages.

Thally is a docs platform that tries to fix this. It hosts your docs from a Git repository, and it watches your product repository. When a pull request merges, Thally checks which pages the change affects and opens a pull request in your docs repository for you to review.

In this article, you will build a docs site with Thally from start to finish. The example is a real site: the docs for tweakcn, a visual theme editor for shadcn/ui. You will see each screen of the setup, the files you edit, the commands you run, and the problems I had and how I fixed them.

Prerequisites

You need these before you start:

A GitHub account. Thally stores your docs in a GitHub repository.
A product repository on GitHub. Thally watches this repository for changes. For this article, I used my fork of tweakcn, tonyedgal/tweakcn.
Node.js 22 or later and npm. You use them to run the site on your computer.
Git, and basic knowledge of clone, commit, and push.
Basic Markdown. Thally pages are MDX: Markdown with React components.

You do not need to know Next.js. The Thally template is a Next.js app, but you edit only content and configuration files.

What You Will Build

At the end, you will have:

A live docs site at a thally.app address.
A private GitHub repository that holds the site.
Track, the Thally service that suggests doc updates when your product changes.

Step 1: Create Your Thally Account

Go to app.thally.io. Sign in with GitHub, Google, or email. GitHub is the best choice, because Thally needs GitHub access later.

After you sign in, the dashboard opens. The button at the top right is Create a site.

Step 2: Create the Site in Thally Cloud

Select Create a site. The setup has five steps. You can go back to a step before you publish.

Site details

Enter three values:

Site name: the product name. I used tweakcn.
Summary: one line about the docs. I used "Guides for theming shadcn/ui apps with the tweakcn visual theme editor."
Address: the thally.app subdomain. Thally checks if the address is free while you type.

Docs source

Select Create a new docs repository. Thally makes a private repository from its template. You can also import a public docs URL or use an existing repository.

Choose the GitHub account and the repository name. Thally checks that the name is free. I could not use tweakcn, because my fork of the product already has that name, so I used tweakcn-docs.

Select Connect GitHub. GitHub asks you to install the Thally GitHub App. To create a new repository, the app needs access to All repositories. With Only select repositories, Thally cannot create the new one.

Product sources

Select the repositories that define your product. Track watches these repositories. The docs repository is not in the list, because Track does not watch itself.

The list shows only the repositories that the Thally GitHub App can read. My fork tonyedgal/tweakcn was not in the list at first:

Select Add repositories. GitHub asks you to confirm access. Give the Thally GitHub App access to the repository, then go back to Thally. The repository is now in the list. Select it.

Knowledge surfaces

Knowledge surfaces are other repositories that Track can update, for example a marketing site or a help center. This step is optional. For a first site, select Skip for now.

Review and publish

Check the summary, then select Publish site. Thally does these things:

Creates the private docs repository from the template.
Deploys the site to your thally.app address.
Starts Track on your product sources.
Starts a 7-day trial.

The dashboard shows Waiting to publish with a progress bar, and the site shows Publishing. When the publish is done, the site shows Live, and the dashboard shows an agent readiness score. For tweakcn, the site was live about one minute after I selected Publish site.

The dashboard also shows Generate docs. This option reads your product repository and opens one pull request with draft pages. Use it when you want a first draft to edit. Skip it when you already have content to add.

Step 3: Clone the Docs Repository

Clone the new repository and install the dependencies:

git clone https://github.com/<your-account>/<docs-repo>.git
cd <docs-repo>
npm ci
npm run dev

Open http://localhost:3000. You see the starter pages from the template.

The parts of the repository that you use:

docs.json              # Tabs, groups, and page order
src/content/           # Pages, as .mdx files
src/data/site.ts       # Site name, links, and brand colors
public/                # Images and other static files
AGENTS.md              # Lists the files that Thally owns

Step 4: Configure the Site

Site identity in site.ts

src/data/site.ts holds the site name, the summary, the header links, and the brand colors. Change the name, the summary, and the links at the end of the file:

export const siteConfig: SiteConfig = {
  ...templateSiteConfig,
  name: "tweakcn",
  description: "Guides for theming shadcn/ui apps with the tweakcn visual theme editor.",
  repoUrl: "https://github.com/tonyedgal/tweakcn-docs",
  links: [
    { label: "Get started", href: "/quickstart" },
    { label: "tweakcn editor", href: "https://tweakcn.com/editor/theme" },
  ],
}

For tweakcn, I kept the Thally template colors. To use your own colors, see Bringing over my design system.

Navigation in docs.json

docs.json defines the tabs, the groups in each tab, and the pages in each group. A page name is the file path in src/content without .mdx. Group pages by what the reader wants to do, for example "Get started" or "Import and export".

{
  "navbar": {
    "primary": { "label": "Open the editor", "href": "https://tweakcn.com/editor/theme" }
  },
  "tabs": [
    {
      "tab": "Docs",
      "groups": [
        { "group": "Get started", "pages": ["introduction", "quickstart"] },
        { "group": "Themes", "pages": ["themes/presets", "themes/modify-a-theme"] }
      ]
    },
    {
      "tab": "Guides",
      "groups": [
        { "group": "Overview", "pages": ["guides/overview"] },
        { "group": "Import and export", "pages": ["guides/import-a-theme", "guides/export-a-theme"] }
      ]
    }
  ]
}

navbar.primary sets the button at the top right of each page.

Tip: Do not name a page index.mdx in a folder. The check reads guides/index.mdx as the page guides and reports it as an orphan. Use a name such as guides/overview.mdx.

Files you must not edit

AGENTS.md lists the files that Thally owns, for example src/styles/** and some files in src/lib. Thally changes those files when it updates the template. If you edit them, Thally can overwrite your change.

Step 5: Write Pages with Thally Components

Page frontmatter

Each page starts with a title and a description:

---
title: "Modify a theme"
description: "Change the colors, fonts, radius, spacing, and shadows of a tweakcn theme for light and dark mode."
---

The description shows under the title, in search results, and in the Markdown version of the page that AI tools read.

The home page

Add mode: home to the frontmatter of the first page. A home page uses a <Hero> at the top and card groups that link to the other pages:

---
title: Introduction
description: Design a shadcn/ui theme in the browser, then install it with one command.
mode: home
---

<Hero
  title="Theme your shadcn/ui app in minutes"
  subtitle="tweakcn is a visual editor for shadcn/ui themes."
  primaryLabel="Install your first theme"
  primaryHref="/quickstart"
/>

## Build your theme

<CardGroup cols="2">
  <Card title="Use a preset" icon="palette" href="/themes/presets">
    Start from one of 42 built-in themes.
  </Card>
</CardGroup>

Use the built-in components

Thally includes components for task pages. You do not import them. Use them directly in MDX.

Steps number a sequence of actions:

<Steps>
<Step title="Install the theme">

```bash
npx shadcn@latest add https://tweakcn.com/r/themes/modern-minimal.json
```

</Step>
</Steps>

Note shows a warning or extra information. Use type="warning" or type="info":

<Note type="warning" title="Fonts are not loaded">
The theme names Inter but does not load it.
</Note>

Tabs show the same step for different tools:

<Tabs>
<Tab title="npm">

```bash
npx shadcn@latest add https://tweakcn.com/r/themes/claude.json
```

</Tab>
<Tab title="pnpm">

```bash
pnpm dlx shadcn@latest add https://tweakcn.com/r/themes/claude.json
```

</Tab>
</Tabs>

Images

Put images in public/images. Wrap each image in <Frame> to add a border and a caption. Readers can select the image to zoom in.

<Frame caption="The Theme Code dialog. The command at the top installs the theme.">
![Theme Code dialog with the shadcn add command](/images/code-panel.png)
</Frame>

Links

Link to another page with its site path, the same as its name in docs.json:

See [Load the theme fonts](/guides/load-theme-fonts).

The check in the next step finds links to pages that do not exist.

Step 6: Check the Site Before You Publish

Run these commands in the docs repository:

npx --yes @thallylabs/cli@latest check
npm run typecheck
npm run build

check finds broken links, pages that are not in docs.json, and bad frontmatter.
typecheck and build find MDX errors.

Then run npm run dev and open each page. Check that the components, images, and navigation show correctly in light and dark mode.

Step 7: Publish and Verify

Commit and push to main:

git add docs.json src/content public/images src/data/site.ts
git commit -m "docs: add tweakcn guides"
git push origin main

Thally deploys each push to main. The Deployments page shows the new deployment.

Open the live URL and check three pages: the home page, the quickstart, and one guide.

From now on, Track reads the pull requests that merge in your product repository. When a change affects a page, Track opens a pull request in the docs repository. You review it and merge it, the same as a code change.

Obstacles and How I Resolved Them

Bringing over my design system

Before tweakcn, I built a Thally site for my own library, UI-Theme (uitheme.thally.app). I wanted the docs to use the same design system as the UI-Theme website.

The problem: the UI-Theme website uses Tailwind CSS v4, with colors as oklch CSS variables in global.css. The Thally template uses Tailwind CSS 3.4. It reads brand colors only as hex values in src/data/site.ts, and src/styles/** is owned by Thally. I could not import global.css.

The fix:

I listed the tokens in the website global.css: background, foreground, card, muted, border, primary, and ring, for light and dark mode.
I converted each oklch value to an sRGB hex value.
I mapped each token to a slot in the brandPresets.primary palette in site.ts:

Website token	Thally slot
`--background`	`background`, `sidebar`
`--card`	`card`
`--foreground`	`foreground`
`--muted`, `--muted-foreground`	`muted`, `mutedForeground`
`--border`, `--input`	`border`, `input`
`--primary-ink`	`accent`
`--primary`	`ring`

Then I ran npm run build and compared the docs with the website in both modes.

primary: {
  light: {
    background: '#FCFCFC',
    foreground: '#171717',
    muted: '#EDEDED',
    border: '#DFDFDF',
    accent: '#007F46',
    accentForeground: '#FFFFFF',
    ring: '#72E3AD',
    // ...
  },
  dark: {
    background: '#121212',
    foreground: '#E2E8F0',
    accent: '#50D492',
    ring: '#4ADE80',
    // ...
  },
},

The website uses a light mint --primary. For text links on a near-white page, that color has too little contrast. I used the darker --primary-ink as the Thally accent, and I kept the mint color for the focus ring.

What I could not bring over: Thally has no slot for the primary button fill, so buttons use the accent color. Fonts, radius, and shadows stay with the template.

Conclusion

You now have a docs site that lives in Git, deploys on each push, and gets update suggestions when your product changes. You created the site in Thally Cloud, connected the product repository for Track, set the identity and navigation, wrote pages with the built-in components, checked the site, and published it with a push to main.

The tweakcn docs are live at tweakcn.thally.app, and the source is at github.com/tonyedgal/tweakcn-docs. The UI-Theme docs are live at uitheme.thally.app, and the source is at github.com/tonyedgal/ui-theme-docs.