Problem

Human readers rely on visual cues, sidebar navigation, and inferred context to understand documentation. AI agents and Large Language Models (LLMs), however, primarily consume raw text streams. When documentation lacks a rigorous semantic structure, these models struggle to map relationships between concepts, leading to poor reasoning and inaccurate coding suggestions.

Why it matters

If your documentation is not optimised for LLMs, developers using tools like GitHub Copilot, Cursor, or ChatGPT will receive more hallucinations when working with your software. This directly degrades the developer experience, as users often blame the product itself for the errors generated by their AI assistants.

Approach

Transition from a “visual-first” mindset to a “semantic-first” mindset. Use standard Markdown features—such as strict header hierarchies, explicit code block language tags, and descriptive alt text—to provide a clear, machine-readable roadmap of your content. docmd processes this structure into optimised outputs via the LLMs Plugin.

Implementation

1. Strict Header Hierarchy

Avoid skipping header levels for purely visual effects. A consistent hierarchy allows LLMs to understand the scope and relationship of different sections.

• # Title: The primary subject of the page.
• ## Major Concept: An atomic, high-level topic.
• ### Detail: A specific sub-task or property of that concept.

• ❌ Poor: Using ### immediately after # because you like the smaller font size.
• ✅ Good: # Installation followed by ## Prerequisites and then ### System Requirements.

2. Descriptive Metadata for Media

Since LLMs cannot “see” images or diagrams, you must provide the architectural context in the alternative text or an adjacent paragraph.

![System Architecture: The frontend React application communicates with the Node.js API via REST, which then queries a Redis cache and a PostgreSQL database.](../../static/img/architecture.png)

3. Explicit Code Block Labeling

Always specify the language for every fenced code block using Syntax Highlighting. This allows LLMs to parse the code’s Abstract Syntax Tree (AST) correctly.

// docmd.config.js
export default {
  plugins: ['llms']
};

4. Semantic Containers

Use Callouts rather than generic blockquotes to provide intent. docmd’s semantic containers help AI models distinguish between core instructions and supplementary tips or warnings.

Trade-offs

Semantic rigor requires authors to be disciplined. You can no longer use Markdown features (like blockquotes or headers) as purely decorative elements. However, this discipline results in documentation that is significantly more accessible to both AI agents and human readers using assistive technologies.