jsdoc-to-markdown icon indicating copy to clipboard operation
jsdoc-to-markdown copied to clipboard

Heading link id/name sanitation for GitHub flavored MarkDown

Open S0AndS0 opened this issue 5 years ago • 0 comments

It should be possible, at least for GitHub flavored MarkDown, to output documents with MarkDown style links.

Here's a function that I've pulled out from one of my own Mustache templated projects, github-utilities/dot-github...

/**
 * Strips and/or replaces characters for heading id/name linking
 * @extends renderCallback
 * @function stripForID
 * @return {renderCallback}
 */
const stripForID = () => {
    const renderCallback = (text, render) => {
        if (!!render.gfm) {
            return render(text).trim()
                .toLowerCase()
                .replace(/<[^>]*>?/gm, '--')
                .replace(/[^a-z0-9_\- ]/g, '')
                .replace(/ +/g, '-');
        }
        return render(text).trim()
            .toLowerCase()
            .replace(/[^a-z0-9_\- ]/g, '')
            .replace(/ +/g, '-');
    };
    return renderCallback;
}

... an example of how it's used...

# Heading Text
[heading__tag]:
  #{{#stripForID}}Tag that may contain bad characters?!{{/stripForID}}
  "description shown when hovered over"

Lorem ipsum dolor sit amet, [consectetur][heading__tag] adipisicing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

... and an example of MarkDown output...

# Heading Text
[heading__tag]:
  #tag-that-may-contain-bad-characters
  "description shown when hovered over"

Lorem ipsum dolor sit amet, [consectetur][heading__tag] adipisicing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

If this seems like a good feature feel free to notify me of what files need changed, and I'll be both able and willing to submit some Pull Request(s).

S0AndS0 avatar Mar 25 '20 20:03 S0AndS0