docs: refactor API documentation (#5219)

* Refactor plugin-docs documentation

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Refactor theme-configuration

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Refactor plugin-blog docs

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Fix link

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* plugin-pages

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Minor change

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Interchange table columns

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Fixes

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Minor improvements

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Fix hash link

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Move blog front matter to API

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Add more blog documentation

Signed-off-by: Josh-Cena <sidachen2003@gmail.com>

* Update blog.md

* Update blog.md

* Update blog.md

* Update website/docs/blog.md

Co-authored-by: Sébastien Lorber <slorber@users.noreply.github.com>
Co-authored-by: slorber <lorber.sebastien@gmail.com>
This commit is contained in:
Joshua Chen 2021-08-04 22:35:17 +08:00 committed by GitHub
parent 2c0b82e7ab
commit c603056f66
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
6 changed files with 686 additions and 469 deletions

View file

@ -51,25 +51,11 @@ This is my first post on Docusaurus 2.
A whole bunch of exploration to follow.
```
## Header options {#header-options}
The only required field in the front matter is `title`; however, we provide options to add more metadata to your blog post, for example, author information. For all possible fields, see [the API documentation](api/plugins/plugin-content-blog.md#markdown-frontmatter).
The only required field is `title`; however, we provide options to add author information to your blog post as well along with other options.
## Blog list {#blog-list}
- `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.
- `slug`: Allows to customize the blog post url (`/<routeBasePath>/<slug>`). Support multiple patterns: `slug: my-blog-post`, `slug: /my/path/to/blog/post`, slug: `/`.
- `date`: The blog post creation date. If not specified, this could be extracted from the file name, e.g, `2021-04-15-blog-post.mdx`. By default, it is the Markdown file creation time.
- `tags`: A list of strings or objects of two string fields `label` and `permalink` 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.
- `keywords`: Keywords meta tag, which will become the `<meta name="keywords" content="keyword1,keyword2,..."/>` in `<head>`, used by search engines.
- `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}
The blog's index page (by default, it is at `/blog`) is the _blog list page_, where all blog posts are collectively displayed.
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:
@ -90,17 +76,71 @@ Not this.
Or this.
```
By default, 10 posts are shown on each blog list page, but you can control pagination with the `postsPerPage` option in the plugin configuration. You can also add meta description to the blog list page for better SEO:
```js title="docusaurus.config.js"
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
// highlight-start
blogTitle: 'Docusaurus blog!',
blogDescription: 'A Docusaurus powered blog!',
postsPerPage: 20,
// highlight-end
},
},
],
],
};
```
## Blog sidebar {#blog-sidebar}
The blog sidebar displays recent blog posts. The default number of items shown is 5, but you can customize with the `blogSidebarCount` option in the plugin configuration. By setting `blogSidebarCount: 0`, the sidebar will be completely disabled, with the container removed as well. This will increase the width of the main container. Specially, if you have set `blogSidebarCount: 'ALL'`, _all_ posts will be displayed.
You can also alter the sidebar heading text with the `blogSidebarTitle` option. For example, if you have set `blogSidebarCount: 'ALL'`, instead of the default "Recent posts", you may would rather make it say "All posts":
```js title="docusaurus.config.js"
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
// highlight-start
blogSidebarTitle: 'All posts',
blogSidebarCount: 'ALL',
// highlight-end
},
},
],
],
};
```
:::note
Because the sidebar title is hard-coded in the configuration file, it is currently untranslatable.
:::
## 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
type BlogOptions = {
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
};
};
```
@ -169,25 +209,6 @@ Don't forget to delete the existing homepage at `./src/pages/index.js` or else t
:::
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`.