3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-05-25 15:07:17 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs: elaborate on "docs-only" and "blog-only" (#6131)

Browse source 
* rephrased documentation

* Rewording

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
This commit is contained in:
Himanshu 2021-12-20 06:59:43 +05:30 • committed by GitHub
parent 638a171673
commit c0a99786b3
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 91 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

81
website/docs/guides/docs/docs-introduction.md
View file

@ -22,7 +22,7 @@ For example, `greeting.md` id is `greeting` and `guide/hello.md` id is `guide/he
```bash
website # Root directory of your site
└── docs
   ├── greeting.md
├── greeting.md
└── guide
└── hello.md
```
@ -69,16 +69,89 @@ Lorem ipsum
## Docs-only mode {#docs-only-mode}
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.
A freshly initialized Docusaurus site has the following structure:
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 info](#home-page-docs)).
```
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 it at the root?
Assume that you have the following in your configuration:
```js title="docusaurus.config.js"
module.exports = {
// ...
presets: [
'@docusaurus/preset-classic',
{
docs: {
/* docs plugin options */
},
blog: {
/* blog plugin options */
},
// ...
},
],
};
```
To enter docs-only mode, change it to like this:
```js title="docusaurus.config.js"
module.exports = {
// ...
presets: [
'@docusaurus/preset-classic',
{
docs: {
// highlight-next-line
routeBasePath: '/', // Serve the docs at the site's root
/* other docs plugin options */
},
// highlight-next-line
blog: false, // Optional: disable the blog plugin
// ...
},
],
};
```
Note that you **don't necessarily have to give up on using 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:
```yml title="docs/intro.md"
---
# highlight-next-line
slug: /
---
This page will be the home page when users visit https://example.com/.
```
:::caution
You should delete the existing homepage at `./src/pages/index.js`, or else there will be two files mapping to the same route!
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](../../blog.mdx#blog-only-mode).