Docusaurus for docs-only sites

[borekb]

I've been looking for a system to publish our Markdown documents and Docusaurus looks really nice. However, it currently seems to be targeted on "project websites" where the base URL (docs.example.com) hosts a front page and the docs live in the /docs subfolder. There might be workaround like using only the /build/docs folder after build-time but it would be really great to see first-class support for docs-only sites as well.

Some things that I'd like to see in Docusaurus if it supported this use case:

• New docusaurus-init mode that generates docs-only site.
• Such site doesn't contain any frontpage or blog or anything else. The /docs folder is the root of the site and when I visit docs.example.com, I directly see the rendered /docs/index.md document.
  • (The docs are not at docs.example.com/docs.)
• There should be a React template for the docs pages, similarly to what exists today for custom pages.
• There should be an on-page navigation (ToC) for longer documentation articles (some docs systems use the right sidebar, for example).

[AlanFoster]

This seems like a similar request to: #416

[JoelMarcey]

@ericnakagawa - you did this with your personal blog, didn't you?

[richardzcode]

Take this gist as index.js: https://gist.github.com/richardzcode/d0fcb3a98e60528340175aa5168835bb

It assumes you have a ../README.md file. If not then just modify the file path.

[nadeemkhedr]

How would you render a markdown file + the docs sidebar, I can see DocsSidebar requires metadata, which i am not sure how to access

[Happy-Ferret]

Just a heads-up, but BlueWhale seems to do what the OP asked for.

Although how, I have yet to investigate. Probably during the build step?

[JoelMarcey]

@Happy-Ferret So the way we solved it for BlueWhale, which I don't think is a horrible solution, is to do a redirect from index.html to the first docs page.

https://github.com/facebookresearch/BlueWhale/blob/docs/website/static/index.html

[ericnakagawa]

I support BlueWhale's solution.

[novalagung]

I ended up doing this: No changes on the docusaurus project at all. But after yarn build, I move everything inside website/build/your-site/docs into website/build/your-site, then adjust the sidebar link. Everything is being done programatically.

[mrchess]

Bluewhale solution doesn't work with Netlify.

EDIT: Nevermind, it does. You need to remove index.js.

[ktutnik]

Everyone still having this issue, its already documented here

[tuler]

The redirect solution still leaves you with a docs.example.com/docs URL instead of just docs.example.com. @novalagung can you elaborate on your solution, specially the sidebar link adjustment.

[pcowgill]

In v2 of this project it would be great to have suppport for docs-only or blog-only versions of the classic init config

[MSanjaySharma]

Check Out Docs-only mode in the official Documentation of Docusaurus.