DEV Community

Piotr Zielinski
Piotr Zielinski

Posted on

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

#markdown #llm #dx #webdev

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

  • Humans want brevity, beautiful diagrams, clean UI, and zero noise.
  • LLMs want absolutely everything. Edge cases, exact dashboard click paths, API endpoint sequences, and hidden technical constraints.

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.

💡 The Context: Why We Needed This

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.

🛠️ The Architecture: One File, Two Views

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:

Document Element Human Reader (Docs UI) AI Assistant (RAG Context)
Standard Markdown ✅ Yes (Rendered to HTML) ✅ Yes (Raw text)
Infoboxes (:::info) ✅ Yes (Styled callouts) ✅ Yes (Textual context)
Mermaid Diagrams ✅ Yes (Graphical render) ✅ Yes (Raw text flow syntax)
Hidden from Humans (:::ai-only) ❌ Hidden (CSS display: none) ✅ Yes (Full text for LLM)
Author Scratchpad (:::hidden-on-purpose) ❌ Stripped entirely ❌ Stripped entirely

📝 How It Looks in Practice (Syntax)

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."

1. AI-Only Blocks (:::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.
:::
Enter fullscreen mode Exit fullscreen mode

How it works:

  • For Humans: The pre-processor wraps this in a <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.
  • For the AI: The backend loader reads the raw Markdown file directly into the vector store or prompt context, completely ignoring the CSS layer. The bot sees the instructions loud and clear.

2. Mermaid Diagrams for Everyone

Instead of uploading 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 specifying mermaid 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:

  • In the browser: mermaid.run() executes on hydration, rendering a gorgeous visual chart for the human reader.
  • For the AI: The agent receives the raw text-based Mermaid code. Because modern LLMs are fantastic at understanding graph-based text syntax, they can flawlessly explain the flowchart to a user in chat or even generate an updated version of the chart in their response.

3. The Author Scratchpad (:::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
:::
Enter fullscreen mode Exit fullscreen mode

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.

🧠 Why This Boosts Developer Experience (DX)

  1. Zero Knowledge Fragmentation: Everything related to a feature (the user-facing copy, the diagrams, and the hyper-technical AI hints) lives in one single file. A code change requires exactly one documentation update.
  2. Git as the Source of Truth: Version control, Pull Requests, peer reviews—the entire documentation workflow follows your standard development pipeline.
  3. Dead Simple Deployment: A single sync script (npm run docs:sync) builds the frontend bundle and simultaneously refreshes the AI bot's knowledge base in our backend.

⚠️ Lessons from Production: What to Watch Out For

  • This is NOT a security boundary: The 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.
  • Keep Your Parsers in Sync: The text stripping utilities must behave identically on both the frontend and the backend. We highly recommend keeping these parser utilities in a shared workspace folder (e.g., shared/utils/), so a regex adjustment in one place doesn't accidentally break formatting in the other.

Conclusion

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.

Try It Out!

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!

Top comments (0)