Cannot add a custom page to the sidebar

[michaelw85]

🐛 Bug Report

Cannot register a custom page in the sidebar and cannot display the sidebar on a custom page.

Have you read the Contributing Guidelines on issues?

yes

To Reproduce

1. Create a custom page using react in doc/pages/en e.g. custom-page.js
2. Add newly created page to sidebars.json

   {
   "docs": {
   "Custom page": ["custom-page"]
   }
   }

3. run docusaurus

I've tried adding filename, filename.js, { page: 'filename', label: 'filename' } and en/filename.js none seem to work.

Expected behavior

Being able to add a custom page similar to any other markdown page with the only difference the content is written using react.

Actual Behavior

Page can be visited via direct url or by adding to the primary navigation but is not visible in sidebar on other pages and never shows the sidebar when visiting the page.

Reproducible Demo

See description in "To Reproduce". This can be done on a any existing Docusaurus setup or newly created one.

[amimas]

I don't think this is available in V1. To my knowledge, the sidebar is specifically used for docs. Custom js pages are not meant to be used for serving docs. That would kinda defeat the purpose of docusaurus.

If you are looking to add react components into your markdown docs, I believe that feature is expected to be available in V2.

[michaelw85]

I don't understand why a custom page is not meant for serving docs. Docusaurus sole purpose is to write documentation which can be done in 3 ways, using markdown, static html and react which all become a html document that will be served. Since all methods result in html I don't see the difference and do not understand why one method should be considered different by design.

To give you a better understanding why I'm looking to include a custom page in the sidebar. I'm working on a component library and use Docusaurus to show options and live previews of the components which until now is done with MD. One of the components is an icon for which I've created a page listing all available svg's with a simple input filter to be able to find the icon you want to use.

As a work around I'm thinking about creating a remarkable extension embedding the page in markdown since without listing it in a sidebar it will still be available on its own url. I'm doing something similar to be able to show live previews of my component.

[amimas]

Docusaurus sole purpose is to write documentation which can be done in 3 ways, using markdown, static html and react which all become a html document that will be served.

In my opinion the docusaurus is meant for writing documentation that is is easy to maintain and it does that using markdown files only. With some knowledge of markdown, even non-programmers can keep producing documents and maintain it if they Docusaurus setup for them.

I'm not saying your use case is invalid. I'm simply trying to justify that the docs are supposed to revolve around markdown files. Besides, as I mentioned already, most likely in V2 you'll be able to inject react components into your markdown files. The maintainers of Docusarus will be able to confirm.

[michaelw85]

I agree the preferred way is to use Markdown. It's just a bit of an edge case I guess although any style guide would have a page similar to mine. Another use case would be the typical list of color swatches.

Can I conclude that if I would offer this as a PR it would be rejected? If so I will focus on a work around in my own setup for now and will see what happens in V2.

[amimas]

Can I conclude that if I would offer this as a PR it would be rejected?

@endiliey @yangshun ☝️

[endiliey]

Hmm.. interesting discussion. Tbh what @amimas said is right, Custom js pages are not meant to be used for serving docs.

It is also safe to assume that it will be better not to send a PR for it as it will most likely won't be a small change and it will most likely be rejected. The hardest part is revolving around versioning and translation. We don't version pages in v1.

Anyway. we are close to roll out docusaurus v2 alpha publicly soon just to maximize community participation feedback. This upcoming alpha is of course not the final v2.0.0 version but I think it's a good idea to let people test the minimal version of it soon.

Here's an example site build with docusaurus 2. Notice how we let you customize the layout to the max level. Pretty much everything https://endiliey.com/

I'm going to close this out issue and marking it as wontfix

[michaelw85]

@amimas @endiliey Thanks for the feedback and healthy discussion, much appreciated!

[avoliva]

Here's an example site build with docusaurus 2. Notice how we let you customize the layout to the max level. Pretty much everything https://endiliey.com/

Why is Chrome saying this link is unsafe?

[yangshun]

That domain name is no longer active. Please refer to other available v2 sites.