How to Build and Publish a Documentation Site with Thally

You find a promising open-source library and open its documentation to see whether it will work for your project. The installation instructions look straightforward until a required configuration step is missing. You try the example, hit another error, and end up searching GitHub issues for something the documentation should have explained.

When you're writing documentation for your own project, developers should be able to follow your instructions and run the examples without searching elsewhere for missing steps. You also need a way to organize your documentation and publish updates as your project changes.

We built Thally to address that. It lets you create a documentation site with MDX, configure its navigation, preview changes locally, and publish from GitHub.

In this tutorial, you'll build and publish a documentation site with Thally.

Prerequisites

Before creating your Thally documentation site, you'll need:

• Node.js 22.14 or later and npm: To run the Thally project and manage its dependencies. The starter also supports Node.js 20.19+.
• Git: To track changes to your documentation and push them to GitHub.
• A GitHub account: To host your documentation repository and connect it to Thally Cloud.
• An IDE or code editor: Use your preferred editor, such as VS Code, Cursor, or IntelliJ IDEA, to work with MDX and configuration files.
• A project to document: For this tutorial, we'll build documentation for Page Metadata Inspector, a Python CLI that extracts metadata from web pages.

Set up your Thally documentation project

You can create a Thally documentation site using its project starter, which includes a Next.js application and sample documentation pages.

Open your terminal, navigate to the directory where you want to create your documentation project, and run:

npx create-thally-docs page-metadata-inspector-docs

The command creates a new page-metadata-inspector-docs directory. Move into that directory and start the development server:

cd page-metadata-inspector-docs
npm run dev

Open http://localhost:3040 in your browser to view the starter site.

The starter includes example documentation that we won't need for this project. Open src/content/ in your IDE or code editor and remove the sample pages for API authentication, changelogs, components, customization, and the starter guides. Keep introduction.mdx and quickstart.mdx, since we'll replace their contents and update the navigation configuration in the next steps.

After cleaning up the sample content, these are the main files and directories we'll work with:

page-metadata-inspector-docs/
├── docs.json
├── package.json
├── src/
│   ├── content/
│   │   ├── introduction.mdx
│   │   └── quickstart.mdx
│   └── data/
│       └── site.ts
└── public/

Keep the other files generated by Thally.

Your documentation pages live in src/content/. You'll configure their navigation in docs.json and can also update the site's name and links in src/data/site.ts.

Configure your documentation site

Thally reads docs.json to determine how your documentation pages appear in the sidebar. For this tutorial, we'll group the introduction and quickstart under Getting started, with a separate Guides section for the practical walkthrough.

Open docs.json in your project's root directory and replace the starter configuration with:

{
  "theme": "default",
  "appearance": {
    "contentIcons": "accent"
  },
  "markdown": {
    "enabled": true
  },
  "i18n": {
    "defaultLocale": "en",
    "locales": [
      {
        "code": "en",
        "label": "English"
      }
    ]
  },
  "navbar": {
    "primary": {
      "label": "Get started",
      "href": "/quickstart"
    }
  },
  "tabs": [
    {
      "tab": "Documentation",
      "groups": [
        {
          "group": "Getting started",
          "pages": ["introduction", "quickstart"]
        },
        {
          "group": "Guides",
          "pages": ["guides/inspect-metadata"]
        }
      ]
    }
  ],
  "ai": {
    "chat": true
  }
}

The tabs property defines the navigation groups, while each entry in pages points to an MDX file under src/content/, without the .mdx extension. For example, guides/inspect-metadata maps to src/content/guides/inspect-metadata.mdx.

Create your documentation pages

Thally uses MDX for documentation pages, so you can write content using Markdown syntax.

Write the introduction

Your introduction should explain what the project does and its limitations so developers can decide whether it fits their use case.

Open src/content/introduction.mdx and replace the starter content with:

---
title: "Introduction"
description: "Learn what Page Metadata Inspector does and when to use it."
---

Page Metadata Inspector is a Python CLI that retrieves metadata
from web pages and returns the results as JSON.

It extracts the page title, meta description, canonical URL,
and Open Graph title.

## How it works

The inspector requests a URL and parses the HTML response.
It doesn't execute JavaScript, so metadata added after the page
loads won't appear in its output.

To inspect your first page, follow the [Quickstart](/quickstart).

Add the quickstart

The quickstart should give developers everything they need for their first successful run.

Open src/content/quickstart.mdx and replace its content with:

---
title: Quickstart
description: Run your first metadata inspection.
---

## Prerequisites

- Python 3.10 or later
- Git
- An internet connection

## Install and run

Clone the application repository:

```bash
git clone https://github.com/oyedeletemitope/page-metadata-inspector.git
cd page-metadata-inspector
```

Run the inspector:

```bash
python3 inspector.py https://example.com
```

The command returns the page metadata as JSON. Fields that
aren't present in the retrieved HTML have a value of `null`.

For a local example, continue to the
[Inspect metadata changes](/guides/inspect-metadata) guide.

Create a practical guide

We'll use two HTML fixtures from the Page Metadata Inspector project to demonstrate a metadata comparison. Because the files are stored in the repository, readers can reproduce the example without depending on a public site's metadata.

Create src/content/guides/inspect-metadata.mdx and add:

---
title: Inspect metadata changes
description: Compare metadata before and after editing a local HTML page.
---

Compare the metadata returned by Page Metadata Inspector
before and after updating an HTML page.

## Start a local server

From the Page Metadata Inspector project directory,
copy the first HTML fixture into the directory the server
will serve:

```bash
cp examples/before.html examples/site/index.html
python3 -m http.server 8765 --bind 127.0.0.1 --directory examples/site
```

Keep the server running. Open another terminal in the
same project directory and save the first result:

```bash
python3 inspector.py http://127.0.0.1:8765/ > before.json
```

## Compare the changes

Replace the served HTML with the updated fixture and
save another result:

```bash
cp examples/after.html examples/site/index.html
python3 inspector.py http://127.0.0.1:8765/ > after.json
diff -u before.json after.json
```
The comparison shows changes to the page title, meta
description, and Open Graph title. The canonical URL
remains unchanged.

If the server doesn't respond, check that it's still
running on port 8765. If another application is using
that port, stop it or choose another port in both the
server and inspector commands.

Save the three MDX files and open http://localhost:3040 in your browser to preview your documentation site. Check that the introduction, quickstart, and practical guide appear under the navigation groups you configured in docs.json, and that their links work.

If your changes don't appear, restart the development server by running npm run dev from your documentation project's root directory.

Test your documentation site locally

Before publishing, run a production build to check whether Next.js can compile your documentation pages, resolve their dependencies, and generate the expected routes. This can catch errors that might prevent pages from rendering after deployment.

From your documentation project's root directory, run:

npm run build

The build output will show whether compilation succeeded or identify errors you need to fix.

You can also check your documentation for content and navigation issues:

npm run check

Publish your documentation site with Thally Cloud

You can publish your documentation through Thally Cloud by connecting the GitHub repository containing your project.

Push your project to GitHub

Create a new public repository on GitHub without initializing it with a README or .gitignore, since your Thally project already contains these files.

From your project's root directory, stage your changes and review the files before committing.

git add .
git status --short

Check that local files such as .env.local aren't included. Once you've reviewed the staged files, commit your changes:

git commit -m "docs: add initial documentation"

Connect your local project to the GitHub repository. Replace YOUR_USERNAME with your GitHub username in the following command:

git remote add origin https://github.com/YOUR_USERNAME/page-metadata-inspector-docs.git
git push -u origin HEAD

Deploy through Thally Cloud

Open Thally Cloud and sign in or create an account if you’re new. From your dashboard click Create a site. You’ll be redirected to where to fill in basic information about the site. During site creation, choose Use an existing repository to publish the project you just pushed.

Connect your GitHub account and grant the Thally GitHub App access to the documentation repository. You can select Only select repositories during installation to limit its access.

Answer the additional setup questions according to your project's needs, or choose Skip for now for optional features you don't need.
Select your documentation repository, review the site details, and click Publish site. Once publishing finishes, return to the workspace Home page and click View live site to open your documentation at https://your-site.thally.app/.

Congratulations, your documentation site is now live:

Troubleshooting common issues

The site still displays the old project name

Renaming your project directory or changing the name field in package.json doesn't update the name shown on the documentation site.

Thally stores the displayed site name separately in src/data/site.ts. Open that file and update the name and description fields inside the exported siteConfig object.

Page titles appear twice

If a documentation page displays the same heading twice, check whether you've added an H1 that repeats the title field in the MDX frontmatter.

Thally can render the frontmatter title automatically. Remove the duplicate H1 and keep the heading structure for the remaining content.

Navigation links don't open the expected pages

If a page is missing from the sidebar or its link doesn't work, compare the page's location under src/content/ with its entry in docs.json.

For example, a navigation entry of guides/inspect-metadata should point to src/content/guides/inspect-metadata.mdx.

Also check that you haven't left references to sample pages you removed during cleanup.

Conclusion

Your documentation site is published, and you can continue updating its content through GitHub as your project changes. You can explore the complete implementation in the Page Metadata Inspector documentation repository.

For additional configuration options and features, check out the official Thally documentation.