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) | |
|---|---|---|
| Pages | 22 | 22, same URLs behind 301s |
| Places a price is written | Once per mention | 1 value per price, 44 values |
| Link check | None | Weekly: 58/58 links, 26/26 JSON samples on the first run |
| Search | None | Cmd+K search with snippets |
| AI answers | None | Ask AI on every page, with source links |
| FAQ structured data | None | Built from every FAQ section |
| Machine-readable copy | None | llms.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.