Docusaurus
Doc front matter fields
https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-front-matter
Link to another doc
[ESLint](javascript/eslint.md#setup)
[ESLint](/javascript/eslint.md#setup)
[ESLint](/javascript/eslint#setup)
All options produce the same link.
Important: when using the first option you need to add .md
, otherwise you get /dev/javascript/eslint#setup
instead of /javascript/eslint#setup
.
Sidebar
https://docusaurus.io/docs/sidebar
https://docusaurus.io/docs/sidebar/items
const sidebars = {
http: [
'http/http',
'http/https',
'http/cors',
'http/csp',
// There are 2 equivalent ways to make the sidebar label different than the front matter 'title'.
// 1) At the doc front matter set 'sidebar_label'.
// 2) Do this:
{
type: 'doc',
id: 'http/headers',
label: 'Headers',
},
// We can have external links:
{
type: 'link',
label: 'RFC 7231',
href: 'https://httpwg.org/specs/rfc7231.html',
},
],
}
Sidebar category with generated index
The generated index route will be /category/aws
, and the page is accessible by clicking the dropdown.
const sidebars = {
cloud: [
'cloud/cloud',
'cloud/kubernetes',
'cloud/terraform',
{
type: 'category',
label: 'AWS',
link: {
type: 'generated-index',
title: 'AWS',
description: 'Amazon Web Services',
},
collapsed: false,
items: [
'cloud/aws/aws', // Actual link to this page will be '/cloud/aws'
'cloud/aws/iam',
'cloud/aws/ec2',
'cloud/aws/s3',
],
},
'cloud/heroku',
],
}
Sidebar category shorthand syntax
https://docusaurus.io/docs/sidebar/items#category-shorthand
const sidebars = {
docs: {
Docusaurus: ['docs/doc1', 'docs/doc2', 'docs/doc3'],
Features: ['docs/mdx'],
'Docusaurus Tutorial': [
'docs/create-a-page',
'docs/create-a-document',
'docs/markdown-features',
],
},
}
Debug
http://localhost:3000/__docusaurus/debug
https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-debug
Routes
Routes panel: http://localhost:3000/__docusaurus/debug/routes
https://docusaurus.io/docs/advanced/routing
Upgrade
This is the message shown at the terminal when you do npm start
:
╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ │
│ Update available 2.2.0 → 2.4.1 │
│ │
│ To upgrade Docusaurus packages with the latest version, run the following command: │
│ `npm i @docusaurus/core@latest @docusaurus/preset-classic@latest @docusaurus/module-type-aliases@latest` │
│ │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
OLD This is the message shown at the terminal when you do yarn start
:
yarn run v1.22.19
$ BROWSER=none docusaurus start
╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ │
│ Update available 2.0.1 → 2.1.0 │
│ │
│ To upgrade Docusaurus packages with the latest version, run the following command: │
│ `yarn upgrade @docusaurus/core@latest @docusaurus/preset-classic@latest @docusaurus/module-type-aliases@latest` │
│ │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
You can also do:
yarn upgrade --latest @docusaurus/core @docusaurus/preset-classic @docusaurus/module-type-aliases
Also take a look at the other packages versions:
- https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-preset-classic/package.json
- https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-theme-classic/package.json
Styling
Uses Infima: https://infima.dev
https://docusaurus.io/docs/styling-layout
MDX
A component can be registered globally so that you don't have to import it on every .mdx file. See docs and this tweet.
Code blocks supported languages
https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/vendor/prism/includeLangs.js
https://docusaurus.io/docs/markdown-features/code-blocks#supported-languages
Server components
https://twitter.com/sebastienlorber/status/1598615824927002624
Releases
- beta 4 - twitter
- beta 5 - twitter
- You can now use
<head>
in .md files
- You can now use
- beta 6 - twitter
- blog/archive route
- beta 7 - twitter
- beta 10 - twitter
- Link a sidebar category to an auto-generated index page, eg https://deploy-preview-6076--docusaurus-2.netlify.app/docs/category/guides/
- Link a sidebar category to an existing markdown document
- beta 11, 12, 13 fix issues in 10 deps and bad npm publish
- beta 14 - twitter
- Simplified footer (if you don't have many links) - https://github.com/facebook/docusaurus/issues/6101
- beta 15 - twitter
- Option to auto-collapse sidebar categories as you click
- beta 16 - twitter
- Swizzling - https://docusaurus.io/docs/swizzling
- Breadcrumbs in docs (disabled in config.js with presets docs.breadcrumbs)
- Add arbitrary html elements to the docs sidebar like images, separators etc.
- beta 17 - twitter
- beta 18 - twitter
- beta 19 - twitter
- beta 20 - twitter
- Small release with fixes for beta 19
- beta 21 - twitter
- beta 22 - twitter
- 2.0.0-rc.1 - twitter
- 2.0.0 - Announcement - twitter - HN
- 2.1.0 - Announcement - twitter
- Allows to override hardcoded
<meta>
- Simple use
<DocCardList/>
, which can now be used in any document.DocCardList
"will display all the sidebar items of the parent category of the current document" source
- Allows to override hardcoded
- 2.2.0 - Announcement - twitter
- 2.3.0 - Announcement - twitter
- Nested alerts (admonitions)
- 2.4.0 - Announcement - twitter
- Sidebar item of type category or link can have description
- Use query string
?docusaurus-theme=dark
or?docusaurus-theme=light
to force mode