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

Quick Take

import { strict as assert } from "assert";
import { bSlug } from "bitbucket-slug";

    "# Let's backwards-engineer BitBucket anchor link slug algorithm"


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: ent opens in a new tab to decode entities and lodash.deburr opens in a new tab to convert letters to basic Latin.



Input: string. Output: string.

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


Whoever wonders, no, slugify opens 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.


See it in the monorepo opens in a new tab, on GitHub.


To report bugs or request features or assistance, raise an issue on GitHub opens in a new tab.

Any code contributions welcome! All Pull Requests will be dealt promptly.


MIT opens in a new tab

Copyright Β© 2010–2021 Roy Revelt and other contributors

Related articles:

Related packages:

πŸ“¦ edit-package-json 0.5.1
Edit package.json without parsing, as string, to keep the formatting intact
πŸ“¦ easy-replace 5.0.1
Replace strings with optional lookarounds, but without regexes
πŸ“¦ str-indexes-of-plus 4.0.1
Like indexOf but returns array and counts per-grapheme
πŸ“¦ email-all-chars-within-ascii 4.0.1
Scans all characters within a string and checks are they within ASCII range
πŸ“¦ js-row-num 5.0.1
Update all row numbers in all console.logs in JS code
πŸ“¦ line-column-mini 2.0.1
Convert string index to line-column position