Every developer tool needs documentation that helps people understand what it does, get started, and solve real problems.
But creating a documentation site involves more than writing Markdown. You need to organize the content, connect the right repository, configure navigation, and publish a site that other developers can actually use.
In this tutorial, we'll walk through that process using Thally Cloud. By the end, you'll understand how to create a documentation site, connect its source, add content, and verify the published result.
Prerequisites
Before you begin, you'll need:
- A Thally Cloud account.
- A GitHub account.
- Permission to install or approve the Thally GitHub App for the account or organization that will own the documentation repository.
- A project or developer tool you want to document.
You don't need Node.js or a local repository checkout to publish the initial starter site through Thally Cloud. You can create the site through the web interface and edit its source afterward.
If you're new to Thally, keep the official Quickstart open as a reference.
Step 1: Create a site
Open Thally Cloud and sign in.
From your workspace Home page, select Create a site.
Enter the following:
- Site name: A clear name for your documentation.
- Description: A short explanation of what the product does.
-
Site address: The
thally.appaddress you want to use.
Choose a name that makes the site's purpose obvious. For example, documentation for a fictional task-management API could be called TaskFlow Developer Docs.
Thally checks the requested address before you continue. Branding and custom domains can be adjusted later.
Step 2: Choose your documentation repository
Next, decide where the documentation source will live.
Thally's recommended path is Create a new docs repository. Thally creates a GitHub repository from its current verified starter release, provides editable source files, and manages the first deployment.
When installing the Thally GitHub App for this fresh-repository workflow, the official Quickstart instructs you to choose All repositories so the app can initialize the repository it creates.
If your organization requires selected-repository access, use an existing compatible Thally repository and grant the app access to that repository instead.
You can choose Use an existing repository when you already have a compatible Thally project. Make sure the correct GitHub account and repository are selected.
Step 3: Connect product sources
Your documentation repository and your product repository serve different purposes.
The documentation repository contains the pages you publish. A product source contains the actual software that Thally Track watches for merged changes that may affect the documentation.
For example, if you're documenting a developer API, the product source might contain the API implementation, configuration, or SDK.
Select the relevant product repository, or choose I'll do this later if you want to finish the initial site setup first.
The Quickstart notes that the documentation repository is excluded from product sources to prevent update loops.
Step 4: Configure knowledge surfaces
If the Knowledge surfaces step is available in your workspace, you can connect additional repositories containing useful Markdown, MDX, or supported React content.
Knowledge surfaces are review destinations for documentation updates. They are not the same as product sources or separate managed documentation sites.
For a first site, you can skip this step if you don't need it. You can add knowledge surfaces later from Site settings → Knowledge surfaces.
The key is to connect only the sources that make sense for your workflow.
Step 5: Review and publish
Before publishing, review your configuration:
- Site name and address.
- Documentation repository.
- Production branch.
- Product sources, if configured.
- Knowledge surfaces, if configured.
When everything is correct, select Publish site.
Thally saves the setup before starting the background work, so you can return to the workspace Home page to follow the publishing progress.
When the process finishes, the site should appear as Live. Select View live site to open it.
Your published site will have an address in this format:
https://your-site.thally.app
Don't stop at seeing a successful status in the dashboard. Open the URL and verify that the site loads correctly.
Step 6: Add and organize your content
Once the site is published, open the GitHub repository shown in the site summary.
The official Quickstart identifies three files you'll commonly work with:
| File | Purpose |
|---|---|
src/content/*.mdx |
Page content and frontmatter |
docs.json |
Tabs, sidebar groups, page order, and optional features |
src/data/site.ts |
Product name, description, links, and versioned brand defaults |
Start with three essential pages.
Introduction
Explain what the product does, who it's for, and what readers will find in the documentation.
A developer should understand the product's purpose without having to explore the entire codebase.
Quickstart
Help a new user accomplish something useful as quickly as possible.
Depending on the product, this might mean making the first API request, running a command, or completing a basic workflow.
Include prerequisites, the exact steps, an expected result, and a way to troubleshoot common failures.
Practical guide
Choose one task that developers will realistically need to perform.
For example, a guide for a fictional API might explain how to authenticate a request, submit data, handle an error response, and troubleshoot an unsuccessful request.
Use real commands, valid examples, and verified behavior from the product you're documenting. Don't invent endpoints, parameters, or authentication requirements.
Step 7: Validate and publish content updates
Before pushing changes to the production branch, the official Quickstart recommends running:
npx --yes @thallylabs/cli@latest check
npm run build
The first command checks the documentation using the Thally CLI. The second builds the project.
If either command fails, inspect the output and fix the underlying issue before publishing.
Once the changes have been reviewed, push them to the production branch. Thally Cloud builds and publishes the updated version, and the deployment history records the commit.
Finally, revisit the live site and confirm that the updated pages and navigation are correct.
Troubleshooting
The GitHub repository isn't accessible
Check that the repository exists and that you're using the correct GitHub account. Confirm that the Thally GitHub App has the necessary access. Organization policies may require additional approval.
The site doesn't become Live
Return to the workspace Home page and inspect the site's status and deployment history.
A site reservation error and a build failure are different problems. Identify which stage failed before changing your configuration or trying to create another site.
A content update fails validation
Check the command output, content structure, frontmatter, links, and navigation configuration. Fix the reported issue and rerun the validation command.
The local build succeeds, but deployment fails
A successful local build doesn't guarantee that production deployment will succeed. Inspect the production logs, identify the failing stage, and verify the published URL after the deployment completes.
What makes a useful documentation site?
A documentation site is useful when it helps a developer accomplish something, not simply when it contains a large number of pages.
Start with a clear introduction, a reproducible quickstart, and one practical guide. Make sure the examples work, the navigation is understandable, and the published site is accessible.
As the product changes, review the documentation alongside those changes. Thally Track can help identify changes that may require updates and prepare pull requests for review, keeping human verification in the workflow.
Conclusion
Creating a documentation site doesn't have to begin with a complicated setup.
With Thally Cloud, you can create a site, connect a GitHub repository, configure product sources, publish the initial version, and then improve the content through a repository-based workflow.
The most important part is still the writing itself: understand your audience, verify your instructions, and give developers a clear path from their first visit to completing a useful task.
Start small, test the instructions, and let the documentation grow with the product.
Top comments (0)