2020-09-20 09:15:50 +00:00
# Docusaurus Build
2020-11-27 12:45:16 +00:00
2022-08-17 09:07:32 +00:00
:warning: Docusaurus build is not maintained anymore. Please note we were using Docusaurus@1.14.7 at the time.
2020-09-20 09:15:50 +00:00
## My opinion
2020-11-27 12:45:16 +00:00
2020-09-20 09:15:50 +00:00
Docusaurus was quite though to setup. It goes too far for my need. It's certainly more suited for real project documentation.
### 😄 Good
2020-11-27 12:45:16 +00:00
2020-09-20 09:15:50 +00:00
- Default theme is nice
- It's possible to use React components
- Default theme got a footer
### 😕 Bad
2020-11-27 12:45:16 +00:00
2020-09-20 09:15:50 +00:00
- The new project boilerplate is too complicated. Would have prefer something simpler but extensible as I need it
- Search is only available using Algolia
### 😫 Ugly
2020-11-27 12:45:16 +00:00
2020-09-20 09:15:50 +00:00
- Didn't find a way not to have that `/docs/` base href
## How does it work?
2020-11-27 12:45:16 +00:00
2020-09-20 09:15:50 +00:00
Here is the built website architecture:
2020-11-27 12:45:16 +00:00
2020-09-20 09:15:50 +00:00
- [`website/package.json` ](./templates/website/package.json )
2020-11-27 12:45:16 +00:00
- To install docusaurus
2020-09-20 09:15:50 +00:00
- [`website/siteConfig.js` ](./templates/website/siteConfig.js )
2020-11-27 12:45:16 +00:00
- Main configuration
2020-09-20 09:15:50 +00:00
- [`website/sidebars.json` ](./templates/website/sidebars.json.handlebars )
2020-11-27 12:45:16 +00:00
- Construct sidebar architecture
2020-09-20 09:15:50 +00:00
- [`website/core/Footer.js` ](./templates/website/core/Footer.js )
2020-11-27 12:45:16 +00:00
- A React footer... I'm not even sure I can throw this one away
2020-09-20 09:15:50 +00:00
- [`website/static/index.html` ](./templates/website/static/index.html )
2020-11-27 12:45:16 +00:00
- The page the user accesses if he goes to `/` . It just redirects to `/docs/` ...
2020-09-20 09:15:50 +00:00
- `docs/readme.md`
2020-11-27 12:45:16 +00:00
- The main page content
2020-09-20 09:15:50 +00:00
All the other pages are markdown files that are carefully put under their folder (e.g. `docs/screenshot/disable-shadow.md` ). Assets are stored under the `docs/assets` folder.
2020-09-12 23:39:09 +00:00
I didn't implement internationalization as it requires the use of the [Crowdin ](https://crowdin.com ) SaaS solution and is [likely to change in v2 ](https://github.com/facebook/docusaurus/issues/3317 ).
2020-09-20 09:15:50 +00:00
There is a second build phase where Docusaurus generates the static website.
## Try locally
2020-11-27 12:45:16 +00:00
2020-09-20 09:15:50 +00:00
### 🏗 Install
```sh
yarn install
```
### 🚀 Usage
This will build the [defaults.yml file ](../../defaults.yml ) and run a Docusaurus server on http://localhost:3000/docs/. Sources of the website are available in the `dist` folder.
```sh
2020-10-05 17:15:23 +00:00
yarn start
2020-09-20 09:15:50 +00:00
```
### 🚧 Run unit tests
```sh
yarn test
```
