mirror of
https://github.com/facebook/docusaurus.git
synced 2025-06-05 04:12:53 +02:00
docs(v2): misc update
This commit is contained in:
Yangshun Tay
parent
37bccf5668
commit
1d968be5bb
4 changed files with 54 additions and 39 deletions
|
|
@ -23,7 +23,7 @@ To publish in the blog, create a file within the blog directory with a formatted
|
|||
|
||||
For example, at `my-website/blog/2019-09-05-hello-docusaurus-v2.md`:
|
||||
|
||||
```yml
|
||||
```md
|
||||
---
|
||||
title: Welcome Docusaurus v2
|
||||
author: Dattatreya Tripathy
|
||||
|
|
@ -33,8 +33,7 @@ authorTwitter: CuriousDT
|
|||
tags: [hello, docusaurus-v2]
|
||||
---
|
||||
|
||||
Welcome to this blog. This blog is created with [**Docusaurus 2 alpha**]
|
||||
(https://v2.docusaurus.io/).
|
||||
Welcome to this blog. This blog is created with [**Docusaurus 2 alpha**](https://v2.docusaurus.io/).
|
||||
|
||||
<!--truncate-->
|
||||
|
||||
|
|
@ -57,7 +56,7 @@ The only required field is `title`; however, we provide options to add author in
|
|||
|
||||
Use the `<!--truncate-->` marker in your blog post to represent what will be shown as the summary when viewing all published blog posts. Anything above `<!--truncate-->` will be part of the summary. For example:
|
||||
|
||||
```yml
|
||||
```md
|
||||
---
|
||||
title: Truncation Example
|
||||
---
|
||||
|
|
@ -79,9 +78,11 @@ Or this.
|
|||
|
||||
### Blog-only mode
|
||||
|
||||
You can run your Docusaurus 2 site without a landing page and instead have your blog's post list page as the index page. Set the `routeBasePath` to be `'/'` to indicate it's the root path. Make sure there's no `index.js` page in `src/pages` or else there could be a conflict of paths!
|
||||
You can run your Docusaurus 2 site without a landing page and instead have your blog's post list page as the index page. Set the `routeBasePath` to be `'/'` to indicate it's the root path.
|
||||
|
||||
```diff
|
||||
**Note:** Make sure there's no `index.js` page in `src/pages` or else there will be two files mapping to the same route!
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
module.exports = {
|
||||
// ...
|
||||
|
|
@ -91,7 +92,7 @@ module.exports = {
|
|||
{
|
||||
blog: {
|
||||
path: './blog',
|
||||
+ routeBasePath: '/',
|
||||
routeBasePath: '/', // Set this value to '/'.
|
||||
},
|
||||
},
|
||||
],
|
||||
|
|
@ -99,7 +100,6 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
|
||||
<!--
|
||||
|
||||
Adding a blog using the blog plugin.
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ This doc guides you through migrating an existing Docusaurus 1 site to Docusauru
|
|||
└── static
|
||||
```
|
||||
|
||||
## Step 1 - Update `package.json`
|
||||
## Update `package.json`
|
||||
|
||||
### Scoped package names
|
||||
|
||||
|
|
@ -88,7 +88,7 @@ A typical Docusaurus 2 `package.json` may look like this:
|
|||
}
|
||||
```
|
||||
|
||||
## Step 2 - Migrate `siteConfig` to `docusaurus.config.js`
|
||||
## Migrate `siteConfig` to `docusaurus.config.js`
|
||||
|
||||
Rename `siteConfig.js` to `docusaurus.config.js`. In Docusaurus 2, we split each functionality (blog, docs, pages) into plugins for modularity. Presets are bundles of plugins and for backward compatibility we built a `@docusaurus/preset-classic` preset which bundles most of the essential plugins present in Docusaurus 1.
|
||||
|
||||
|
|
@ -103,9 +103,9 @@ module.exports = {
|
|||
'@docusaurus/preset-classic',
|
||||
{
|
||||
docs: {
|
||||
// docs folder path relative to site dir.
|
||||
// docs folder path relative to website dir.
|
||||
path: '../docs',
|
||||
// sidebars file relative to site dir.
|
||||
// sidebars file relative to website dir.
|
||||
sidebarPath: require.resolve('./sidebars.json'),
|
||||
},
|
||||
...
|
||||
|
|
@ -357,7 +357,7 @@ The following fields are all deprecated, you may remove from your configuration
|
|||
|
||||
We intend to implement many of the deprecated config fields as plugins in future. Help will be appreciated!
|
||||
|
||||
## Step 3 - Delete footer file
|
||||
## Delete footer file
|
||||
|
||||
`website/core/Footer.js` is no longer needed. If you want to modify the default footer provided by docusaurus, [swizzle](using-themes.md#swizzling-theme-components) it:
|
||||
|
||||
|
|
@ -367,13 +367,23 @@ yarn swizzle @docusaurus/theme-classic Footer
|
|||
|
||||
This will copy the current `<Footer />` component used by the theme to a `src/theme/Footer` directory under the root of your site, you may then edit this component for customization.
|
||||
|
||||
## Step 4 - Update your page files
|
||||
## Update your page files
|
||||
|
||||
Please refer to [creating pages](creating-pages.md) to learn how Docusaurus 2 pages work. After reading that, you can notice that we have to move `pages/en` files in v1 to `src/pages` instead.
|
||||
|
||||
`CompLibrary` is deprecated in v2, so you have to write your own React component or use Infima styles (Docs will be available soon, sorry about that! In the meanwhile, inspect the V2 website to see what styles are available).
|
||||
|
||||
## Step 5 - Modify `.gitignore`
|
||||
## Update your docs
|
||||
|
||||
### Update syntax
|
||||
|
||||
In Docusaurus 2, the markdown syntax has been changed to [MDX](https://mdxjs.com/). Hence there might be some broken syntax in the existing docs which you would have to update. A common examples is that self-closing tags like `<img>` and `<br>` would have to be explicitly closed now: `<img/>` and `<br/>`. The tags have to be valid JSX.
|
||||
|
||||
### Language-specific Code Tabs
|
||||
|
||||
Not yet supported. Stay tuned.
|
||||
|
||||
## Modify `.gitignore`
|
||||
|
||||
The `.gitignore` in your `website` should contain:
|
||||
|
||||
|
|
@ -400,7 +410,7 @@ yarn-debug.log*
|
|||
yarn-error.log*
|
||||
```
|
||||
|
||||
## Step 6 - Test your site
|
||||
## Test your site
|
||||
|
||||
After migration, your folder structure should look like this:
|
||||
|
||||
|
|
@ -428,6 +438,10 @@ cd website
|
|||
yarn start
|
||||
```
|
||||
|
||||
## Step 7 - Configure your build directory
|
||||
## Configure your `build` directory
|
||||
|
||||
In Docusaurus 1, all the build artifacts are located within `website/build/<PROJECT_NAME>`. However, in Docusaurus 2, it is now moved to just `website/build`. Make sure that you update your deployment configuration to read the generated files from the correct `build` directory.
|
||||
|
||||
## Support
|
||||
|
||||
For any questions, you can ask in the [`#docusaurus-1-to-2-migration` Discord channel](https://discordapp.com/invite/kYaNd6V). Feel free to tag us ([@yangshun](https://github.com/yangshun) and [@endiliey](https://github.com/endiliey)) in any migration PRs if you would like us to have a look.
|
||||
|
|
|
|||
|
|
@ -33,8 +33,8 @@ A sidebar object looks like the following. The key `docs` is the name of the sid
|
|||
module.exports = {
|
||||
docs: {
|
||||
'Getting started': ['greeting'],
|
||||
'Docusaurus': ['doc1'],
|
||||
}
|
||||
Docusaurus: ['doc1'],
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
|
|
@ -47,20 +47,21 @@ module.exports = {
|
|||
{
|
||||
type: 'category',
|
||||
label: 'Getting Started',
|
||||
items: ['greeting']
|
||||
items: ['greeting'],
|
||||
},
|
||||
{
|
||||
type: 'category',
|
||||
label: 'Docusaurus',
|
||||
items: ['doc1']
|
||||
items: ['doc1'],
|
||||
},
|
||||
]
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
You can also have multiple sidebars for different Markdown files by adding more top-level keys to the exported object.
|
||||
|
||||
Example:
|
||||
|
||||
```js
|
||||
// sidebars.js
|
||||
module.exports = {
|
||||
|
|
@ -70,7 +71,7 @@ module.exports = {
|
|||
secondSidebar: {
|
||||
'Category A': ['doc2'],
|
||||
'Category B': ['doc3'],
|
||||
}
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
|
|
@ -90,12 +91,13 @@ website # root directory of your site
|
|||
|
||||
However, the last part of the `id` can be defined by user in the frontmatter. For example, if `guide/hello.md` content is defined as below, it's final `id` is `guide/part1`.
|
||||
|
||||
```md
|
||||
---
|
||||
id: part1
|
||||
---
|
||||
Lorem ipsum
|
||||
```
|
||||
```md
|
||||
---
|
||||
id: part1
|
||||
---
|
||||
|
||||
Lorem ipsum
|
||||
```
|
||||
|
||||
## Sidebar item
|
||||
|
||||
|
|
@ -120,7 +122,7 @@ Sidebar item type that links to a doc page. Example:
|
|||
Using just the [Document ID](#document-id) is perfectly valid as well, the following is equivalent to the above:
|
||||
|
||||
```js
|
||||
'doc1' // string - document id
|
||||
'doc1'; // string - document id
|
||||
```
|
||||
|
||||
Note that using this type will bind the linked doc to current sidebar, this means that if you access `doc1` page, the sidebar displayed will be the sidebar this item is on. For below case, `doc1` is bounded to `firstSidebar`.
|
||||
|
|
@ -134,11 +136,10 @@ module.exports = {
|
|||
secondSidebar: {
|
||||
'Category A': ['doc2'],
|
||||
'Category B': ['doc3'],
|
||||
}
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
|
||||
### Link
|
||||
|
||||
Sidebar item type that links to a non-document page. Example:
|
||||
|
|
|
|||
|
|
@ -50,7 +50,7 @@ When you `init` your Docusaurus 2 project, the website will be generated with ba
|
|||
}
|
||||
```
|
||||
|
||||
In future, we will provide an easier way to generate the different shades of colors.
|
||||
Infima uses 7 shades of each color. We recommend using [ColorBox](https://www.colorbox.io/) to find the different shades of colors for your chosen primary color. In future, we will provide an easier way to generate the different shades of colors.
|
||||
|
||||
<!-- TODO need more refinement here -->
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue