Docs Introduction
The docs feature provides users with a way to organize Markdown files in a hierarchical format.
info
Check the Docs Plugin API Reference documentation for an exhaustive list of options.
Document IDβ
Every document has a unique id
. By default, a document id
is the name of the document (without the extension) relative to the root docs directory.
For example, greeting.md
id is greeting
and guide/hello.md
id is guide/hello
.
website # Root directory of your site
βββ docs
βββ greeting.md
βββ guide
βββ hello.md
However, the last part of the id
can be defined by the user in the front matter. For example, if guide/hello.md
's content is defined as below, its final id
is guide/part1
.
---
id: part1
---
Lorem ipsum
Customizing doc URLsβ
By default, a document's URL location is its file path relative to the docs
folder. Use the slug
front matter to change a document's URL.
For example, suppose your site structure looks like this:
website # Root directory of your site
βββ docs
βββ guide
βββ hello.md
By default hello.md
will be available at /docs/guide/hello
. You can change its URL location to /docs/bonjour
:
---
slug: /bonjour
---
Lorem ipsum
slug
will be appended to the doc plugin's routeBasePath
, which is /docs
by default. See Docs-only mode for how to remove the /docs
part from the URL.
note
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://docusaurus.io/docs/
, you can use the slug front matter:
---
id: my-home-doc
slug: /
---
Lorem ipsum
Docs-only modeβ
A freshly initialized Docusaurus site has the following structure:
example.com/ -> generated from `src/pages/index.js`
example.com/docs/intro -> generated from `docs/intro.md`
example.com/docs/tutorial-basics/... -> generated from `docs/tutorial-basics/...`
...
example.com/blog/2021/08/26/welcome -> generated from `blog/2021-08-26-welcome/index.md`
example.com/blog/2021/08/01/mdx-blog-post -> generated from `blog/2021-08-01-mdx-blog-post.mdx`
...
All docs will be served under the subroute docs/
. But what if your site only has docs, or you want to prioritize your docs by putting them at the root?
Assume that you have the following in your configuration:
module.exports = {
// ...
presets: [
'@docusaurus/preset-classic',
{
docs: {
/* docs plugin options */
},
blog: {
/* blog plugin options */
},
// ...
},
],
};
To enter docs-only mode, change it to like this:
module.exports = {
// ...
presets: [
'@docusaurus/preset-classic',
{
docs: {
routeBasePath: '/', // Serve the docs at the site's root
/* other docs plugin options */
},
blog: false, // Optional: disable the blog plugin
// ...
},
],
};
Note that you don't necessarily have to give up on using the blog or other plugins; all that routeBasePath: '/'
does is that instead of serving the docs through https://example.com/docs/some-doc
, they are now at the site root: https://example.com/some-doc
. The blog, if enabled, can still be accessed through the blog/
subroute.
Don't forget to put some page at the root (https://example.com/
) through adding the front matter:
---
slug: /
---
This page will be the home page when users visit https://example.com/.
caution
If you added slug: /
to a doc to make it the homepage, you should delete the existing homepage at ./src/pages/index.js
, or else there will be two files mapping to the same route!
Now, the site's structure will be like the following:
example.com/ -> generated from `docs/intro.md`
example.com/tutorial-basics/... -> generated from `docs/tutorial-basics/...`
...
tip
There's also a "blog-only mode" for those who only want to use the blog feature of Docusaurus 2. You can use the same method detailed above. Follow the setup instructions on Blog-only mode.