15e73daae7
* doc components initial simplification
* doc components initial simplification
* add docContext test
* Add poc of global data system + use it in the theme
* Revert "doc components initial simplification"
This reverts commit f657b4c4
* revert useless changes
* avoid loosing context on docs switch
* fix docs tests
* fix @generated/globalData ts declaration / es import
* typo
* revert bad commit
* refactor navbar in multiple parts + add navbar item types validation + try to fix remaining merge bugs
* add missing watch mode for plugin debug
* fix docs global data integration, move related hooks to docs plugin + convert to TS
* change versions link label
* fix activeClassName react warning
* improve docs global data system + contextual navbar dropdown
* fix bug preventing the deployment
* refactor the global data system to namespace automatically by plugin name + plugin id
* proper NavbarItem comp
* fix tests
* fix snapshot
* extract theme config schema in separate file + rename navbar links to navbar items
* minor typos
* polish docs components/api
* polish useDocs api surface
* fix the docs version suggestions comp + data
* refactors + add docsClientUtils unit tests
* Add documentation
* typo
* Add check for duplicate plugin ids detection
* multi-instance: createData plugin data should be namespaced by plugin instance id
* remove attempt for multi-instance support
5.4 KiB
| id | title |
|---|---|
| blog | Blog |
Initial setup
To setup your site's blog, start by creating a blog directory.
Then, add a item link to your blog within docusaurus.config.js:
module.exports = {
themeConfig: {
// ...
navbar: {
items: [
// ...
// highlight-next-line
{to: 'blog', label: 'Blog', position: 'left'}, // or position: 'right'
],
},
},
};
Adding posts
To publish in the blog, create a file within the blog directory with a formatted name of YYYY-MM-DD-my-blog-post-title.md. The post date is extracted from the file name.
For example, at my-website/blog/2019-09-05-hello-docusaurus-v2.md:
---
title: Welcome Docusaurus v2
author: Joel Marcey
author_title: Co-creator of Docusaurus 1
author_url: https://github.com/JoelMarcey
author_image_url: https://graph.facebook.com/611217057/picture/?height=200&width=200
tags: [hello, docusaurus-v2]
description: This is my first post on Docusaurus 2.
image: https://i.imgur.com/mErPwqL.png
---
Welcome to this blog. This blog is created with [**Docusaurus 2 alpha**](https://v2.docusaurus.io/).
<!--truncate-->
This is my first post on Docusaurus 2.
A whole bunch of exploration to follow.
Header options
The only required field is title; however, we provide options to add author information to your blog post as well along with other options.
author- The author name to be displayed.author_url- The URL that the author's name will be linked to. This could be a GitHub, Twitter, Facebook profile URL, etc.author_image_url- The URL to the author's thumbnail image.author_title- A description of the author.title- The blog post title.tags- A list of strings to tag to your post.draft- A boolean flag to indicate that the blog post is work in process and therefore should not be published yet. However, draft blog posts will be displayed during development.description: The description of your post, which will become the<meta name="description" content="..."/>and<meta property="og:description" content="..."/>in<head>, used by search engines. If this field is not present, it will default to the first line of the contents.image: Cover or thumbnail image that will be used when displaying the link to your post.
Summary truncation
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:
---
title: Truncation Example
---
All this will be part of the blog post summary.
Even this.
<!--truncate-->
But anything from here on down will not be.
Not this.
Or this.
Feed
You can generate RSS/ Atom feed by passing feedOptions.
feedOptions?: {
type: 'rss' | 'atom' | 'all';
title?: string;
description?: string;
copyright: string;
language?: string; // possible values: http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes
};
Example usage:
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
feedOptions: {
type: 'all',
copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`,
},
},
},
],
],
};
Accessing the feed:
The feed for RSS can be found at:
https://{your-domain}/blog/rss.xml
and for Atom:
https://{your-domain}/blog/atom.xml
Advanced topics
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.
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
path: './blog',
routeBasePath: '/', // Set this value to '/'.
},
},
],
],
};
:::caution
Don't forget to delete the existing homepage at ./src/pages/index.js or else there will be two files mapping to the same route!
:::
Multiple blogs
By default, the classic theme assumes only one blog per website and hence includes only one instance of the blog plugin. If you would like to have multiple blogs on a single website, it's possible too! You can add another blog by specifying another blog plugin in the plugins option for docusaurus.config.js.
Set the routeBasePath to the URL route that you want your second blog to be accessed on. Note that the routeBasePath here has to be different from the first blog or else there could be a collision of paths! Also, set path to the path to the directory containing your second blog's entries.
module.exports = {
// ...
plugins: [
[
'@docusaurus/plugin-content-blog',
{
/**
* URL route for the blog section of your site.
* *DO NOT* include a trailing slash.
*/
routeBasePath: 'my-second-blog',
/**
* Path to data on filesystem relative to site dir.
*/
path: './my-second-blog',
},
],
],
};