Generate BitBucket readme header anchor slug URLs. Unofficial, covers whole ASCII and a bit beyond.

§ Idea

BitBucket readme file headings are automatically linked with anchors.

This library generates those anchor links, just in case you want to generate a "Table of Contents" or programmatically generate links to any given BitBucket headings.

We backwards-engineered the BitBucket slug-generation algorithm, and it appears to be:

  • Strip all punctuation (.,;&)
  • Strip all emoji or non-letter characters (like 🦄 or )
  • Strip hashes which mean Markdown headings and single space that follows them (##)
  • Replace each chunk of spaces with single hyphen
  • Deburr (déjà vu -> deja vu; ąžuolas -> azuolas)
  • Strip non-latin letters (Cyrillic, Hiragana, Katakana etc.)

In BitBucket README's, there's a rule that no two slugs can be the same. If BitBucket slug-generation function generates the same URL, it starts to append _1, _2 on the first repeated slug onwards.

There are only two dependencies: entopens in a new tab to decode entities and lodash.deburropens in a new tab to convert letters to basic Latin.

§ Competition

Whoever wonders, no, slugifyopens in a new tab on npm won't match the BitBucket heading slug generation API. There are peculiarities which differ.

This library, on another hand, is aiming to match BitBucket spec as close as possible. Our unit tests are pinning the output of this library against the BitBucket-rendered HTML.

§ Usage

const bSlug = require("bitbucket-slug");

const res1 = bSlug(`## So-called "music"`);
console.log("res1 = " + JSON.stringify(res1, null, 4));
// => "markdown-header-so-called-music"

// works with encoded HTML:
const res2 = bSlug("## Some Lithuanian - Ąžuolynas");
console.log("res2 = " + JSON.stringify(res2, null, 4));
// => "markdown-header-some-lithuanian-azuolynas"


API is simple: string in, string out.

If the input is undefined or null or not a string - empty string will be returned.

§ Licence

MITopens in a new tab

Copyright © 2015–2020 Roy Revelt and other contributors

Related articles:

Related packages:

📦 edit-package-json 0.1.35
Edit package.json without parsing, as string, to keep the formatting intact
📦 easy-replace 3.7.63
Replace strings with optional lookarounds, but without regexes
📦 str-indexes-of-plus 2.10.10
Like indexOf but returns array and counts per-grapheme
📦 email-all-chars-within-ascii 2.9.71
Scans all characters within a string and checks are they within ASCII range
📦 js-row-num 2.7.27
Update all row numbers in all console.logs in JS code