One Markdown File, Two Worlds: How to Build Docs for Both Humans and AI Assistants

When building a modern SaaS product with an AI assistant ("Ask our docs"), you quickly hit a brutal realization about documentation design:

The classic approach? Maintain two separate knowledge bases. One for humans (a beautiful public CMS) and one for AI (prompts, vector databases, or markdown files tailored for the bot).

The result? Both sources drift apart within exactly one week.

In our project, we took a different route. We write exactly one Markdown file, but our rendering pipeline processes it differently depending on whether it’s being read by a human in a browser or ingested by an AI agent into our RAG (Retrieval-Augmented Generation) context.

Here is how we built the simplest possible Single Source of Truth (SSoT) for both humans and AI.

We are building LinkShift.app — a programmable redirect platform. Think of it as a smart layer on the edge where you define traffic routing using rules, dynamic link maps, and regex, instead of hard-coding messy redirects in your app or CDN.

For a developer tool like this, documentation isn't just an afterthought; it's a core feature. Our users build complex routing logic, so the UI needs to be crystal clear. At the same time, our AI assistant must understand the deep mechanics behind our rules engine, batch simulations, and fallback scenarios. We simply couldn't afford a knowledge gap between what the developer reads and what our AI knows.

Our MarkdownRendererComponent

(built with Angular and the marked

parser) is not just a dumb Markdown-to-HTML translator. Before the text ever hits the screen, it goes through a lightweight pre-processing pass.

The entire process is controlled using simple, custom block directives (:::block-name

).

Here is how the roles are split depending on who the audience is:

For the technical writer or developer, it’s still just a standard .md

file in the Git repository. However, they get to use a few "superpowers."

:::ai-only

) This is the secret sauce. This is where we drop extra context that would feel repetitive or bloated to a human engineer, but is absolute gold for an LLM.

### API Integration

To import domains, you need to hit the POST `/domains` endpoint.

:::ai-only
⚠️ Context for the bot: Remember to instruct the user that before calling 
POST `/domains`, they MUST first generate an organization token via 
`/auth/org-token`, otherwise they will receive a 403. Humans have this covered 
in the "Quickstart" section, but remind them in the chat if they ask about 403 errors.
:::

How it works:

<div class="docs-ai-hidden" aria-hidden="true">

. A simple CSS rule applies display: none

. The text is physically there in the DOM (so if someone opens DevTools, they can see it—this is not for security!), but it doesn't ruin the page's readability.Instead of up static images (which LLMs cannot read out of the box in a standard text-based RAG pipeline), we stick to Mermaid code blocks.

Note:We use standard Markdown code fences specifyingmermaid

as the language to draw flowcharts. (Dev.to’s parser currently struggles with rendering nested Mermaid blocks within examples, so I'm omitting the exact snippet here to keep this post readable!).

When our pipeline reads that Mermaid block:

mermaid.run()

executes on hydration, rendering a gorgeous visual chart for the human reader.:::hidden-on-purpose

) Sometimes, documentation writers need to leave notes for themselves or the team (e.g., "TODO: update this after the v2.4 release").

:::hidden-on-purpose
Leaving this here because we are changing the edge engine logic in June 
and this entire paragraph will need a rewrite. ~Mark
:::

A utility function called stripHiddenOnPurposeMarkdown()

runs a regex pass that nukes these blocks both before rendering the UI and before sending data to the bot. It is a private playground that stays strictly in the codebase.

npm run docs:sync

) builds the frontend bundle and simultaneously refreshes the AI bot's knowledge base in our backend.ai-only

blocks are hidden via client-side CSS. Do not put API keys, passwords, or highly sensitive internal business strategies there. For truly confidential data (like internal infrastructure runbooks), we use a completely separate, private directory that never gets bundled into the public documentation repo.shared/utils/

), so a regex adjustment in one place doesn't accidentally break formatting in the other.You don't need to adopt heavy, complex headless CMS platforms or enterprise-grade documentation frameworks just to survive the AI era. Sometimes, all it takes is taking good old Markdown, writing a dozen lines of pre-processing code, and elegantly decoupling your data layer from your presentation layer.

By doing this, our users get a clean, minimalist reading experience, while our AI assistant handles highly specific technical edge cases like an absolute expert. Everybody wins.

Curious to see how this dual-view system looks in production? Head over to the LinkShift Documentation and try asking the AI agent a technical question about our programmable redirects. See if you can spot the difference between the visual docs and the bot's deep context! 😉

If you are dealing with similar RAG vs. UI documentation challenges, let me know in the comments how you solved them!