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

fix(v2): deprecate docs homePageId in favor of frontmatter "slug: /" (#3228)

Browse source 
* homePageId => deprecated

* docs prettier
This commit is contained in:
Sébastien Lorber 2020-08-06 18:31:50 +02:00 • committed by GitHub
parent 0079f0e8d1
commit 0a33a52301
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
25 changed files with 109 additions and 79 deletions
Download patch file Download diff file Expand all files Collapse all files

76
website/docs/docs.md
View file

@ -39,42 +39,27 @@ slug: part1.html
Lorem ipsum
```
## Home page docs
Using the `homePageId` property, you can create a home page of your docs. To do this, you can create a new document, especially for this purpose with the id as `_index`, or you could specify an existing document id.
```js {8} title="docusaurus.config.js"
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
homePageId: 'getting-started', // Defaults to `_index`
// ...
},
},
],
],
// ...
};
```
Given the example above, now when you navigate to the path `/docs` you will see that the document content with id is `getting-started`. This functionality also works for docs with versioning enabled. Importantly, with document serves as home docs page, it will not be available at its URL. Following the example above, this means that the `docs/getting-started` URL will be lead to a 404 error.
:::important
The document id of `_index` is reserved exclusively for the home doc page, so it will not work as a standalone route. If left to the default, the page will not show a sidebar. If you wish to have a sidebar for this page, specify the document id that is listed in the sidebar file.
:::
:::note
The page `docs` that you created (eg. `src/pages/docs.js`) will take precedence over the route generated via the `homePageId` option.
It is possible to use:
- absolute slugs: `slug: /mySlug`, `slug: /`...
- relative slugs: `slug: mySlug`, `slug: ./../mySlug`...
:::
## Home page docs
If you want a document to be available at the root, and have a path like `https://v2.docusaurus.io/docs/`, you can use the slug frontmatter:
```yml
---
id: my-home-doc
slug: /
---
Lorem ipsum
```
## Sidebar
To generate a sidebar to your Docusaurus site, you need to define a file that exports a sidebar object and pass that into the `@docusaurus/plugin-docs` plugin directly or via `@docusaurus/preset-classic`.
@ -327,34 +312,7 @@ module.exports = {
If you only want the documentation feature, you can run your Docusaurus 2 site without a landing page and display your documentation page as the index page instead.
To enable docs-only mode, set the `routeBasePath` property of the `docs` object to the root of your site. Also, set the `homePageId` property to the ID of the document that you wish to show by default.
:::note
More details on functionality of home page for docs can be found in [appropriate section](#home-page-docs).
:::
```js {8-9} title="docusaurus.config.js"
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: {
routeBasePath: '/', // Set this value to '/'.
homePageId: 'getting-started', // Set to existing document id.
// ...
},
},
],
],
// ...
};
```
Now, when visiting your site, it will show your initial document instead of a landing page.
To enable docs-only mode, set the docs plugin `routeBasePath: '/'`, and use the frontmatter `slug: /` on the document that should be the index page ([more infos](#home-page-docs)).
:::caution