bitbucket-slug1.10.1

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";

assert.equal(
  bSlug(
    "# Let's backwards-engineer BitBucket anchor link slug algorithm"
  ),
  "markdown-header-lets-backwards-engineer-bitbucket-anchor-link-slug-algorithm"
);

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

§ API

bSlug(str)

Input: string. Output: string.

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

§ Competition

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.

§ Changelog

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

§ Licence

MIT opens in a new tab

Copyright © 2010–2020 Roy Revelt and other contributors

Related articles:

Related packages:

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