DEV Community

Cover image for Why I Ditched Traditional Docs Tools to Build a Site with Thally
Michael Uzukwu
Michael Uzukwu

Posted on

Why I Ditched Traditional Docs Tools to Build a Site with Thally

#documentation #devtool #cicd #nextjs

If you maintain a developer tool or API, you know the pain of documentation drift. When the code changes, the docs fall behind. I recently built a documentation site for my open-source tool, api2md, using Thally.

Thally is a product knowledge layer for software teams. It does not just host your docs; it watches your product repositories and updates the docs when the code changes.

Here is why I chose Thally, how I built the site step by step, and the friction I hit along the way.

What Thally Is Doing Right

I have used Docusaurus, Hugo, and Astro Starlight. They are excellent static site generators, but they do not solve the sync problem. Thally stood out for a few reasons:

  • GitHub-native: Your content stays in Git. There is no proprietary CMS or lock-in.
  • Track feature: You connect your product repository, and Thally opens draft PRs in your docs repo when the code changes.
  • Local-first development: You can clone the repo and run it locally with Next.js.
  • Beautiful defaults: The dark-mode theme and sidebar navigation look professional out of the box.

Prerequisites

Before you start, make sure you have:

  • A GitHub account.
  • An OpenAPI spec file or a developer tool to document.
  • Node.js (v20.19+ or v22.14+) installed on your machine.

1. Setup and Connection

  1. Go to app.thally.io and create a workspace.
  2. Click Create a site and choose your site name and thally.app address.

Creating a new site in the Thally Cloud dashboard

  1. Connect GitHub: When prompted for the docs source, choose Create a new docs repository. You will be asked to install the Thally GitHub App.

Connecting a new GitHub repository for the documentation source

  1. Connect Product Source: Link the repository that contains your actual product code.

Linking the product code repository so Thally can track changes

2. Local Configuration

Once the site is created, clone the new docs repository to your local machine. In your terminal, run:

git clone https://github.com/YourUsername/your-docs-repo.git
cd your-docs-repo
npm install
npm run dev
Enter fullscreen mode Exit fullscreen mode

This starts a local server at http://localhost:3040.

Terminal showing the local Next.js development server running successfully on port 3040

3. Content Creation

Thally uses MDX (Markdown with React components). You will find your content inside the src/content/ folder.

I created three core pages for my tool:

  • introduction.mdx: Explained what the tool does, why it matters, and linked to related concepts like the OpenAPI specification.
  • quickstart.mdx: A step-by-step guide to install the tool, run a test, and see a result.
  • guides/github-action.mdx: A practical guide showing how to use the tool in a CI/CD pipeline.

To control the sidebar navigation, you edit the docs.json file. I removed the default Thally template pages and replaced them with my tool's actual structure.

Here is how the final page would look when previewing locally:

Previewing the generated api2md Quick start documentation locally

4. Review and Publish

Before publishing, Thally gives you a clean review screen to confirm all your connections.

Reviewing the site settings before the first deployment

To publish your changes, commit them to the main branch:

git add .
git commit -m "docs: add api2md documentation"
git push origin main
Enter fullscreen mode Exit fullscreen mode

Thally Cloud automatically detects the push, builds the site, and deploys it to your live thally.app URL in minutes.

The Thally Cloud dashboard showing the site is live

Obstacles and How I Resolved Them

1. GitHub Repository Name Collision

When setting up the docs source, Thally defaults to using the same name as your product. Because I already had a repo named api2md, GitHub rejected the new repository creation. The fix was simple: I changed the docs repository name to api2md-docs during setup.

2. Double Page Titles

After creating my pages, the site rendered the title twice. This happens because Thally uses the title from the frontmatter to generate the page header automatically. The fix was to remove the # Title line from the body of my MDX files. The frontmatter handles the header, so you only need ## for subsections.

3. Local Development Warnings

When running npm run dev locally, the terminal threw a warning about the middleware file convention being deprecated in Next.js. While it did not break the site, it added noise to the setup. For this small project, I ignored it. For a production site, running the suggested npx @next/codemod would resolve it.

4. Unnecessary API Sidebar Items

Because Thally reads the default openapi.yaml file in the repo, the sidebar automatically generated fake API endpoints like Posts and Users. I updated the docs.json file to remove the default API Reference tab and moved my CLI Reference guide into a Reference group under the Guides tab.

Final Thoughts

Building this site with Thally was incredibly fast. The dark-mode theme and automatic deployment make it feel like a premium documentation platform out of the box. The friction points were minor, mostly related to understanding how the template maps to the sidebar navigation. Once I understood the structure, pushing content to the live site took seconds.

Top comments (0)