使用 Thally 建立 Cursor 指南

Think of documentation as the manual that comes with a car. It helps software engineers understand a tool and use it properly.

Whenever I try a new developer tool, the documentation is usually my first stop. After that, I check YouTube videos or articles. If you look closely, many tools with growing developer adoption also have helpful documentation.

In this article, we will build a documentation site with Thally. The site will teach developers how to make and review changes with Cursor.

Note: The Cursor Guide is an independent guide and is not affiliated with the official Cursor documentation. We created it for this article to explore how to build and publish a focused documentation site.

The guide explains what Cursor is, helps a reader make and review one focused change, and shows how to add a reusable project rule.

Let’s get started!

Thally is a platform for creating product and developer-tool documentation. If you’re familiar with tools such as Mintlify or Docusaurus, you already have an idea of how it works.

If not, don’t worry. It is quite easy to set up. 🙂

What we’re building

The guide currently has three public pages:

1. An introduction that explains Cursor and the intended audience.
2. A quickstart for understanding a project and making a reviewed change.
3. A practical guide for creating and troubleshooting a project rule.

We do not need to explain every Cursor feature. We only need to help a new user complete one useful workflow without guessing what to do next.

What you need

To follow the same process, you need:

• a Thally Cloud account
• a GitHub account with permission to connect the Thally GitHub App
• Node.js and Git for local development
• a product or developer tool you know well
• a clear reader and one useful outcome

Start with one clear outcome

Before we created any pages, we wrote down one outcome:

A developer should be able to use Cursor to understand a project, make a focused change, review the diff, and verify the result.

This made it easier to decide what belonged in the guide. The introduction explains the tool, the quickstart helps the reader get their first result, and the project-rules guide gives them something useful to try next.

Create the site with Thally

First, sign up at Thally.io to access Thally Cloud.

After signing in, select Create a new docs repository. Thally will create a GitHub repository from its maintained template and connect it to the publishing workflow.

Next, we selected Check GitHub and authorized Thally Labs to use the GitHub account that would own the repository. Make sure you connect an account where you have permission to create and manage the project.

Thally created Tabintel/cursor from its current starter, connected main as the production branch, and published the first deployment at cursor.thally.app.

Once the first deployment was live, we cloned the new repository:

git clone https://github.com/Tabintel/cursor.git
cd cursor

Add the documentation pages

Thally stores documentation pages under src/content/. We removed the demo content and added these three pages:

src/content/
  introduction.mdx
  quickstart.mdx
  guides/
    project-rules.mdx

Each page needs title and description frontmatter. For the two task pages, we also added what the reader needs, clear steps, a success check, and troubleshooting.

For example, the quickstart tells the reader what they will accomplish before moving into the steps:

---
title: "Make your first reviewed change"
description: "Use Cursor Agent to understand a project, make one focused change, review the diff, and verify the result."
mode: wide
---

After this quickstart, you will have used Cursor Agent to make and verify one small change in a project you control.

Add screenshots with borders and captions

Screenshots make a guide easier to follow because the reader can compare each instruction with the product. We saved ours under public/images/, then added them to the MDX pages with root-relative paths.

Thally's Frame component gives each image a border, a caption, and click-to-zoom behaviour, so we did not need to build a custom image component.

<Frame caption="Review every changed line before keeping the result.">
  <img
    className="aspect-video w-full bg-background object-cover object-top"
    src="/images/cursor/workflow/cursor-review-flow.png"
    alt="Cursor Agent showing a focused request and a proposed diff"
  />
</Frame>

Here, aspect-video gives every screenshot the same 16:9 shape. object-cover object-top fills the space while keeping Cursor's title bar and main controls visible, and w-full lets the image use the available width.

caption is used in the documentation site to tell the reader what to notice. The alt text describes what is shown for readers who use assistive technology or cannot load the image.

Note: object-cover can crop the bottom of a tall screenshot. If every part of the screen must remain visible, use object-contain instead. You may see some empty space around images with a different shape.

Initially, the screenshots inside Thally's numbered <Step> component appeared narrower than the image on the introduction page. This happens because each Step keeps some space for its number and connecting line.

To give the screenshots more room on a wide task page, we added a small responsive wrapper:

<div className="md:-ml-[50px] md:w-[calc(100%+50px)]">
  <Frame caption="Cursor Agent explains the project and cites the files behind its answer.">
    <img
      className="aspect-video w-full bg-background object-cover object-top"
      src="/images/cursor/workflow/cursor-agent-explanation.png"
      alt="Cursor Agent answering an evidence-based project explanation prompt"
    />
  </Frame>
</div>

The extra width only applies from the medium breakpoint, so the screenshot still fits naturally on phones. We also added mode: wide to the page frontmatter. This removes the right-side contents rail and gives the task more room without making the paragraphs difficult to read.

Keep the navigation simple

Next, we added the three pages to docs.json. We kept the navigation short and organised it around what the reader wants to do:

{
  "tabs": [
    {
      "tab": "Cursor Guide",
      "groups": [
        {
          "group": "Start here",
          "pages": ["introduction", "quickstart"]
        },
        {
          "group": "Practical guides",
          "pages": ["guides/project-rules"]
        }
      ]
    }
  ]
}

Now the reader can start with the introduction, complete the quickstart, and move to the practical guide without searching through a long sidebar.

Using Cursor as the visual reference

For the guide to feel familiar to a Cursor user, you can study the current Cursor documentation to understand the themes.

These are the main colours we used as a reference:

Cursor uses Cursor Sans and Berkeley Mono, but those fonts are not included in this project. We used Inter for the text and kept Thally's code font.

Add the theme and fonts

Thally lets us control the site's appearance through docs.json, src/data/site.ts, and the Branding settings in Thally Cloud.

We selected the sharp theme because its 4px corners are close to Cursor's current interface. We also set Inter as the reading font and kept the light and dark mode toggle:

{
  "theme": "sharp",
  "appearance": {
    "default": "system",
    "showToggle": true,
    "contentIcons": "accent"
  },
  "fonts": {
    "body": {
      "family": "Inter",
      "weight": ["400", "500", "600"]
    },
    "heading": {
      "family": "Inter",
      "weight": ["400", "500", "600"]
    }
  }
}

Fix the homepage title without changing Thally's runtime

Here is one small problem we ran into: Thally's built-in Hero limits headings to 17ch. Our homepage title wrapped onto two lines even when there was enough room on a wide screen.

We could have edited the built-in component, but that file belongs to Thally's runtime and may be replaced during a future sync. Instead, we registered our own Hero in src/mdx/custom-components.tsx, the customer-owned file Thally provides for custom components:

export const customComponents: MDXComponents = {
  Hero: CursorHero,
}

Our Hero removes the narrow title limit and uses xl:whitespace-nowrap only on large desktop screens. On phones and tablets, the title can still wrap naturally.

Before changing any part of a Thally site, it helps to know which file owns it:

Add the Cursor logo and favicon

We saved the light and dark Cursor marks under public/brand/:

public/brand/
  cursor-light.svg
  cursor-dark.svg

Then we connected them to the logo and favicon settings in docs.json:

{
  "favicon": {
    "light": "/brand/cursor-light.svg",
    "dark": "/brand/cursor-dark.svg"
  },
  "navbar": {
    "logo": {
      "light": "/brand/cursor-light.svg",
      "dark": "/brand/cursor-dark.svg",
      "showTitle": true
    }
  }
}

Because this is not Cursor's official documentation, we kept the independent-guide note visible in the introduction and repository.

Including the light and dark colours for the documentation

Next, we added the brand colours to src/data/site.ts so they remain part of the repository. Here is the dark configuration:

dark: {
  background: '#14120B',
  card: '#1B1913',
  foreground: '#EDECEC',
  muted: '#1B1913',
  mutedForeground: '#A9A79F',
  border: '#2A2822',
  accent: '#EDECEC',
  accentForeground: '#14120B',
  input: '#1B1913',
  sidebar: '#14120B',
  ring: '#EDECEC',
  sidebarActiveBg: '45 17% 11%',
  sidebarActiveText: '#EDECEC'
}

We kept the accent colours neutral because Cursor's documentation does not use a bright colour for every active state.

We did not want the project-rule guide to end with a code sample that nobody had tested. We opened the rule in Cursor and checked the file patterns that control where it applies.

Then we created a temporary practice page and asked Cursor to update only that file. This let us confirm that Cursor found the rule, followed the instructions, and left the change for us to review. Once the test worked, we removed the practice page because it was never meant to be published.

Check the site before publishing

Before we published anything, we ran the checks required by the repository:

npm ci --ignore-scripts --prefix .github/thally-tooling
.github/thally-tooling/node_modules/.bin/thally check --ci .
npm test
npm run build

The content check returned no errors or warnings. All 1,673 tests passed, and the production build completed successfully.

The commands were only part of the check. We also opened the local preview and used the site like a reader. We checked the homepage, quickstart, screenshots, code blocks, internal links, and both colour themes.

Publish and check the live site

Once everything passed locally, we committed the changes and pushed them to main, the production branch connected to Thally Cloud. That push started a new deployment.

When the deployment finished, we checked three things:

1. The deployment commit matches the commit we pushed.
2. The homepage contains the Cursor Guide content instead of the starter pages.
3. The live site uses the expected colours, logo, navigation, and page links in both themes.

A successful status is good, but it does not always mean the live site contains the exact revision you expected. That is why we checked the commit and the site itself.

Next steps

Now we have built and published a documentation site with Thally. We started with a simple idea, turned it into three focused pages, added Cursor-inspired branding, tested the instructions, and published the guide.

You can explore the Cursor Guide, make updates to the documentation, or use the source repository as a reference for your own project.

If you have a product or developer tool you want to document, try Thally and build your own documentation site. Start small, choose one useful outcome for your reader, and grow the guide as you learn what they need.

Cursor names, marks, and visual references belong to Cursor and Anysphere. This project uses them only to identify the documented product and remains an independent guide.