Allow configuring the title of a sidebar link in sidebar.js in plugin-docs

[vjpr]

I thought it would be possible to do something like this: {type: 'doc', id: 'foo', title: 'Foo'}.

However it doesn't work Error: Unknown sidebar item keys: label..

Say you want to automatically generate your sidebar from the file system structure inside sidebar.js`...this would be useful.

[slorber]

That's something we could add easily, will ask one of our MLH fellows to take a look at this.

[slorber]

@vjpr we agree that you want to "override" the doc title set in frontmatter through the sidebar file?

What's your usecase for defining a name in sidebars.js instead of using the doc sidebar_label frontmatter?

Should it be named label? (because your snippet show "title")

Label is already allowed by the other sidebar types like category and link so it could be more consistent.

[vjpr]

I want the page title to be sentence case. My file is ‘foo.md’ and I want the page title to be ‘Foo’. My ultimate use case is to have an “auto sidebar” that matches the file system structure. Seems like this would be a pretty popular use case also. At the moment I do this manually.

…

On Mon 1. Mar 2021 at 18:58, Sébastien Lorber ***@***.***> wrote: @vjpr <https://github.com/vjpr> we agree that you want to "override" the doc title set in frontmatter through the sidebar file? What's your usecase for defining a name in sidebars.js instead of using the doc sidebar_label frontmatter? Should it be named label? (because your snippet show "title") Label is already allowed by the other sidebar types like category and link so it could be more consistent. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#4314 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACEWRLIUTFXG3CL2I7BHLDTBPIVFANCNFSM4YKO7P6A> .

[vjpr]

Label is good.

…

On Mon 1. Mar 2021 at 19:08, Vaughan Rouesnel ***@***.***> wrote: I want the page title to be sentence case. My file is ‘foo.md’ and I want the page title to be ‘Foo’. My ultimate use case is to have an “auto sidebar” that matches the file system structure. Seems like this would be a pretty popular use case also. At the moment I do this manually. On Mon 1. Mar 2021 at 18:58, Sébastien Lorber ***@***.***> wrote: > @vjpr <https://github.com/vjpr> we agree that you want to "override" the > doc title set in frontmatter through the sidebar file? > > What's your usecase for defining a name in sidebars.js instead of using > the doc sidebar_label frontmatter? > > Should it be named label? (because your snippet show "title") > > Label is already allowed by the other sidebar types like category and > link so it could be more consistent. > > — > You are receiving this because you were mentioned. > > > Reply to this email directly, view it on GitHub > <#4314 (comment)>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/AACEWRLIUTFXG3CL2I7BHLDTBPIVFANCNFSM4YKO7P6A> > . >

[slorber]

Yes but why don't you set this sentence case syntax in the doc frontmatter exactly?

https://v2.docusaurus.io/docs/next/api/plugins/@docusaurus/plugin-content-docs#markdown-frontmatter

---
id: foo
title: fOO
sidebar_label: FoO
---
My Document Markdown content

Is there any case where you would want a sidebar label that can't be hardcoded in the frontmatter? and for what reason?

[vjpr]

It's just inconvenient to have to add a sidebar_label to each frontmatter. I create documents all the time and I just don't like the repetitive work, and I also have to remind team members to not forget either.

[slorber]

So, adding sidebar_label in the md doc is less convenient than adding label in sidebars.js?

I don't understand why exactly this is less convenient. In all cases if you need a custom sidebar label the creator of the document would have to remember to add that custom label

[vjpr]

So, adding sidebar_label in the md doc is less convenient than adding label in sidebars.js?

The label is not added manually...my sidebar.js is a function that reads the filesystem, and generates the items automatically. So I want to be able to add label: sentenceCase(id) for each file. Right now this is not possible, which means every file I create I have to add the frontmatter manually.

sidebars.js code

module.exports = function (docsDir, overrides = [], excludes = []) {
  if (debug) console.log('----------')

  docsDir = require('path').resolve(docsDir)

  const filteredTree = dirTree(docsDir, {
    extensions: /\.(md|mdx)$/,
    exclude: [/node_modules/, ...excludes],
  })

  const sidebarTree = treeToDocuSidebarTreeShorthand(filteredTree)

  // See: https://v2.docusaurus.io/docs/sidebar#creating-a-hierachy
  function treeToDocuSidebarTreeShorthand(node) {
    if (!node) return

    // File (leaf)
    if (node.type === 'file') {
      const id = getDocumentIdFromPath(node, docsDir)

      // TODO(vjpr): We skip ids starting with dots because Docusaurus doesn't support them right now.
      if (id.startsWith('.')) return

      return {
        type: 'doc',
        id,
      }
    }

    // Directory
    if (node.type === 'directory') {
      const out = {
        type: 'category',
        label: changeCase.sentenceCase(node.name),
        items: node.children
          .map(child => treeToDocuSidebarTreeShorthand(child))
          .filter(Boolean), // Filter trees with no markdown files.
      }
      if (out.items.length) return out
      return
    }
  }

  const sidebarTreeItems = sidebarTree?.items ?? []

  // We use `.items` because the first dir is the docs dir which whose level we don't want to show.
  const out = [...sidebarTreeItems, ...overrides]

  if (debug) console.log(JSON.stringify(out, null, 2))

  return out
}

[slorber]

I see thanks

Allowing to add frontmatter through the sidebars file is a more generic solution, maybe we should just focus on that to enable all use-cases?

What if the frontmatter is defined in the doc and the sidebar, which one wins? Should we shallow-merge or fully replace one frontmatter by the other?

[vjpr]

I feel like explicit frontmatter should win.

…

On Tue 2. Mar 2021 at 17:24, Sébastien Lorber ***@***.***> wrote: I see thanks Allowing to add frontmatter through the sidebars file is a more generic solution, maybe we should just focus on that to enable all use-cases? What if the frontmatter is defined in the doc and the sidebar, which one wins? Should we shallow-merge or fully replace one frontmatter by the other? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#4314 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACEWRJN3SLEOII6HZMRBGLTBUGM5ANCNFSM4YKO7P6A> .

[slorber]

After thinking about this, I think we should just let the sidebar provides its own label

That would be a bit weird to allow the sidebar config to override doc frontmatter, and there's already a workaround where you can assign a customProps data structure to each doc, so basically this is already possible to override sidebar label and frontmatter with this setting + swizzle the sidebar comp and use this custom data.

https://v2.docusaurus.io/docs/next/sidebar#passing-custom-props

We can still add the ability to set the label through the sidebar, as a shortcut.

[idontknowjs]

hey @slorber, We were migrating our Docs from Vuepress to Docusaurus and have over 200 markdown files in each 18 versions. So we do not want to modify every markdown files with Front matter like these:

---
id: greeting
title: Hello
---

Is there any way possible that we can change the title/sidebar_label of the files from sidebar.js only.

But adding label to a type: 'doc' like shown below, doesn't seem to work and give error Unknown sidebar item keys: label:

{
  type: 'doc',
  id: 'doc1', // string - document id
  label: 'This is Doc 1'

}

label only seem to work with type: 'category'. For us this will be a very useful feature, if this can be achieved

[slorber]

@CovalentBond can you help me understand your usecase better?

What does a source doc look like? (content + filename, ideally Git repo?)

Why is it complicated to add frontmatter to the 200 docs and why it is better to do that on sidebars.js instead? Wouldn't this complicate the maintenance on the long term as authors won't understand how to set the doc title?

What data do you want to provide with sidebars.js exactly? Only the doc sidebar label? Or also the doc title? Or even more frontmatter data?

[idontknowjs]

Hey, my usecase is similar to what's stated in #4425 . We have existing markdown files without frontmatter in it. Now to only add sidebar labels and title to each file, we might need to edit those existing files. Instead we are looking out for alternatives to just pass sidebar_labels through modifying only the sidebar.js, because editing all the doc file is painful and will also update the time stamps in each file. So it might be confusing to differ the outdated with latest doc.

Now even if somehow we are able to pass the title from sidebar.js, we might have two headings in each file (one from existing doc and one from the Docusaurus page title). So to hide the Docusaurus title, we still might need to add hide_title: true to each file which is actually we are refraining from, modifying every existing file.

And were looking if hide_title: true could be set globally from sidebar.js or docusaurus.config.js`. To avoid editing files.

But I feel #4485 would definitely resonate with our use case to support docs without frontmatter in them

[slorber]

• feat(v2): frontmatter-less: read first heading as title and use it in front-matter #4485 allows using # Title instead of frontmatter to define the page/doc title + sidebar doc label.
• Auto generate sidebar according to the docs folder structure #3464 will add support for auto-generated sidebars

Does this cover all your use cases?

I don't feel sidebars.js is a good place to "override" the frontmatter (but it make sense to override the "sidebar_label" frontmatter), as it is possible to create docs that don't belong to any sidebar for which we still want somehow to provide the frontmatter from an "external" config.

Maybe we should have a callback in the docs plugin allowing you to "modify/enhance/override" the doc frontmatter with your custom computed data? (ie you could provide/read your own config file or use data from a CMS or whatever)

[
  "@docusaurus/plugin-content-docs",
  {
    createFrontMatter: async ({ frontmatter, version, sourceFile, markdownString }) => ({
      ...frontmatter,
      title: formatTitle(frontmatter.title),
      myExtraFrontMatter: "hello"
    })
  }
];

Would you use this?

@vjpr I think you could wire your title formatting logic here? Just wondering if you still need this once the 2 linked issues are both implemented?

[slorber]

FYI the PR of @besemuna here #4500

Allows to declare the sidebar label of a doc through sidebars.js instead of using sidebars_label: My Label frontmatter.

Does not allow (on purpose) to override the doc title frontmatter that will be used in page/document heading/title.

So, not sure it will solve any of your pain points, but still think it's useful to add this.