melvinmt Machine-Accessible Websites
Make websites accessible to both humans and AI agents by implementing the "AIs are the web's new user" pattern.
Quick Start
Implement these 5 components:
- Floating toggle - HUMAN/MACHINE switcher at page bottom
- Content negotiation - Return markdown for
Accept: text/markdown - Alternate .md pages - Markdown version at each URL +
.md - llms.txt - AI-friendly site overview at
/llms.txt - robots.txt - Exclude
.mdpages from search engines
1. Floating HUMAN/MACHINE Toggle
Fixed-position toggle at bottom center of each page.
States:
- Human (default):
◉ ʜᴜᴍᴀɴ ○ ᴍᴀᴄʜɪɴᴇ→ shows HTML page - Machine:
○ ʜᴜᴍᴀɴ ◉ ᴍᴀᴄʜɪɴᴇ→ shows markdown with permalink + copy button
Behavior:
- State resets to HUMAN on page refresh (no localStorage/cookies)
- Machine mode shows: raw markdown, permalink to
.mdendpoint, copy button - No close button needed (toggle navigates between modes)
For implementation details, see references/toggle-component.md.
2. Content Negotiation
Return markdown when agents request it via header:
Accept: text/markdown
Server middleware pattern:
function contentNegotiation(req, res, next) {
if (req.headers.accept?.includes('text/markdown')) {
const mdPath = getMarkdownPath(req.path);
return res.type('text/markdown').sendFile(mdPath);
}
next();
}
All links in markdown responses MUST be formatted as: [link text](url)
For framework-specific examples, see references/content-negotiation.md.
3. Alternate .md Pages
Create markdown version of each page accessible via .md suffix:
| HTML Page | Markdown Alternate |
|---|---|
/ |
/index.md |
/about |
/about.md |
/docs/api |
/docs/api.md |
Add alternate link tag to HTML <head>:
<link rel="alternate" type="text/markdown" href="/about.md" title="Markdown version">
4. llms.txt Implementation
Create /llms.txt following the llmstxt.org specification.
Required structure:
# Project Name
> Brief one-line description of your project.
Key context for LLMs about your project.
## Docs
- [Getting Started](https://example.com/docs/start.md): Quick setup guide
- [API Reference](https://example.com/docs/api.md): Complete API docs
## Optional
- [Advanced Config](https://example.com/docs/advanced.md): Edge cases
Machine version of landing page should display the contents of llms.txt.
For templates and examples, see references/llms-txt-examples.md.
5. robots.txt Exclusion
Exclude .md pages from traditional search engine crawling:
User-agent: *
Disallow: /*.md$
Disallow: /llms.txt
This prevents duplicate content issues while keeping pages accessible to AI agents.
Implementation Checklist
- [ ] Add floating HUMAN/MACHINE toggle component
- [ ] Implement content negotiation middleware
- [ ] Generate .md version of each page
- [ ] Add <link rel="alternate"> tags to HTML pages
- [ ] Create /llms.txt with site overview
- [ ] Configure machine mode landing page to show llms.txt
- [ ] Update robots.txt to exclude .md pages
- [ ] Test with curl -H "Accept: text/markdown"
Testing
Test content negotiation:
curl -H "Accept: text/markdown" https://yoursite.com/about
Test .md endpoint:
curl https://yoursite.com/about.md
Test llms.txt:
curl https://yoursite.com/llms.txt