Skip to content

case study · help center · docs migration

How Portico's docs run on Topicary

Vlad Kuzin
Written with AI assistance
On this page

Portico is a client onboarding app for bookkeepers and other service firms. Its help center has 22 topics: setup, templates, onboardings, the client's side, billing, integrations, the API and webhooks. Until October 2026 those pages were MDX files inside the marketing website. They now live at docs.portico.run, published by Topicary.

Both products have the same founder, so this is a customer story with a conflict of interest. It is also the most honest test we have. The docs are real, the product under them changes every week, and every failure is ours to fix.

Why move docs out of the website

The docs inside the website had three problems, and none of them was the website's fault. Prices were typed into the pages, so a pricing change meant a search through 22 files and the hope of finding every copy. Nothing checked links or code samples, so a broken link stayed broken until a reader complained. And the app changed weekly while the docs changed when someone remembered. We found that the third problem was the expensive one. A help page that names a button the app no longer has costs a support email every time someone reads it.

What the move was

The source stayed plain Markdown in Portico's repository. A sync script writes it into a Topicary project, and the site publishes from there. Old addresses such as portico.run/docs/quick-start answer with a 301 to the same page on docs.portico.run, which follows Google's guidance for site moves. Links in emails, partner pages and search results keep working.

Three things changed in the source itself:

  • Prices and plan limits became variables. The docs quote 44 numbers that marketing can change: monthly and annual prices, lifetime prices, storage, e-signatures, AI generations, SMS allowances and credit packs. Each one is now one value in one file (how variables work).
  • Repeated blocks became components. Three notes, such as which plans include a feature, appear on 2 or more pages each and are written once.
  • Every page got a type. 12 reference topics, 7 task topics and 3 concept topics. The type decides which automated checks run on a page.

The numbers before and after

Before (website MDX)After (Topicary)
Pages2222, same URLs behind 301s
Places a price is writtenOnce per mention1 value per price, 44 values
Link checkNoneWeekly: 58/58 links, 26/26 JSON samples on the first run
SearchNoneCmd+K search with snippets
AI answersNoneAsk AI on every page, with source links
FAQ structured dataNoneBuilt from every FAQ section
Machine-readable copyNonellms.txt, full-text Markdown, a .md copy of each page

What readers got

Readers search with Cmd+K and get snippets around their words. They can ask a question in plain language and get an answer drawn from the docs, with links to the pages it used. A reader who asks "How do I take a deposit?" gets the payment field steps and a link to the Stripe page. Each "Frequently asked questions" section becomes FAQ structured data for search engines. Every page also exists as Markdown at its own address, and the whole site is listed in llms.txt for AI tools (what that covers).

What the writer got

A weekly check now opens every link and parses every code sample (how the check works). On its first run it checked 58 links and 26 JSON samples across 22 topics and found nothing broken. When it does find something, the item goes to the writer's worklist next to the page. A dead link becomes a task, not a surprise.

The docs also follow the app. After each Portico release, a drift check compares the labels the docs tell users to click with the labels the app actually shows. In October that check caught an error message the app had stopped showing, while the docs still quoted it word for word. The fix took one sentence; finding it by hand would have taken a reader's complaint.

Publishing is a separate, deliberate step. A sync changes the authoring copy, and readers see nothing until someone clicks Update. Before it builds the site, Topicary checks every page for broken references and undefined variables, and it refuses to publish when it finds one. That gate fired this week. A list item that started with a variable token was read as one long, broken variable name, and the publish stopped with the page named. The source line was reworded, a check was added, and the next publish went through.

What moving our own docs found

Dogfooding is only useful if you write down what broke. Moving Portico's docs surfaced real defects in Topicary, and we fixed these for every customer:

  • Search snippets ran headings into body text and started mid-word.
  • Brand-colored links were hard to read in dark mode for dark brand colors.
  • Page titles always ended in "- Topicary", whatever title template a site set.
  • The content health scan kept stale "not in any map" items after a page was mapped. Its AI review also reported its own excerpt limit as missing content.

What we would do differently

We would put the prices into variables on day one, before any other change. Every other part of the move depended on knowing which numbers were facts about the product and which were prose. Finding the 44 values took longer than converting 22 pages, because prices hide in tables, FAQs and the middle of sentences. A one-line rule would have saved that work: if marketing can change it, it lives in the data file.

We would also run every automated check on real content before trusting it. The weekly link check reported "no eligible pages" on its first run, and that empty result looked like a clean bill of health. It was not. The pages were live but still marked Draft, and the check only reads pages marked Published. An empty result from a check is a question, not an answer.

Finally, we would read the AI review findings as a sample before acting on them. 14 of its first 25 findings said text was cut off. The text was complete; the review had been shown a 600-character excerpt without being told it was one.

Should you do the same

Is your help center a folder of Markdown or MDX inside a website? Then the move is mostly mechanical. Keep the files, add the variables, point a subdomain at the new site and redirect the old paths. We recommend starting with the variables, because that step pays off even if you never move. The work that pays off is the boring part. Keep one value per price, and run a check that tells you when the product moved under the page.

FAQ

Frequently asked

Did Portico lose search traffic by moving its docs to a subdomain?

There was little to lose. The docs earned 11 clicks from Google in the 12 months before the move. Every old address answers with a 301 to the same page on docs.portico.run, and the new sitemap went to Search Console the same day.

Do the docs still live in Portico's repository?

Yes. The source is plain Markdown in Portico's website repository, reviewed like code. A sync script writes it into a Topicary project, and the site publishes from there. Nobody edits the published site by hand.

What does Topicary do worse than a docs folder in the website?

Two things, today. Marking a synced page as verified fails, because the editor and the stored page disagree on defaults. Adding the custom domain also needed a support step. Both are logged as open defects.

How long did the move take?

The content work took two days with an AI agent doing most of the conversion and checking. The domain switch, redirects and checks took one afternoon. Fixing the Topicary defects the move found took longer than either.

Can I do the same move without Topicary?

Yes. Keep your Markdown, put prices in one data file, add a weekly link checker and redirect old paths with 301s. Topicary bundles those parts with search, AI answers and structured data, but the pattern works with any static site tool.

Ready to try Topicary?

Start free. No credit card required.