Migrate Markdown Docs to a Hosted Site

Your Markdown docs already work. They live in a repo, they render on GitHub, and the team knows where to find them. So why move? Usually because the folder has outgrown itself: no search, no previews, no versioning story, and readers who land on raw files instead of a real site. The harder question is how to migrate Markdown docs to a hosted site without rewriting everything, breaking every inbound link, or getting locked into a platform you can't leave. This guide walks through doing it in a way you can check at each step and undo if needed.

Docs carry real weight. In the Stack Overflow 2025 Developer Survey, "Technical documentation is the most used resource for learning, with nearly 68% of respondents using it in the past year". A migration that breaks pages or quietly changes their meaning costs your readers, not just your team.

Import Markdown without a rewrite

The point of a migration is to change where and how your docs are served, not what they say. If the plan starts with "first, we'll convert everything to the new format by hand," stop and question the plan.

Markdown is portable, but less portable than it looks. CommonMark, the project that set out to standardize the syntax, puts it bluntly: "Because there is no unambiguous spec, implementations have diverged considerably over the last 10 years". A document can render one way on a GitHub wiki and another way through a different converter. Markdown has no such thing as a "syntax error," so those differences can slip through unnoticed. The Babelmark 3 tool compares output across more than 20 Markdown implementations, and the spread is a good reminder of how much variation exists.

In practice, a good import should:

• Read your existing folder structure and turn it into navigation, rather than asking you to rebuild the sidebar by hand
• Keep front matter (titles, descriptions, ordering) and map it to site metadata
• Preserve relative links between pages and resolve them to the new URLs
• Carry over images and other assets with their paths intact
• Flag anything it couldn't interpret instead of silently dropping it

What to check before you migrate Markdown docs to a hosted site

Before you run any import, take inventory. It takes an afternoon and saves days of cleanup.

• List every page and its current public URL, if the docs are already served anywhere
• Note nonstandard syntax: custom admonitions, HTML blocks, embedded components, footnotes, tables with merged cells
• Find pages that rely on renderer-specific behavior, such as GitHub's automatic heading anchors
• Identify which pages get the most traffic or are linked from your product, README, or support articles

The divergence CommonMark describes is why this inventory matters. Your highest-risk pages are the ones with unusual formatting and heavy inbound links. Check those first after the import.

Thally's migration takes a folder of Markdown (or an existing docs project), converts it into a connected content graph, and deploys it in one pass, with SSL, preview deploys, and instant rollback. Your source files stay as Markdown.

Keep the import non-destructive and reversible

A migration should never be a one-way door. Two properties matter here.

Non-destructive means the import reads your content and writes its output somewhere else. Your original files, history, and folder layout are untouched. If the import mangles a page, your source is still exactly as it was.

Reversible means you can back out completely: drop the new site, point traffic back at the old one, and lose nothing. That covers your content and your URLs.

Some practical ways to protect both:

• Run the import against a branch or a copy, not the branch your current site deploys from
• Review the output as a diff before merging anything back into your main docs branch
• Keep the old site live and serving until the new one has been verified
• Write down the rollback steps before you need them

URLs deserve extra care, because they're where migrations quietly do the most damage. If page paths change, set up redirects from every old URL to its new equivalent. Google's guidance on site moves is clear on several points:

• Use HTTP permanent redirects such as 301 or 308 where possible
• "301 and other permanent redirects don't cause a loss in PageRank"
• Googlebot can follow up to 10 hops in a redirect chain, but Google advises redirecting straight to the final page
• Don't send many old URLs to one unrelated page, such as the new home page
• Keep redirects as long as possible, generally at least one year, and consider keeping them forever for users' sake

The last point matters most for docs. Old links to your docs live in Stack Overflow answers, blog posts, issue threads, and customer bookmarks for years. A redirect map built from your pre-migration inventory is the cheapest insurance you can buy.

Preview the hosted site before you switch

Don't flip DNS and hope. Build the new site, put it at a preview URL, and check it the way a reader would.

Here's a review checklist that catches most problems:

• Click through the navigation and confirm the structure matches what you expect
• Open the pages you flagged as high-risk and compare them side by side with the originals
• Check code blocks for language highlighting, line breaks, and escaped characters
• Test every redirect from your map, and confirm each one resolves in a single hop to the right page
• Run a link checker against the preview to catch broken internal links
• Try search with the queries your users actually type
• Check the site on mobile

Preview deploys also pay off after launch. If every change to your docs produces its own preview, reviewers see the rendered page, not just a Markdown diff. Formatting bugs get caught in review instead of in production.

When the preview passes, cut over in a way you can undo. Keep the old deployment available, switch traffic, and watch for errors and missing-page responses over the coming days. If something is badly wrong, roll back first and debug second.

Leave the content in Git

Moving to a hosted site shouldn't mean moving your content out of the repository and into someone else's editor. If your Markdown already lives in Git, that's a strength worth keeping.

Write the Docs describes docs as code as "a philosophy that you should be writing documentation with the same tools as code". That means issue trackers, version control, and code review. It isn't a niche practice. Riona MacNamara has described how adopting it completely changed how Google does documentation, and Jen Lambourne has described the UK Government Digital Service's move to the same approach. GitHub is already where most developers collaborate: Stack Overflow's 2025 survey found it was the most popular code documentation and collaboration tool, at 81%, ahead of Jira at 46% and GitLab at 36%.

Keeping docs in Git gets you concrete benefits:

• Docs changes can ride in the same pull request as the code change, or in a linked PR reviewed at the same time
• Reviewers see the code diff and the docs diff together
• Full history, blame, and revert for every page
• No separate workflow that depends on someone remembering to go update a different tool

When you evaluate a hosting option, ask direct questions. Where does the canonical copy of my content live? Can I edit it in my own editor and push from my own machine? If I stop using this service, what do I walk away with? If the answer is an export button instead of "it's already in your repo," weigh that carefully.

Also check what access the platform needs. A tool that only needs read access to your repositories is a smaller risk than one that wants write access everywhere.

Once docs live in Git and publish from one source, you can serve the same content in more than one shape. That includes a human-readable site, raw Markdown, and an llms.txt file. llms.txt is a proposed standard: "a markdown file that provides brief background information and guidance, along with links to markdown files". It sits at the root path /llms.txt of a site and helps AI tools find your content.

Start on the free tier with one managed site

You don't need a budget approval to prove a migration works. Start small:

• Pick one docs set, ideally a real one with a few awkward pages
• Import it to a free managed site
• Run through the preview checklist above
• Share the preview with two or three people who use the docs often and ask what's broken

If it holds up, you have evidence for the larger move. If it doesn't, you've lost an afternoon and your original Markdown hasn't changed.

Weigh what you'd be giving up compared with staying on a static host you manage yourself. GitHub Pages, for example, caps published sites at 1 GB and recommends source repositories stay under 1 GB. It times out deployments after 10 minutes and applies soft limits of 100 GB of bandwidth per month and 10 builds per hour. Those limits are fine for many teams. The bigger cost is usually the time you spend maintaining a build pipeline, previews, search, and redirects yourself.

Check the exit path too. Thally's free plan includes one managed site. The engine is MIT-licensed, so if you ever stop paying, the site can keep running on the open-source engine, hosted wherever you choose. Whatever you pick, make sure leaving is as straightforward as arriving.

Migrating Markdown docs doesn't have to be a rewrite or a leap of faith. Import without changing the source, keep everything reversible, preview before you switch, keep the content in Git, and prove it on a free site first. Each step is something you can verify, and that's the point.

Sources

1. Site Moves and Migrations (Google Search Central)
2. CommonMark
3. GitHub Pages limits (GitHub Docs)
4. Docs as Code (Write the Docs)
5. /llms.txt proposal (Answer.AI)
6. Stack Overflow 2025 Developer Survey: Developers
7. Keep Your Docs Site in Sync With Code Changes | Thally
8. Thally Automation: Ship the Code. Docs Follow. | Thally
9. Thally Migration & Hosting: Import Docs, Host Them at the Edge | Thally