Home → Suggestions →

Case-preserving HTML anchors

• Edit

Jack Repenning

05 Aug, 2014 05:30 PM

I our API documentation site, we generate a ton of HTML out of mmd sources. Some of the document section URLs serve multiple functions: links within the document, links between documents, links from API response bodies, and even (in a growing number of cases) human-readable, power-user documentation.

A particular example requiring several of those functions simultaneously is the proposed standard Problem Details for HTTP APIs. This RFC provides a standard JSON or XML layout for a message response that not only reports an error, but also provides some description of the underlying problem, and a link to a more extended problem description. These reports are designed to serve both automated response (through fields such as a numeric status value) and also human response, typically during interactive debugging or from log files (text descriptions and URLs to fuller documentation).

This elevates the in-document link anchors within the documents from opaque internal details all the way to user-experience concerns. One thing that's becoming particularly troublesome is the denaturing of section names into auto-generated href'able anchors. A document might say

### 405 - Method Not Supported [httpRequestMethodNotSupported]

Explanation of this error.

... and the matching HTTP Problems response body might say

{
   "detail": "Method requested (POST) is not supported for this resource. Supported methods are: [PUT, DELETE, GET]",
   "status": 405,
   "title": "Bad Request",
   "type": "https://problems.luna.akamaiapis.net/config-gtm/v1/errors#httpRequestMethodNotSupported"
}

But, we can't, because the anchor text gets down-cased. We can write the "type" to link to the downcased name, httprequestmethodnotsupported, but this is unreadable for humans.

So: is there some way we can say "no, really: exactly like I said it"? Probably not, so could there come to be?

1. 1 Posted by Jack Repenning on 05 Aug, 2014 05:37 PM

   

   I recognize that there are backwards-compatibility issues here: any page coded to the current, down-casing behavior would break if it suddenly stopped. But couldn't there be some syntactic extension, say

   ### 405 - Method Not Supported [[httpRequestMethodNotSupported]]
   ...
   

   • Edit

2. Support Staff 2 Posted by fletcher on 05 Aug, 2014 06:01 PM

   

   The problem is that people expect Markdown links to case agnostic, so
   that [Foo] and [foo] both work. The change you're requesting would
   break this, so I don't think it makes sense to add it to MMD itself.

   But there's no reason you can't modify your own copy of MMD to behave
   the way you want and *not* lowercase the id (either when specifying the
   label manually, automatically, or both).

   The relevant section of code would be around (for HTML anyway):

   } else if (n->children->key == AUTOLABEL) {
   temp = label_from_string(n->children->str);

   Fletcher

   • Edit