Generating markdown headers instead of HTML

[DavidMikeSimon]

This makes the output more idiomatically Markdown-y, and in particular works better with Markdown-parsing tools like markdown-toc

[davidchambers]

Idiomatic Markdown is worth pursuing, but I believe this change would break an important feature of Transcribe: clean fragment identifiers. The following links point to the same section, but one is much nicer than the other:

• https://github.com/sanctuary-js/sanctuary/tree/v0.14.1#traverse
• https://github.com/sanctuary-js/sanctuary/tree/v0.14.1#traverse--applicativeftraversablet--typerepf---a-fb---ta---ftb

The former is generated by Transcribe; the latter by GitHub.

Could we better interoperate with markdown-toc without sacrificing clean fragment identifiers?

[DavidMikeSimon]

Two possible approaches:

• Move the function signature (i.e. everything after the ::) to a line of regular text below the header. Then github's automatic identifier would be alright.

• Add a span tag around the header text with the generated name

What do you think would be best, if either?

[davidchambers]

The first option doesn't suit me because I sometimes rely on case sensitivity. The follow links point to different sections:

• https://github.com/sanctuary-js/sanctuary/tree/v0.14.1#Maybe
• https://github.com/sanctuary-js/sanctuary/tree/v0.14.1#maybe

The second option sounds promising. The element should be a div rather than a span, though, since headings are block-level elements.

Do Markdown parsers respect Markdown syntax inside HTML elements?

[DavidMikeSimon]

@davidchambers I was thinking span because it would be an inline-level element inside the block-level markdown header, e.g.:

## <span name="foo">Foo</span>

Which would render to:

<h2><span name="foo">Foo</span></h2>

[DavidMikeSimon]

@davidchambers Okay, I've made an update. Now the PR does the following:

• Replace <code> tags with markdown backticks
• Replace <hX> tags with markdown hashes
• Still uses HTML <a> tags for links, but moves the name attribute from the <hX> to the <a> tag

I tried the <span> approach above, but GitHub's markdown parser discarded the spans for no reason that I could figure out.

[davidchambers]

Thanks, @DavidMikeSimon. I'm eager to put your updated version through its paces. :)

[davidchambers]

Since markdownHeadingPrefix is referenced just once, let's replace it with its definition.

[davidchambers]

We could use '######'.slice(0, options.headingLevel) in place of the Ramda version.

[davidchambers]

I spent some time formatting this code. Let's use this:

//. formatSignature :: Options -> String -> Number -> String -> String
var formatSignature = R.curry(function(options, filename, line, signature) {
  return '######'.slice(0, options.headingLevel) + ' ' +
         '<a name="' + esc(signature.split(' :: ')[0]) + '"' +
           ' href="' + esc(options.url.replace('{filename}', filename)
                                      .replace('{line}', line)) + '">' +
           '`' + esc(controlWrapping(signature)) + '`' +
         '</a>\n';
});

[davidchambers]

I created sanctuary-js/sanctuary-type-classes@v8.1.1...davidchambers/transcribe to test these changes. I don't see any differences in the rendered output, so this is a strict upgrade. Not only is the text more accessible to markdown-toc, it's more elegant. :)

[DavidMikeSimon]

@davidchambers Ok, formatted as suggested

[davidchambers]

❤️