# LLM-Friendly Docs Course: [Markdown](https://www.devtutorials.ai/learn/markdown) · Section: AI-Native Markdown Source: https://www.devtutorials.ai/learn/markdown/ai-native/llm-friendly-docs > Write docs that AI tools can find their way through. Fix a page whose answer a chatbot missed, give each section a heading that names its topic, make sections stand alone, and write an llms.txt that maps your docs. ## The Answer Was on the Page, but the AI Missed It A customer asks the support chatbot: "How long do I have to return a damaged item?" The chatbot searches the order-support docs and answers: "I could not find that information." The answer was in the docs. Here is the page it was on: ```md runnable title="A page that is hard to search" # Refunds ## Overview This page covers refunds. Please read it carefully. ## Details Refunds are allowed within 30 days of delivery. After that, we offer a voucher. As mentioned above, damaged items are different. For those, it is 60 days, and we need a photo. Refunds over ₹5,000 need a manager's approval. This applies to all of the cases above. Bank transfers take up to 5 working days. Card refunds take up to 3. ## More See the section above for the rules. ``` Open the **Outline** tab and look at the **Chunks** list. AI search tools usually cut a page into chunks at its headings, then fetch only the chunks that match the question. Look at what they have to work with: - The headings, "Overview", "Details" and "More", say nothing about the content. A search for "damaged item return" matches none of them. - The one useful chunk mixes four topics. - "As mentioned above" and "the cases above" only make sense if you read the whole page. A chunk fetched on its own does not have "above". In this lesson, you will learn to write docs that both people and AI tools can find their way through: an `llms.txt` file that maps your docs, and pages whose sections still make sense when read alone. **In simple words:** an AI tool often reads one section of your page, not the whole page. Every section must make sense on its own. ## TL;DR - AI search tools split pages into **chunks**, usually at headings, and read only the chunks that match the question. - Give each section a **heading that names its topic**: "Damaged items", not "Details". - Make each section **stand alone**. Name the subject again. Never write "as mentioned above". - Keep **one topic per section**, and put the key fact in the first sentence. - **`llms.txt`** is a Markdown file at the root of a docs site. It lists the important pages for AI tools: a `#` title, a `>` summary, then `##` sections of links. - Offer a clean **`.md` version** of each important page, so tools do not have to read HTML. ## A Real-World Example Think about recipe cards in a box. Each card has the dish name at the top, and everything you need for that dish on the card. You can pull out one card and cook from it. Now imagine a recipe book where page 40 says "add the sauce from the previous recipe". If you only photocopy page 40, you cannot cook the dish. AI tools photocopy single pages, or single sections. Write every section like a recipe card. ## What You Will Learn In this lesson, you will learn: 1. How AI tools find and read your docs. 2. Why headings decide what an AI tool can find. 3. How to write sections that make sense on their own. 4. The `llms.txt` format, and its Optional section. 5. Why each page should also be available as plain Markdown. ## Cheat Sheet ```md runnable title="The same page, easy to search" # Refund policy The rules support staff use to approve a refund. ## Refund window A refund is allowed within 30 days of delivery. After 30 days, offer a voucher instead. ## Damaged items A customer can return a damaged item within 60 days of delivery. Ask for a photo of the damage before approving the refund. ## Approval limit A refund over ₹5,000 needs a manager's approval. This applies to every refund, including damaged items. ## Refund times A bank transfer refund takes up to 5 working days. A card refund takes up to 3 working days. ``` Open the Outline tab. Each chunk now has a heading that names its topic, and each one is small. A search for "damaged item return" goes straight to the "Damaged items" chunk, and that chunk alone answers the question. ## How AI Tools Read Docs ### Chunks and Retrieval When a chatbot or a coding agent answers from your docs, it usually does not read every page. It uses **retrieval**: 1. Your pages are split into **chunks**, often one chunk per heading. 2. When a question comes in, the tool finds the chunks that best match it. 3. It reads only those chunks, and answers from them. This is often called **RAG**, retrieval-augmented generation. You do not need to build one to benefit from writing for one. You only need to know that **your page will be read one section at a time**. Not every tool cuts at headings, and some use overlapping windows of text instead. But headings are the most common split, and well-headed, self-contained sections help every method. The Context Engineering and RAG courses cover how retrieval works in depth. ### Headings Are the Index A chunk is found mostly by its words, and its heading carries a lot of weight. Compare: | Vague heading | Heading that names the topic | |---|---| | Overview | What the refund policy covers | | Details | Refund window | | Notes | Damaged items | | More | Refund times | | FAQ | Can I return a damaged item after 30 days? | A question-style heading works well too, because people ask questions, and the heading then matches their words. ## Sections That Stand Alone ### Name the Subject Again In a normal essay, you avoid repeating yourself. In docs read by AI tools, a little repetition is what makes each chunk work. ```md runnable title="A chunk that needs the page, and one that does not" ## Damaged items As above, but it is 60 days, and we need a photo. ## Damaged items A customer can return a damaged item within 60 days of delivery. Ask for a photo of the damage before approving the refund. ``` The first section is useless on its own. What is "it"? 60 days for what? The second names the item, the time limit, what it counts from, and what to do. ### Four Rules for Every Section 1. **One topic.** If a section covers two things, split it into two sections. 2. **Key fact first.** The first sentence should answer the question the heading asks. 3. **No pointers.** Replace "as mentioned above", "see below" and "this" with the actual words. 4. **Define short forms** in the section that uses them, or link to where they are defined. Read each section on its own, as if it were the only thing you could see. If it still answers its heading, it is ready for retrieval. If you have to scroll up to understand it, rewrite it. ### Keep Sections Small A chunk that is too large wastes the tool's context on text that does not answer the question. A chunk that is too small loses the details. Aim for sections a person can read in under a minute: a few short paragraphs, or one table. The Outline tab shows the size of each chunk as you write. ## llms.txt ### A Map of Your Docs for AI Tools A website's menu is built for people clicking around. An AI tool wants something simpler: a list of the important pages, with a one-line note on each. **`llms.txt`** is that list. It is a Markdown file at the root of a site, like `https://docs.example.com/llms.txt`. The format is described at llmstxt.org. ```md runnable clean file="llms.txt" title="An llms.txt for the order-support docs" # Order Support > Order Support answers customer questions about orders, refunds and shipping. These docs are for support staff and for AI tools that help them. Policies change each quarter. The refund and shipping pages are always current. ## Policies - [Refund policy](https://docs.example.com/refunds.md): refund window, damaged items, approval limit and refund times - [Shipping policy](https://docs.example.com/shipping.md): delivery times, express orders and lost parcels ## How-to guides - [Approve a refund](https://docs.example.com/how-to/approve-refund.md): the steps in the support tool, with screenshots described in text ## Optional - [Policy history](https://docs.example.com/history.md): what changed in each quarter since 2024 ``` ### The Format The file has a fixed order: 1. An **H1** with the name of the project or site. This is the only required part. 2. A **blockquote** (`>`) with a short summary: what this is and who it is for. 3. Optional paragraphs or lists with more detail. No headings here. 4. **H2 sections**, each holding a **file list**: one link per line, written `- [name](url): notes`. The section called **`## Optional`** has a special meaning. It holds links a tool can skip when it needs to keep its context short. Put history, deep detail and nice-to-have pages there. ```md runnable file="llms.txt" expect-lint="LLM002,LLM003,LLM004,LLM005" title="An llms.txt that breaks the format" # Order Support Answers questions about orders. ## Policies - Refund policy: docs.example.com/refunds - [Shipping policy](https://docs.example.com/shipping.md) ### Old pages - [History](https://docs.example.com/history.md): policy changes ``` Open the Checks tab. The summary is not a blockquote (**LLM002**). The first item is not a link (**LLM004**). The second has no note (**LLM005**). And `###` headings are not part of the format (**LLM003**). ### Markdown Versions of Pages The links in `llms.txt` point to `.md` files, not web pages. The format suggests that every important page should also be available as **clean Markdown**, at the same address with `.md` added: `refunds.html` also as `refunds.html.md`, or `refunds` as `refunds.md`. A web page carries menus, scripts and styling. A tool reading it has to dig the content out first, and pays tokens for all the rest. The `.md` version gives it just the content. Many docs tools can also build an **`llms-full.txt`**: one big file with the full text of every page. This is a common convention, not part of the `llms.txt` format itself. It suits tools that want everything at once; `llms.txt` suits tools that want to choose. Every link in `llms.txt` must work. A tool cannot tell a broken link from a missing page, so a dead link hides that page from it completely. Check the links every time the docs are published. ## Where This Is Used - **Product docs sites:** `llms.txt` at the root, `.md` versions of each page. - **Support chatbots:** answer from docs split into chunks at headings. - **Coding agents:** fetch a library's `llms.txt` to find the right page to read. - **Internal wikis and runbooks:** searched by AI assistants one section at a time. ## Common mistakes | Symptom | Cause | Fix | |---|---|---| | The chatbot says it cannot find an answer that is in the docs | The heading does not name the topic | Rename the heading after its topic, or as a question | | The chatbot answers with only half the rule | The rest is in another section, joined by "as above" | Make the section stand alone | | The answer includes unrelated rules | Several topics share one section | Split the section, one topic each | | A tool skips an important page | It is not in `llms.txt`, or its link is broken | Add it, and check every link | | `llms.txt` checks fail | No `>` summary, `###` headings, or items that are not links | Follow the fixed order: `#`, `>`, then `##` lists of `- [name](url): notes` | | Tools pay many tokens to read a short page | They read the HTML version | Publish a `.md` version and link to it | ## Quick Check ## Exercises ## What to Remember - AI tools often read one chunk of a page, usually one section between headings. - Name the topic in every heading. Question-style headings work well too. - Make every section stand alone: one topic, key fact first, no "as above". - `llms.txt` maps your docs for AI tools: a `#` title, a `>` summary, then `##` lists of `- [name](url): notes`. - `## Optional` holds links a tool can skip. - Publish clean `.md` versions of important pages, and keep every link working. ## Further Reading - [llms.txt](https://llmstxt.org): the format, with examples. - [Rspress: AI guide](https://rspress.rs/guide/basic/ssg-md): one docs tool's `llms.txt`, `llms-full.txt` and `.md` page output. - The **Retrieval-Augmented Generation** course on this site: how chunks are made, searched and ranked. Next: **Cleaning AI Output**, where you fix over-formatted answers that AI tools write, and set style rules agents follow.