Markdown twins and negotiation

Every page in the /japan/ tree, building pages and hub pages both, has a markdown twin. The HTML page at /japan/tokyo/chiyoda/marunouchi/DNK-JP-13-01000000 and the markdown page at /japan/tokyo/chiyoda/marunouchi/DNK-JP-13-01000000.md describe the same building. Short links get one too: /japan/id/DNK-JP-13-01000000.md.

The twin exists because most AI crawlers and agent frameworks read markdown far more often than they read rendered HTML, and markdown for the same content runs a fraction of the token count. JMAD serves it as a first-class format rather than something you scrape out of the page.

Getting the markdown version

Two ways to get it. Add .md to the path:

curl https://dnk.co/japan/tokyo/chiyoda/marunouchi/DNK-JP-13-01000000.md

Or send Accept: text/markdown to the HTML path and let the server negotiate:

curl -H "Accept: text/markdown" https://dnk.co/japan/tokyo/chiyoda/marunouchi/DNK-JP-13-01000000

Both return the same body with Content-Type: text/markdown. A markdown response carries Vary: Accept so a cache in front of the page keys on that header instead of serving the wrong format to the next request. The HTML response carries a broader Vary: Accept-Language, Cookie, Accept instead, since it also varies by locale cookie and browser language. The two Vary values belong to different responses; they don't stack.

⚠️

Caution

If you are testing this in a browser, note that browsers send Accept: text/html by default and will always get HTML. Use curl or an explicit fetch with the header set.

Crawler fallback

Some well-known crawlers do not send Accept: text/markdown even when they would rather have it, so JMAD checks the user agent as a fallback and serves markdown regardless of the Accept header sent. The fallback list: GPTBot, OAI-SearchBot, ChatGPT-User, ClaudeBot, Claude-User, Claude-SearchBot, Google-Extended, GoogleOther, PerplexityBot, Perplexity-User, Applebot-Extended, Bingbot, Meta-ExternalAgent, Amazonbot, CCBot.

Discovering the twin from the HTML page

Every HTML page links to its own markdown twin two ways, so an agent that lands on the HTML version does not have to guess the .md path:

• an HTTP Link header: Link: <.../DNK-JP-13-01000000.md>; rel="alternate"; type="text/markdown"
• an equivalent <link rel="alternate" type="text/markdown" href="..."> in the document head

The same Link header also advertises /japan/llms.txt with rel="llms-txt", so a crawler following link relations from any page finds both the twin and the usage guide in one hop.

What the twin contains

The markdown twin carries the same facts as the HTML page: for a building page, that means name, address, every field with its value and provenance, footprint and centroid, venues, nearby buildings, and record history, rendered as headings, tables, and prose rather than as a component tree. A building's markdown comes from the stored building_pages.markdown column, generated once at publish time. A hub page's markdown (title, counts, child areas, a table of buildings with permalinks) renders on request from the same view model that drives the HTML hub, so the two never drift out of sync.

The field table also includes completion month, structure, land and leasable areas, acquisition price and date, appraisal amount and date, book value, occupancy ratio, leasable units, hotel rooms, developer, tenure, and management-plan certification date. Missing values remain unavailable. Prices are JPY; disclosed amounts can concern only the issuer’s holding. The Sources section links the original portfolio or filing.

JSON-LD stays HTML-only

HTML building pages also carry a <script type="application/ld+json"> block describing the building as a schema.org Place, with a PropertyValue identifier for the DNK Asset ID, address, geo, and key measurements. This is for search engines that read structured data from HTML, not a substitute for the markdown twin: no fact lives only in JSON-LD, since most agent crawlers do not execute JavaScript or parse embedded scripts at all.

Next

• Agent discovery for how a crawler finds JMAD in the first place.
• MCP server for a structured alternative to fetching markdown by hand.