remarkjs/remark-slug

Legacy plugin to add `id`s to headings — please use `rehype-slug`

remark-slug

Stability: Legacy. This package is no longer recommended for use. It’s still covered by semantic-versioning guarantees and not yet deprecated, but use of this package should be avoided. Please use remark-rehype to move from remark (markdown) to rehype (HTML) and then replace remark-slug with rehype-slug.

Legacy documentation for this package is still available in Git.

License

MIT © Titus Wormer

remark-slug's Issues

Enable unique slugs across multiple files

Initial checklist

• I read the support docs
• I read the contributing guide
• I agree to follow the code of conduct
• I searched issues and couldn’t find anything (or linked relevant results below)

Problem

Given a headline appears multiple times within a set of markdown files that is being processed by unified-engine and remark-slug. Then resetting the slugger within the transformer produces slugs that are unique on a per-file basis.

As a remark-slug and unified-engine user I would like to be able to postprocess markdown files with pandoc and concatenate them into a single output file. In such a scenario I need slugs that are unique across the whole set of files and multiple syntax trees to maintain uniqueness after concatenation.

Solution

I propose an option multifile which is false by default for backwards compatibility but when true prevents the slugger from being reset:

export default function remarkSlug(opts) {
  const {multifile} = { multifile: false, ...opts }
  
  slugs.reset()  // reset once, only.
  return (tree) => {
    if (! multifile) {
       slugs.reset()
    }
    // [...]
  }
}

Open questions

• Does the name multifile make sense? Other ideas: reset, autoreset, resetSlugs

Alternatives

1. Fork remark-slug and publish a forked package
2. Implement it privately and drop remark-slug in favour of a custom function

Given the widespread use of remark and pandoc a contribution to remark-slug may be the best alternative.

remark-slug doesn't take current URL into consideration

Problem

remark-slug currently just takes the text content of the heading and slugifies it for remark-autolink-headings, I assume.

Unfortunately, I am on a nested URL like: /blog/contributing-to-open-source-projects-the-right-way and not on the root path, therefore the a link redirects me to the root page instead of staying on the current page and jumping down.

Is there any solution or config option for that?

Expected behaviour

Jump to the anchor

Add `-` before headings whose ID starts with number to avoid URL issue

Initial checklist

• I read the support docs
• I read the contributing guide
• I agree to follow the code of conduct
• I searched issues and couldn’t find anything (or linked relevant results below)

Problem

Hi, I use VS Code to write markdown. And, I use an extension that adds section numbering to the headings like 1.1, 1.1.1 and so on.

For my website, I use Nuxt Content which uses remark-slug plugin. So, the headings have their ID set as 1-1-something. This causes an issue when I directly go the webpage with the hash, as the hash starts with number, and I think it's not allowed in CSS. So, the underlying Vue Router throws an error and the page doesn't load.

Solution

I can't stop using the VS Code extension which adds the automatic section numbering, because I work with huge markdown documents and I prefer to have heading numbering to quickly navigate inside VS Code's Outline sidebar. So, currently, I am unable to go the URL of the webpage using hash.

So, it would be great to simply add some - or any other text or symbol before the IDs of the headings that start with number. This way, the IDs would not start with number (even if the Headings text start with number) and the Vue Router won't throw an error.

Alternatives

1. An alternative would be to stop adding section numbers. but that's just not feasible for long markdown documents.
2. Also, I can use CSS to add heading numberings, instead of having the heading numberings inside the markdown text. It would solve the issue, but, then again, it would make it very difficult to read such long markdown files offline (on local computer) if there is no heading numberings. So, again, it's not feasible.

does not add anchors to headings using GitHub’s algorithm

Subject of the issue

remark-slug does not add anchors to headings using GitHub’s algorithm.

This probably got to do with toString from https://github.com/syntax-tree/mdast-util-to-string

Your environment

N/A. Does not matter.

Steps to reproduce

Example you have markdown

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

## <a name="foo"></a> _Foo_

Use runkit for easy reproduction

https://runkit.com/endiliey/5dd56d8045205a0013aec93d

Expected behaviour

Slug should be like GitHub https://gist.github.com/endiliey/4516bbf630b0f34eeabe8900733cfbf6#-foo

-foo and -foo-1

Actual behaviour

Slug is a-namefooa-foo and a-namefooa-foo-1

Emoji leads to weird slug

Watch carfully the hovered link (it looks good), but when clicking, I got a weird URL. I assume that the emoji is still here, but hidden.

It seems that remark-slug is ok as you can see in the HTML.

Compatibility with remark-react?

Hi!

I am trying to switch from remark-html to remark-react with this:

// remark-plugins.js
import remark from 'remark';
import slug from "remark-slug"
import reactRenderer from 'remark-react';

export default (body: string) => remark()
  .use(slug)

  .use(reactRenderer)

  .processSync(body, {
    commonmark: true,
  })

When doing a render I get the following snapshot using jest:

import renderer from 'react-test-renderer';

import remarkPlugins from "../remark-plugins.js"

it("should render markdown as react component", () => {
  const md = remarkPlugins("## Test\n[link](href)").contents
  const tree = renderer.create(md).toJSON();
  expect(tree).toMatchSnapshot();
})

// Jest Snapshot v1, https://goo.gl/fbAQLP

exports[`should render markdown as react component 1`] = `
<div>
  <h2
    id="user-content-test"
  >
    Test
  </h2>
  
  
  <p>
    <a
      href="href"
    >
      link
    </a>
  </p>
</div>
`;

As you can see, the "id" is longer than what I would expect. I tried adding remark-autolink-headings in the first place: this one is actually adding href around "Test" with the correct slug (#test).
Do you have an idea about this problem and if it can be supported? (Without remark-slug I only get a simple h2, no id attribute.

When creating slugs (within gatsby-plugin-mdx), accents make the anchors fail

If in a mdx file I have something like

# This is my áccentuated title

The id generated keeps the accent

id="This-is-my-áccentuated-title"

But then, the link that you can recreate with "to="mywebpage#This-is-my-áccentuated-title" doesn't go to the anchor because of the accent (at least what I'm seeing in Chrome)

Could it be possible to remove accents from strings?

Mismatch between GH Emoji and Slug

Not sure whether this belongs here or on remark-validate-links, but given the following:

### :triangular_ruler: Example

GitHub generates #triangular_ruler-example. However, remark-validate-links expects #triangularruler-example, with no underscore, using the following .remarkrc:

{
  "plugins": {
    "toc": {
      "tight": true
    },
    "slug": {
      "library": "github"
    },
    "lint": {
      "no-html": false,
      "list-item-spacing": false,
      "list-item-indent": "mixed",
      "code-block-style": "fenced",
      "maximum-heading-length": 80,
      "no-heading-punctuation": false,
      "no-missing-blank-lines": false
    },
    "validate-links": true
  },
  "settings": {
    "listItemIndent": "1",
    "bullet": "*"
  }
}

Compatible with `remark-autolink-headings`

when I upgrade remark-slug to version >=5.0.0
remark-autolink-headings is broken, but version 4.2.3 works.

link in header leads to unexpected parsing

Subject of the issue

I am trying to host the AWS docs on Next.js using MDX with the remark-slug plugin. The slug breaks when there is HTML in a header.

Your environment

https://codesandbox.io/s/remark-debug-forked-9dggo?file=/src/index.js

Expected behavior

I am expecting the slug to be consistent with how it is on GitHub.

Actual behavior

I am getting id="sign-up-for-awsa-namesign-up-for-aws-gsga", but when viewed on GitHub the extension is #sign-up-for-aws.

Types definitions

Types definitions

TS definitions for the export would be much appreciated.

Allow slugger to be passed in

Subject of the feature

It'd be helpful to be able to pass the slugger instance in as configuration.

Problem

In the context of a page with multiple chunks of markdown, it's possible for the same slug to be generated more than once on the same page.

Expected behavior

If I anticipate that I'd like to be able to pass in an instance that the plugin would use to generate slugs rather than minting its own one. That way I can be in charge of resetting it when I decide it's necessary, and I can use the same slugger for multiple markdown renderings.

Alternatives

I suppose I could set a different clobberPrefix for each markdown field, but I'd rather not.