WEB-254Recommended
Link Markdown copies to Markdown copies
Every internal link in a Markdown copy points to the Markdown copy of its target.
How to do it
An agent that follows a link from a Markdown page to an HTML page pays for the whole layout. Rewrite internal links when you build the Markdown, including breadcrumbs, chapter links and previous and next links. Leave links to other sites alone. The copies themselves follow Offer every page as Markdown.
Examples
JavaScript example
export const toMarkdownLinks = (markdown, host) =>
markdown.replace(/\]\((https:\/\/[^)\s]+)\)/g, (link, url) => {
const { hostname, pathname } = new URL(url);
return hostname === host && !/\.\w+$/.test(pathname) ? `](${url.replace(/\/?$/, '')}.md)` : link;
});
Python example
import re
from urllib.parse import urlsplit
def to_markdown_links(markdown: str, host: str) -> str:
def rewrite(match: re.Match) -> str:
url = match.group(1)
parts = urlsplit(url)
if parts.hostname == host and not re.search(r"\.\w+$", parts.path):
return f"]({url.rstrip('/')}.md)"
return match.group(0)
return re.sub(r"\]\((https://[^)\s]+)\)", rewrite, markdown)
How to check
A script reads every .md page. It fails on any link to your own host whose path does not end in .md, apart from images and feeds.
Related rules
- WEB-186 Offer every page as Markdown in Website
For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/website/ready-for-ai-agents/markdown-links-to-markdown">Agent Wranglers website playbook</a>. In code you write, add a comment next to it with the same link.