Config option for custom slug

[microbouji]

Is this a bug report?

no

Have you read the Contributing Guidelines on issues?

yes

Proposal

I might be getting a bit carried away here, but keeping in mind #559 and #560, I think people might want a way to customize the slug from their side. The siteConfig.js option could look like this:

slug: 'unidecode' | 'uslug' | <customSlug function>

In line with docusaurus' idea to get started quickly, the two first string options would provide pre-configured slugs. Given a header like ## 汉语/漢語

• "unidecode" would generate the slug #yi-yu-han-yu
• "uslug" would generate #汉语漢語.

One of them would be the default.

The third option would be a custom callback giving the user total control over the slug output. I don't think this would make the code much more complex, as all the logic for this would be inside that toSlug.js file which would still just export one toSlug function to be used in the same way everywhere else.

[markerikson]

I'd love to see something like this. My specific use case is for the Redux FAQ pages like https://redux.js.org/faq/actions . Right now, a header like this:

### How can I represent “side effects” such as AJAX calls? Why do we need things like “action creators”, “thunks”, and “middleware” to do async behavior?

Turns into a URL like:

https://redux.js.org/faq/actions#how-can-i-represent-side-effects-such-as-ajax-calls-why-do-we-need-things-like-action-creators-thunks-and-middleware-to-do-async-behavior

Which is unfortunately hideous and looks silly when you paste it elsewhere.

I'd originally worked around this when I first wrote the FAQ by adding hand-written "short anchor" tags right before each header, like <a id="actions-side-effects"></a>, and hand-writing the TOC links at the top using those anchors using URLs like https://redux.js.org/faq/actions#actions-side-effects`. That worked with our old version of Gitbook, but not the new one. Both current Gitbook and Docusaurus auto-generate a side TOC based on the header text.

Not a deal-breaker, but sure would be nice to have something like this.

[Nevon]

I agree with @markerikson and am in the same boat. For common errors, I would even like to embed a link to where users can find help within the application itself, but that means I need to have stable slugs that I can guarantee won't change even if I decide to change the wording of the title.

[endiliey]

We won't do this in v1. But this is doable in v2 by writing your own remark plugins/ rehype plugins to alter the slug. The docs functionality itself is a plugin in v2, so we won't do it in config.

Closing :)

[TheReincarnator]

@endiliey Are you sure this can be done in V2 using remark/rehype? I tried to, but I don't have access to the file name there.

I'd basically like to name my files 04-My Page.md, and it should automatically

• be the 4th item,
• get a sidebar label My Page,
• get a slug my-page

I can achieve 1 and 2, but I am not managing how to do 3.

[slorber]

slug: /my-page frontMatter should do the job in v2

Note the url would be /docs/my-page by default, but you can remove the /docs/ prefix with plugin option routeBasePath: '/'

[CMCDragonkai]

If I'm in a situation where I cannot write frontmatter because the markdown file has to be markdown without any yaml, is there a way I can specify a custom slug for a given page directly in JS or some alternative override?

[slorber]

We want to provide a "createFrontMatter" api so you could dynamically create frontmatter (like the slug) based on various params, including the md file path.

#5568