From f40dc3138105cfbe56d02b1f2a43daec9128f472 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Sat, 28 May 2022 21:24:01 +0800 Subject: [PATCH] docs: multiple documentation elaborations (#7519) --- website/docs/advanced/ssg.md | 4 +- website/docs/api/docusaurus.config.js.md | 10 +- website/docs/blog.mdx | 2 +- website/docs/guides/docs/docs-create-doc.mdx | 132 ++++++++++++------ website/docs/guides/docs/docs-introduction.md | 74 +--------- .../markdown-features-intro.mdx | 16 +++ 6 files changed, 123 insertions(+), 115 deletions(-) diff --git a/website/docs/advanced/ssg.md b/website/docs/advanced/ssg.md index 0a394f9179b4..dbd104d78a95 100644 --- a/website/docs/advanced/ssg.md +++ b/website/docs/advanced/ssg.md @@ -8,12 +8,14 @@ description: Docusaurus statically renders your React code into HTML, allowing f In [architecture](architecture.md), we mentioned that the theme is run in Webpack. But beware: that doesn't mean it always has access to browser globals! The theme is built twice: - During **server-side rendering**, the theme is compiled in a sandbox called [React DOM Server](https://reactjs.org/docs/react-dom-server.html). You can see this as a "headless browser", where there is no `window` or `document`, only React. SSR produces static HTML pages. -- During **client-side rendering**, the theme is compiled with standard React DOM, and has access to browser variables. CSR produces dynamic JavaScript. +- During **client-side rendering**, the theme is compiled to JavaScript that gets eventually executed in the browser, so it has access to browser variables. :::info SSR or SSG? _Server-side rendering_ and _static site generation_ can be different concepts, but we use them interchangeably. +Strictly speaking, Docusaurus is a static site generator, because there's no server-side runtime—we statically render to HTML files that are deployed on a CDN, instead of dynamically pre-rendering on each request. This differs from the working model of [Next.js](https://nextjs.org/). + ::: Therefore, while you probably know not to access Node globals like `process` ([or can we?](#node-env)) or the `'fs'` module, you can't freely access browser globals either. diff --git a/website/docs/api/docusaurus.config.js.md b/website/docs/api/docusaurus.config.js.md index d20d29d34c76..0b0a6ecf8832 100644 --- a/website/docs/api/docusaurus.config.js.md +++ b/website/docs/api/docusaurus.config.js.md @@ -425,7 +425,7 @@ module.exports = { ### `scripts` {#scripts} -An array of scripts to load. The values can be either strings or plain objects of attribute-value maps. The `