docusaurus: inject 'slug: /' in api/index.md

[felipecrs]

Since homePageId: "api/index" is deprecated, the docs/api/index.md should contain a new header:

---
slug: /
---

The docs plugin option homePageId=api/index is deprecated. To make a doc the "home", prefer frontmatter: "slug: /"

[tgreyuk]

ok thanks will have a look at this.

[tgreyuk]

@felipecrs fixed in 0.2.0

[felipecrs]

I see that now, api/index has the slug: "/api". It makes sense, but what if the user wanted to use the api/index as the homepage (slug: "/")?

I worked around it by implementing my own README.md to index.md generation, there would be many fields that the user would like to customize if you give them this option, so I'm not sure if new options to customize the readme in this plugin is really needed.

In any case, if in the future this feature gets implemented (facebook/docusaurus#3475), we will be in business anyway.

[tgreyuk]

I see. I suppose we could provide another option indexSlug or something that defaults to /api. I will leave this open for now.

[felipecrs]

I see. I suppose we could provide another option indexSlug or something that defaults to /api. I will leave this open for now.

Beyond that, I would need to disable the api/index inclusion in the typedoc-sidebar.js, so I can put it in another category. Again, not sure if we should go that further in the customizations or not, I would like to hear more opinions.

[tgreyuk]

Would quite like to bottom this one out. Not sure if this will be an issue after #202 / #203 ?

[felipecrs]

Good point. In fact, after #203, I would need a new option: readmeSlug: '/', otherwise I wouldn't be able to make it my homepage.

[felipecrs]

Also, just to you know, I tried to make docusaurus use the typedoc-sidebar.js just for testing, and it fails:

$ docusaurus start
Starting the development server...
Info: Loaded plugin typedoc-plugin-markdown
Info: TypeDoc sidebar written to /home/felipesantos/repos/megatar/website/typedoc-sidebar.js
Generated 7 of 7 TypeDoc docs
Info: Documentation generated at /home/felipesantos/repos/megatar/docs/api
Error: Error loading {"type":"category","collapsed":true,"label":"0","items":"a"}. "items" must be an array.
    at assertIsCategory (/home/felipesantos/repos/megatar/node_modules/@docusaurus/plugin-content-docs/lib/sidebars.js:51:15)
    at normalizeItem (/home/felipesantos/repos/megatar/node_modules/@docusaurus/plugin-content-docs/lib/sidebars.js:91:13)
    at arrayMap (/home/felipesantos/repos/megatar/node_modules/lodash.flatmap/index.js:140:21)
    at map (/home/felipesantos/repos/megatar/node_modules/lodash.flatmap/index.js:1928:10)
    at Object.flatMap [as default] (/home/felipesantos/repos/megatar/node_modules/lodash.flatmap/index.js:1881:22)
    at normalizeSidebar (/home/felipesantos/repos/megatar/node_modules/@docusaurus/plugin-content-docs/lib/sidebars.js:114:36)
    at /home/felipesantos/repos/megatar/node_modules/lodash/lodash.js:13469:38
    at /home/felipesantos/repos/megatar/node_modules/lodash/lodash.js:4967:15
    at baseForOwn (/home/felipesantos/repos/megatar/node_modules/lodash/lodash.js:3032:24)
    at Function.mapValues (/home/felipesantos/repos/megatar/node_modules/lodash/lodash.js:13468:7)
    at normalizeSidebars (/home/felipesantos/repos/megatar/node_modules/@docusaurus/plugin-content-docs/lib/sidebars.js:117:21)
    at Object.loadSidebars (/home/felipesantos/repos/megatar/node_modules/@docusaurus/plugin-content-docs/lib/sidebars.js:132:12)
    at loadVersion (/home/felipesantos/repos/megatar/node_modules/@docusaurus/plugin-content-docs/lib/index.js:98:45)
    at Array.map (<anonymous>)
    at Object.loadContent (/home/felipesantos/repos/megatar/node_modules/@docusaurus/plugin-content-docs/lib/index.js:150:68)
    at /home/felipesantos/repos/megatar/node_modules/@docusaurus/core/lib/server/plugins/index.js:55:59

This doesn't affect me as I'm using my own sidebars.js.

[felipecrs]

Hey @tgreyuk, I just saw something at Docusaurs and I wanted to let you know:

facebook/docusaurus#4485

Also, news at sidebars is incoming:

facebook/docusaurus#3464 (comment)

[tgreyuk]

Thanks for heads-up @felipecrs

[tgreyuk]

@felipecrs Can we close this ticket?

[samrith-s]

Idk what I'm doing wrong, but I get the slug as something weird:

slug: "//Users/samrith.shankar/Work/projects/concurrent-tasks/website/docs/api"

Because of this Docusaurus won't start. Any leads?

[tgreyuk]

I think this was because of changes in typedoc 0.21. If you try again with latest version it should work.

[edew]

Hey @tgreyuk

Perhaps this is a separate issue but it would be great if we could specify the slug we want to use in index.md ourselves though a configuration option.

Would you be open to that?

[tgreyuk]

@edew yeah could provide an indexSlug option or something. will have a look.

[tgreyuk]

indexSlug option available will simply replace the slug value in index.md.

As for the original ticket the feature does appear to be doable as per facebook/docusaurus#3475 .