Documentation and Examples for Static Site Generation (SSG)

[1mamute]

Hello, coming from a NextJS background and not being an expert in react hooks, I'm having some confusion trying to set up Static Side Generation using Server Side hooks. My markdown files are stored in a CMS and I would like to generate the static pages at build time.

I found NextJS server-side methods are well documented (getInitialProps, getStaticProps, getStaticPaths, getServerSideProps) and easy to learn. I think this could be done with Docusaurus as well.

The following informations is what i gathered in research but still didn't manage to implement myself:

• rdilweb/docusaurus-plugin-remote-content
• docs/lifecycle-apis#async-loadcontent
• docs/lifecycle-apis#async-contentloadedcontent-actions
• docs/creating-pages#routing
• Issue Dynamic Routes and Data Fetching #4710

📚 Documentation

Can we, please, have:

• A clear, concise documentation on how to generate static pages from data that's not available at build time.
• A bunch of examples (maybe a docs page dedicated to it!)
• Compare and show the differences with other static generator like CRA, NextJS and Gatsby (this would help a lot for people that are transitioning like me)

[slorber]

Docusaurus focus mostly on the docs use case, considering that your docs are available on the filesystem at build time.

However, it technically remains a generic SSG, and is similar to Gatsby without the GraphQL data layer.
We have an addRoute() plugin API that is quite similar to Gatsby's createPage()

If you want to integrate with a CMS, it is probably not the best choice currently (at least we don't have very good doc to help you figure this out).

We'll definitively try to improve our APIs and doc on that, but keep in mind Docusaurus does not aim to be a better generic SSG than Next or Gatsby, so if your main use-case is to integrate with CMSes and not build doc sites based on git markdown files, you'd better not use Docusaurus in the first place.

[1mamute]

@slorber Thank you for clarifying.

(...) so if your main use-case is to integrate with CMSes and not build doc sites based on git markdown files, you'd better not use Docusaurus in the first place.

Just to show that building the docs from a remote source is still a recurrent question for me, either integrating with a CMS or with remote documentation files:

There's a second project that i'm part of, the documentation in this case is indeed markdown files. Part of the documentation lives inside each applications repository and part of it are in a centralized gitlab wiki (it uses gollum git wiki under the hood).

Docusaurus lives in a separated repository and i'm struggling to come with a way to fetch all the docs file during development/build files.

Is there any better way of doing this besides using git submodules?

[slorber]

Docusaurus lives in a separated repository and i'm struggling to come with a way to fetch all the docs file during development/build files.
Is there any better way of doing this besides using git submodules?

Docusaurus does not care about what you use, as long as it's able to see the files at the correct file-system location when using start/build.

I can't really tell you what is the best way to "fetch" your docs, using git, rsync, ssh, cp, mv, curl, wget, unzip or whatever you want is the same for Docusaurus.

If we build something for CMS integration, it's more likely to be a way to fetch/cache the data using an async callback as part of a content plugin. Not sure it would solve your use-case anyway if your source is already markdown files.

[1mamute]

Thank you, I'll try to find a way to see what works best for my use-case.

If we build something for CMS integration, it's more likely to be a way to fetch/cache the data using an async callback as part of a content plugin. Not sure it would solve your use-case anyway if your source is already markdown files.

That would be really great!

Should we keep this issue open so we can gather more feedback if other users are having the same doubts?

[slorber]

We can keep this open until I document better how Docusaurus can be used as a less opinionated SSG, in a similar way to Gatsby

[slorber]

This is an old issue and I think we improved our documentation regarding plugins creation, lifecycles etc...

Also things are going to change deeply once we introduce React Server Components (#9089). I think we can close it for now and imporve our docs even more once we implement RSCs