How to migrate Docusaurus docs to ThallyHow to migrate Docusaurus docs to Thally

Your Docusaurus import builds successfully. The sidebar opens, the code blocks look familiar, and a local React component appears. Then an old quickstart URL redirects to a page that no longer exists. Converting the files was only part of moving the documentation.

To migrate Docusaurus documentation to Thally, preserve the project, import into a new destination, and compare the rendered content and routes before switching traffic. This guide follows that procedure with a pinned CLI and a controlled fixture, including a redirect that needed manual repair. It is for the engineer or documentation owner handling the move. We build Thally. The checks below establish a small local migration, not a completed customer cutover.

1. Inventory the project and its published routes

Keep an untouched source checkout and record its repository, branch, commit and project directory. Preserve docusaurus.config.*, sidebars, MDX pages, static/ assets, local components, plugins and dependency lockfile together. Copying only docs/ can leave the navigation or an imported component behind.

Write down which docs instances, versions, languages, blog posts and custom pages your readers use. The Docusaurus versioning guide distinguishes the current files in docs/ from the version served by default. These are configurable and can differ. A filename alone does not establish the public URL.

Build an old-to-new route map using the actual published site and its configuration. Include baseUrl, the docs plugin's routeBasePath, frontmatter slug values, version paths, case-sensitive paths and important heading anchors. Docusaurus docs plugin options explain those controls. Keep important old links in your acceptance list even when the new sidebar works.

Separate content you intend to move from content you intend to retire. Record an owner for redirects, access rules, translations and any service configured outside Git. Do not mark an old version or a custom landing page covered because one current guide imports.

2. Import into a fresh Thally project

The current Thally migration prerequisites are Node.js 22 or later and Git. Our local test used Node.js 24.1.0 and @thallylabs/cli 0.8.129. Pinning that CLI identifies the command we ran. Its downloaded scaffold and dependencies can change, so retain the destination lockfile and starter-release.json as well.

Validation executes imported MDX and components locally. Use a source you own or trust. From the directory that will hold the destination, run:

npx --yes @thallylabs/cli@0.8.129 migrate ./docusaurus-source thally-docs --platform docusaurus --yes

Replace ./docusaurus-source with the project root containing the Docusaurus configuration. Choose a destination that does not exist yet. For a repository in a monorepo, the official Docusaurus migration guide supports a GitHub tree/<branch>/<dir> URL pointing to the site directory. Confirm the branch and directory before importing.

The normal new-project flow converts the source, installs dependencies, runs content validation and a production build, and initializes Git. Read thally-docs/migration-report.json afterward. --yes skips prompts. It does not approve publication. Avoid --into when you want an isolated trial because that option merges into an existing project.

A public-site URL is another supported source, but it has different visibility. The adapter guide says the live-site path follows the current version and skips legacy and next trees. That statement does not establish the same filtering for a repository import. Our repository fixture included a historical version page. Prefer source when available, then inspect the actual scope rather than assuming that every input route imports the same material.

3. Review sidebars, MDX and custom components

Thally documents a dedicated Docusaurus adapter for pages, sidebars, categories, admonitions, tabs and static assets. Its adapter guide says sidebars are parsed as data rather than executed. Sidebars that depend on function calls can fall back to folder-based navigation, with a report warning. Inspect the destination hierarchy instead of accepting the page count as proof of correct order.

Docusaurus MDX and React can include components and framework-specific imports. A working destination needs both compatible markup and the code that supplies it.

Material	What to compare after import
Sidebar and category data	Labels, grouping, order, category index pages and hidden or unlisted content
Frontmatter and relative links	Titles, descriptions, slugs, heading anchors and links from nested pages
Admonitions and tabs	Meaning, tab labels, selected content and keyboard interaction
Local React components	Copied files, imports, required packages and rendered content
Static and remote assets	Actual image/download responses and dependencies that remain on another host
Versions and translations	Included trees, release applicability, language navigation and URL mapping
Theme, search and plugins	The destination implementation of each requirement, rather than assumed plugin portability

For our fixture, :::note became <Note>, <TabItem> became <Tab>, and the local component was copied and rendered. Those observations cover one small component with no external package dependencies. They do not establish compatibility for arbitrary React context, global CSS, theme overrides, client-only widgets or third-party plugins.

If an import fails, use the report and build output to identify the file and dependency. Recover missing content or adapt the component deliberately. Do not remove a failing example or explanation merely to get a green build. If you choose --skip-validation, the imported project is still awaiting dependency installation, content checks and a production build.

What the controlled fixture established

The fixture and receipts contain two current docs pages, a literal sidebar, a note, two tabs, a local React component, a marker image, relative MDX links and a renamed quickstart slug. A historical version page and standalone page exercise the scope boundary. This is a controlled source using Docusaurus configuration and MDX patterns. We did not build the source with Docusaurus itself.

The pinned CLI imported 3 pages and 1 asset and passed content validation and production build. The generated project used Next.js 16.4.1. The three pages included the historical introduction at /1.0.0/intro. The standalone page was absent. Validation also reported that the intentionally short historical page might be empty, so passing validation did not mean an absence of diagnostics.

The generated current docs used /intro and /quickstart. The source configuration explicitly selected the current version as the default and gave it an empty version path under the /docs route base. Its redirect still targeted /docs/quickstart after import. That destination returned 404. This was a concrete reason to repair and retest the destination route map.

The exercise did not test a live-site crawl, complete version or translation coverage, a real API request, private-reader enforcement, deployment or DNS changes. Treat those as separate acceptance cases when your project uses them.

4. Repair redirects and test the final destination

Docusaurus's client-redirect plugin generates HTML pages that redirect with JavaScript in production. That is different from an HTTP redirect on the destination host. Inspect the imported rule and verify the response readers actually receive.

In our generated project, we changed the old redirect to point directly to /quickstart and added the /docs aliases needed for the trial. Merge the relevant entries into the existing destination docs.json. Do not replace the rest of its configuration with this example:

{
  "redirects": [
    { "source": "/old-start", "destination": "/quickstart", "permanent": false },
    { "source": "/docs/quickstart", "destination": "/quickstart", "permanent": false },
    { "source": "/docs/intro", "destination": "/intro", "permanent": false }
  ]
}

These paths belong to the fixture. Substitute the routes established by your own map. We used temporary redirects during the trial. Decide permanence deliberately using Thally's redirect contract, then test it on the intended host.

After the repair and rebuild, all three source paths returned HTTP 307 to a destination that returned 200. We also checked the note, local component marker, tab content, rewritten internal links, preserved code text and image bytes. Code-text preservation does not mean the Python example or a product API was executed.

5. Validate the repaired project and review a preview

From the generated project, run the checks again after your edits:

cd thally-docs
npx --yes @thallylabs/cli@0.8.129 check
npm run build
npm run dev

Open the local address printed by the development server, normally on port 3040. Stop it with Ctrl+C when finished. Read the homepage, primary navigation, a deep page, the renamed page, a component-heavy page and each required version or language. At desktop and narrow mobile widths, inspect tabs, code blocks, tables, images, downloads and visible keyboard focus.

Test old links from outside the new sidebar. Check heading fragments, case-sensitive paths, canonical URLs, titles and search. Verify the machine-readable surfaces your users need, such as Markdown, llms.txt and MCP, against the same content and audience. The agent-readable documentation guide explains those different outputs.

6. Keep publication separate from import acceptance

Keep the current Docusaurus deployment available while reviewing the new project. Follow the deployment guide for your chosen host. Commit the complete reviewed destination, including its lockfile, and set the destination repository URL for edit links. Verify access restrictions before any deployment containing private material.

Before an authorized hostname switch, record the old and new routing values, responsible owner, acceptance checks and rollback decision. Use the host's specific domain instructions. A working preview alone does not establish certificate or DNS readiness at the final hostname. After the switch, check the certificate, representative content, old routes, access and machine-readable outputs again. If acceptance fails, restore the planned routing and verify that the old site is reachable.

Use the documentation migration checklist for those shared launch decisions. If you are still evaluating the destination, read the Thally and Docusaurus comparison first. When your source and acceptance cases are ready, create a Thally workspace to evaluate managed hosting, or continue with the local open-source project.

Sources and verification

Reviewed October 30, 2026 against the official Docusaurus 3.10.2 documentation and current Thally migration, CLI, redirects and deployment guides linked above. Local import and validation used CLI 0.8.129 on Node.js 24.1.0. The committed fixture and receipts record the observed conversion and route repair. No customer migration, live-site crawl, account connection, publication, deployment, paid service or DNS change was performed for this guide. Read the editorial policy for sourcing and correction standards.