mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-30 01:17:07 +02:00
chore(v2): prepare v2.0.0-beta.0 release (#4774)
* beta.0 version docs + changelog * fix config for beta switch * v2.0.0-beta.0
This commit is contained in:
Sébastien Lorber
GitHub
parent
fe6492aa87
commit
7e4d7671c8
103 changed files with 11779 additions and 149 deletions
222
website/versioned_docs/version-2.0.0-beta.0/blog.md
Normal file
222
website/versioned_docs/version-2.0.0-beta.0/blog.md
Normal file
|
|
@ -0,0 +1,222 @@
|
|||
---
|
||||
id: blog
|
||||
title: Blog
|
||||
---
|
||||
|
||||
## Initial setup {#initial-setup}
|
||||
|
||||
To setup your site's blog, start by creating a `blog` directory.
|
||||
|
||||
Then, add an item link to your blog within `docusaurus.config.js`:
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
themeConfig: {
|
||||
// ...
|
||||
navbar: {
|
||||
items: [
|
||||
// ...
|
||||
// highlight-next-line
|
||||
{to: 'blog', label: 'Blog', position: 'left'}, // or position: 'right'
|
||||
],
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
## Adding posts {#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`:
|
||||
|
||||
```yml
|
||||
---
|
||||
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
|
||||
hide_table_of_contents: false
|
||||
---
|
||||
Welcome to this blog. This blog is created with [**Docusaurus 2 alpha**](https://docusaurus.io/).
|
||||
|
||||
<!--truncate-->
|
||||
|
||||
This is my first post on Docusaurus 2.
|
||||
|
||||
A whole bunch of exploration to follow.
|
||||
```
|
||||
|
||||
## Header options {#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-progress 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.
|
||||
- `hide_table_of_contents`: Whether to hide the table of contents to the right. By default it is `false`.
|
||||
|
||||
## Summary truncation {#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:
|
||||
|
||||
```yml
|
||||
---
|
||||
title: Truncation Example
|
||||
---
|
||||
All these 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 {#feed}
|
||||
|
||||
You can generate RSS/Atom feed by passing feedOptions. By default, RSS and Atom feeds are generated. To disable feed generation, set `feedOptions.type` to `null`.
|
||||
|
||||
```ts
|
||||
feedOptions?: {
|
||||
type?: 'rss' | 'atom' | 'all' | null;
|
||||
title?: string;
|
||||
description?: string;
|
||||
copyright: string;
|
||||
language?: string; // possible values: http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes
|
||||
};
|
||||
```
|
||||
|
||||
Example usage:
|
||||
|
||||
```js {8-11} title="docusaurus.config.js"
|
||||
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:
|
||||
|
||||
```text
|
||||
https://{your-domain}/blog/rss.xml
|
||||
```
|
||||
|
||||
and for Atom:
|
||||
|
||||
```text
|
||||
https://{your-domain}/blog/atom.xml
|
||||
```
|
||||
|
||||
## Advanced topics {#advanced-topics}
|
||||
|
||||
### Blog-only mode {#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.
|
||||
|
||||
```js {9} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
docs: false,
|
||||
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!
|
||||
|
||||
:::
|
||||
|
||||
You can also add meta description to the blog list page for better SEO:
|
||||
|
||||
```js {8} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
[
|
||||
'@docusaurus/preset-classic',
|
||||
{
|
||||
blog: {
|
||||
blogTitle: 'Docusaurus blog!',
|
||||
blogDescription: 'A docusaurus powered blog!',
|
||||
},
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
### Multiple blogs {#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.
|
||||
|
||||
As documented for [multi-instance plugins](./using-plugins.md#multi-instance-plugins-and-plugin-ids), you need to assign a unique id to the plugins.
|
||||
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
plugins: [
|
||||
[
|
||||
'@docusaurus/plugin-content-blog',
|
||||
{
|
||||
/**
|
||||
* Required for any multi-instance plugin
|
||||
*/
|
||||
id: 'second-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',
|
||||
},
|
||||
],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
As an example, we host a second blog [here](/second-blog).
|
||||
Loading…
Add table
Add a link
Reference in a new issue