How to serve Markdown to AI agents: Making your docs more AI-friendly

Om Umale — Sat, 04 Oct 2025 07:12:36 +0000

The problem: HTML bloat
AI agents can fetch the content of web pages to help developers. Most of the time, this content comes back as HTML. But HTML contains markup that consume tokens without adding meaningful information, degrading performance.

The solution: Content negotiation
The elegant solution is content negotiation. This is a standard HTTP mechanism where clients tell servers what format they prefer using the Accept header.

When an AI agent requests your documentation with Accept: text/markdown or Accept: text/plain, your server can respond with Markdown instead of HTML.

This means:

Fewer tokens for the same information
Easier parsing and comprehension
More documentation fits in the context window
Implementation guide
The exact implementation detail depends on your programming language and framework, but the general approach is the same.

Let's walk through an example with Express.js.

1. Detect the Accept header
When a request arrives, check if the Accept header contains text/markdown or text/plain:

app.get("/docs/*", (req, res) => {
const acceptHeader = req.headers.accept || "";

if (acceptHeader.includes("text/markdown")) {
// Serve Markdown
} else if (acceptHeader.includes("text/plain")) {
// Serve plain text
} else {
// Serve HTML (default behavior)
}
});
2. Serve the raw Markdown
Load and return the raw Markdown content for the requested page:

if (acceptHeader.includes("text/markdown")) {
const markdownContent = await loadMarkdownForPage(req.path);
res.setHeader("Content-Type", "text/markdown; charset=utf-8");
res.send(markdownContent);
return;
}
**3. Fallback to existing behavior
**For all other requests (browsers, crawlers, etc.), continue with your existing HTML rendering:

res.render("docs", { content: processedContent });
4. Test your implementation
Use curl to verify your implementation works correctly:

# Request Markdown
curl -H 'Accept: text/markdown' https://lingo.dev/en/cli

# Request plain text
curl -H 'Accept: text/plain' https://lingo.dev/en/cli

**# Request HTML (default)
**curl -H 'Accept: text/html' https://lingo.dev/en/cli
For Markdown requests, you should see:

Response header: Content-Type: text/markdown; charset=utf-8
Body: Raw Markdown content without HTML tags
For HTML requests, you should see your normal rendered page.

Further reading and resources
To learn more about how to implement this, check out the following resources:
**
Accept header documentation**
Next.js template by @cramforce
Set-up guide for Laravel by @retlehs
Set-up guide for static websites, Cloudflare Workers, and Caddy by @skeptrune.

JavaScript Arrow Functions Explained: Guide to ES6+ Syntax

Om Umale — Sat, 04 Oct 2025 06:57:49 +0000

Introduction
JavaScript is full of features that make writing code easier and faster. Arrow functions stand out as one of the most valuable features added in ES6+. Arrow functions give you a shorter way to write functions, making your code look clean and simple. For beginners, understanding arrow functions is a big step toward writing modern JavaScript like a pro.

What Are Arrow Functions?
Before ES6, writing functions could sometimes feel long and repetitive. Arrow functions solve that by giving you a shorter syntax.

Example with a normal function:

function greet(name) {
return Hello, ${name}!;
}

With an arrow function:

const greet = (name) => Hello, ${name}!;

Both do the same thing, but the arrow function is shorter and easier to read.

Shorter Syntax and Simplicity
Arrow functions are popular because they save time when coding. If your function only returns one value, you can even remove the curly braces and return keyword.

Example:

const add = (a, b) => a + b;
console.log(add(2, 8)); // 10

Here, the arrow function is not only shorter but also easier to understand.

Arrow Functions vs this
A major difference between arrow functions and regular functions is how they treat the keyword this. With normal functions, this can change based on how the function is used, but in arrow functions, this sticks to the surrounding scope.

Example:

const person = {
name: "Wisdom",
greet: () => {
console.log(Hi, I'm ${this.name});
}
};

person.greet(); // Hi, I'm undefined

Forem: Om Umale

How to serve Markdown to AI agents: Making your docs more AI-friendly

JavaScript Arrow Functions Explained: Guide to ES6+ Syntax