Case-preserving HTML anchors

Jack Repenning's Avatar

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

    Jack Repenning's Avatar

    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]]
    ...
    
  2. Support Staff 2 Posted by fletcher on 05 Aug, 2014 06:01 PM

    fletcher's Avatar

    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

Comments are currently closed for this discussion. You can start a new one.

Keyboard shortcuts

Generic

? Show this help
ESC Blurs the current field

Comment Form

r Focus the comment reply box
^ + ↩ Submit the comment

You can use Command ⌘ instead of Control ^ on Mac

Recent Discussions

22 Apr, 2018 11:04 PM
13 Apr, 2018 10:58 PM
09 Apr, 2018 09:47 PM
09 Apr, 2018 04:28 PM
19 Feb, 2018 10:29 PM

Recent Articles