3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-08-03 16:59:06 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs(v2): refactor docs for better outline and welcoming PRs (#1641)

Browse source 
* docs(v2): refactor docs for better outline and welcoming PRs

* docs(v2): update docs
This commit is contained in:
Wei Gao 2019-07-08 14:14:49 +08:00 • committed by Yangshun Tay
parent e5e085b33d
commit 95fde5f827
31 changed files with 435 additions and 253 deletions
Download patch file Download diff file Expand all files Collapse all files

26
website/docs/design-principles.md
View file

@ -3,14 +3,28 @@ id: design-principles
title: Design Principles
---
- Easy to learn but most things are still achievable by users, even if it takes them more code and more time to write. No abstractions beat bad abstractions, and we don't want users to have to hack around the wrong abstractions. Mandatory talk: Minimal API Surface Area
- Users won't feel overwhelmed when looking at the directory of a D2 project. It just makes sense and is easy to build on top of. Gatsby projects have a ton of config files - `gatsby-config.js`, `gatsby-node.js`, `gatsby-client.js`, which can look intimidating to beginners.
- We should not lock in our users to use our plugins or our CSS. Certain lower-level infra level stuff like React Loadable, React Router are fine, but not higher level ones, such as choice of Markdown engines, CSS frameworks, CSS methodology.
- The separations of concerns between each layer of our stack should be clear - well-abstracted and modular.
_This section is a work in progress._
TODO: Explain the principles that guide the development of Docusaurus.
- Easy to learn but most things are still achievable by users, even if it takes them more code and more time to write. Not having abstractions is better than having the wrong abstractions, and we don't want users to have to hack around the wrong abstractions. Mandatory talk - [Minimal API Surface Area](https://www.youtube.com/watch?v=4anAwXYqLG8)
- Intuitive project structure - users will not feel overwhelmed when looking at the project directory of a Docusaurus project. It should look intuitive and easy to build on top of.
- The separations of concerns between each layer of our stack (content/theming/styling) should be clear - well-abstracted and modular.
- Sensible defaults - Common and popular performance optimizations and configurations will be done for users but they are given the option to override them.
- No vendor-lock in - Users are not required to use the default plugins or CSS, although they are highly encouraged to. Certain lower-level infra level stuff like React Loadable, React Router are fine, but not higher level ones, such as choice of Markdown engines, CSS frameworks, CSS methodology.
#### References
## How Docusaurus Works
<!-- moved in from how Docusaurus works @yangshun -->
We believe that as devlopers, knowing how a library works is helpful in allowing us to become better at using it. Hence we're dedicating effort into explaining the architecture and various components of Docusaurus with the hope that users reading it will gain a deeper understanding of the tool and be even more proficient in using it.
<!--
Explain the principles that guide the development of Docusaurus.
References
---
- https://www.gatsbyjs.org/docs/behind-the-scenes/
- https://reactjs.org/docs/design-principles.html
- https://v1.vuepress.vuejs.org/miscellaneous/design-concepts.html
-->