docs: add advanced guides #6296
Conversation
Josh-Cena
added
the
pr: documentation
|
✔️ [V2] 🔨 Explore the source changes: cf3e619 🔍 Inspect the deploy log: https://app.netlify.com/sites/docusaurus-2/deploys/61ef6b09f663210007f7b4f8 😎 Browse the preview: https://deploy-preview-6296--docusaurus-2.netlify.app |
|
⚡️ Lighthouse report for the changes in this PR:
Lighthouse ran on https://deploy-preview-6296--docusaurus-2.netlify.app/ |
|
Size Change: +4.39 kB (+1%) Total Size: 715 kB
ℹ️ View Unchanged
|
|
We certainly beat VuePress for the architecture schematic! 😄 https://deploy-preview-6296--docusaurus-2.netlify.app/docs/advanced/architecture/ |
|
|
||
| Docusaurus' routing system follows single-page application conventions: one route, one component. In this section, we will begin by talking about routing within the three content plugins (docs, blog, and pages), and then go beyond to talk about the underlying routing system. | ||
|
|
||
| ## Routing in content plugins |
There was a problem hiding this comment.
this section is nice, it should probably not be in the advanced part?
There was a problem hiding this comment.
The rationale is to put all "meta-level" instructions in the advanced part. The "guides" part are more like a step-by-step instruction of "how to make X happen" rather than "how does X happen". I would probably re-organize the advanced guides again in the future to make it more progressive.
|
|
||
| ## Generating and accessing routes | ||
|
|
||
| The `addRoute` lifecycle action is used to generate routes. It registers a piece of route config to the route tree, giving a route, a component, and props that the component needs. The props and the component are both provided as paths for the bundler to `require`, because as explained in the [architecture overview](architecture.md), server and client only communicate through temp files. |
There was a problem hiding this comment.
I wouldn't use the term "temp files" but rather "generated files"
|
|
||
| At this point, you probably have a big `docusaurus.config.js` already😄 However, you haven't written much code yet! Most of the features are implemented through calling encapsulated Docusaurus APIs. As you continue your journey, you can take three paths: | ||
|
|
||
| - Learn more advanced Docusaurus concepts. This will help you gain a deeper understand of what the APIs do. |
There was a problem hiding this comment.
how do we link to the advanced section? 🤪
There was a problem hiding this comment.
Mmm, I definitely planned to do that, probably forgot before the merge...
| @@ -0,0 +1,17 @@ | |||
| # Routing | |||
There was a problem hiding this comment.
not sure to understand the purprose of this file, is it just temporary until the next releases?
There was a problem hiding this comment.
Yes, because I want to allow readers to switch between versions and understand how the same page looks like across versions....
|
|
||
| import React from 'react'; | ||
| import {useColorMode} from '@docusaurus/theme-common'; | ||
| import BasicZoom from 'react-medium-image-zoom'; |
There was a problem hiding this comment.
this seems to load quite a few extra deps, see lockfile
what about using an existing docusaurus plugin instead?
https://github.com/flexanalytics/plugin-image-zoom
https://github.com/gabrielcsapo/docusaurus-plugin-image-zoom
this could apply to all site images automatically and also be nice to dogfood community plugins
|
Great improvements, thanks a lot for that 👍 I think some parts of those docs are not so advanced and should be moved to guides (like basic routing and swizzling) but we'll do that later. |
|
I do have some opinions about making the "Guides" section maximally approachable. Swizzling inevitably involves writing React code while routing involves more explanations than instructions. I'd want the guides section to only contain instructions on "how do I do X" through a well-defined Docusaurus API |
Motivation
Close #6236
Close #4301
Have you read the Contributing Guidelines on pull requests?
Yes