mirror of
https://github.com/facebook/docusaurus.git
synced 2025-06-01 18:32:52 +02:00
feat(docs, blog): add support for tags.yml, predefined list of tags (#10137)
Co-authored-by: Sébastien Lorber <slorber@users.noreply.github.com> Co-authored-by: OzakIOne <OzakIOne@users.noreply.github.com> Co-authored-by: sebastien <lorber.sebastien@gmail.com> Co-authored-by: slorber <slorber@users.noreply.github.com>
This commit is contained in:
ozaki
GitHub
parent
1049294ba6
commit
0eb7b64aac
63 changed files with 2597 additions and 722 deletions
|
|
@ -0,0 +1,54 @@
|
|||
## Tags File {#tags-file}
|
||||
|
||||
Use the [`tags` plugin option](#tags) to configure the path of a YAML tags file.
|
||||
|
||||
By convention, the plugin will look for a `tags.yml` file at the root of your content folder(s).
|
||||
|
||||
This file can contain a list of predefined tags. You can reference these tags by their keys in Markdown files thanks to the [`tags` front matter](#markdown-front-matter).
|
||||
|
||||
:::tip Keeping tags consistent
|
||||
|
||||
Using a tags file, you can ensure that your tags usage is consistent across your plugin content set. Use the [`onInlineTags: 'throw'`](#onInlineTags) plugin option to enforce this consistency and prevent usage of inline tags declared on the fly.
|
||||
|
||||
:::
|
||||
|
||||
### Types {#tags-file-types}
|
||||
|
||||
The YAML content of the provided tags file should respect the following shape:
|
||||
|
||||
```tsx
|
||||
type Tag = {
|
||||
label?: string; // Tag display label
|
||||
permalink?: string; // Tag URL pathname segment
|
||||
description?: string; // Tag description displayed in the tag page
|
||||
};
|
||||
|
||||
type TagsFileInput = Record<string, Partial<Tag> | null>;
|
||||
```
|
||||
|
||||
### Example {#tags-file-example}
|
||||
|
||||
```yml title="tags.yml"
|
||||
releases:
|
||||
label: 'Product releases'
|
||||
permalink: '/product-releases'
|
||||
description: 'Content related to product releases.'
|
||||
|
||||
# A partial tag definition is also valid
|
||||
announcements:
|
||||
label: 'Announcements'
|
||||
|
||||
# An empty tag definition is also valid
|
||||
# Other attributes will be inferred from the key
|
||||
emptyTag:
|
||||
```
|
||||
|
||||
```md title="content.md"
|
||||
---
|
||||
tags: [releases, announcements, emptyTag]
|
||||
---
|
||||
|
||||
# Title
|
||||
|
||||
Content
|
||||
```
|
||||
|
|
@ -78,6 +78,8 @@ Accepted fields:
|
|||
| `processBlogPosts` | <code>[ProcessBlogPostsFn](#ProcessBlogPostsFn)</code> | `undefined` | An optional function which can be used to transform blog posts (filter, modify, delete, etc...). |
|
||||
| `showLastUpdateAuthor` | `boolean` | `false` | Whether to display the author who last updated the blog post. |
|
||||
| `showLastUpdateTime` | `boolean` | `false` | Whether to display the last date the blog post was updated. This requires access to git history during the build, so will not work correctly with shallow clones (a common default for CI systems). With GitHub `actions/checkout`, use`fetch-depth: 0`. |
|
||||
| `tags` | `string \| false \| null \| undefined` | `tags.yml` | Path to the YAML tags file listing pre-defined tags. Relative to the blog content directory. |
|
||||
| `onInlineTags` | `'ignore' \| 'log' \| 'warn' \| 'throw'` | `warn` | The plugin behavior when blog posts contain inline tags (not appearing in the list of pre-defined tags, usually `tags.yml`). |
|
||||
|
||||
```mdx-code-block
|
||||
</APITable>
|
||||
|
|
@ -224,7 +226,7 @@ Accepted fields:
|
|||
| `author_title` | `string` | `undefined` | ⚠️ Prefer using `authors`. A description of the author. |
|
||||
| `title` | `string` | Markdown title | The blog post title. |
|
||||
| `date` | `string` | File name or file creation time | The blog post creation date. If not specified, this can be extracted from the file or folder name, e.g, `2021-04-15-blog-post.mdx`, `2021-04-15-blog-post/index.mdx`, `2021/04/15/blog-post.mdx`. Otherwise, it is the Markdown file creation time. |
|
||||
| `tags` | `Tag[]` | `undefined` | A list of strings or objects of two string fields `label` and `permalink` to tag to your post. |
|
||||
| `tags` | `Tag[]` | `undefined` | A list of strings or objects of two string fields `label` and `permalink` to tag to your post. Strings can be a reference to keys of a [tags file](#tags-file) (usually `tags.yml`) |
|
||||
| `draft` | `boolean` | `false` | Draft blog posts will only be available during development. |
|
||||
| `unlisted` | `boolean` | `false` | Unlisted blog posts will be available in both development and production. They will be "hidden" in production, not indexed, excluded from sitemaps, and can only be accessed by users having a direct link. |
|
||||
| `hide_table_of_contents` | `boolean` | `false` | Whether to hide the table of contents to the right. |
|
||||
|
|
@ -272,7 +274,7 @@ authors:
|
|||
title: Co-creator of Docusaurus 1
|
||||
url: https://github.com/JoelMarcey
|
||||
image_url: https://github.com/JoelMarcey.png
|
||||
tags: [hello, docusaurus-v2]
|
||||
tags: [docusaurus]
|
||||
description: This is my first post on Docusaurus.
|
||||
image: https://i.imgur.com/mErPwqL.png
|
||||
hide_table_of_contents: false
|
||||
|
|
@ -281,6 +283,10 @@ hide_table_of_contents: false
|
|||
A Markdown blog post
|
||||
```
|
||||
|
||||
import TagsFileApiRefSection from './_partial-tags-file-api-ref-section.mdx';
|
||||
|
||||
<TagsFileApiRefSection />
|
||||
|
||||
## i18n {#i18n}
|
||||
|
||||
Read the [i18n introduction](../../i18n/i18n-introduction.mdx) first.
|
||||
|
|
|
|||
|
|
@ -65,6 +65,8 @@ Accepted fields:
|
|||
| `lastVersion` | `string` | First version in `versions.json` | The version navigated to in priority and displayed by default for docs navbar items. |
|
||||
| `onlyIncludeVersions` | `string[]` | All versions available | Only include a subset of all available versions. |
|
||||
| `versions` | <code>[VersionsConfig](#VersionsConfig)</code> | `{}` | Independent customization of each version's properties. |
|
||||
| `tags` | `string \| false \| null \| undefined` | `tags.yml` | Path to a YAML file listing pre-defined tags. Relative to the docs version content directories. |
|
||||
| `onInlineTags` | `'ignore' \| 'log' \| 'warn' \| 'throw'` | `warn` | The plugin behavior when docs contain inline tags (not appearing in the list of pre-defined tags, usually `docs/tags.yml`). |
|
||||
|
||||
```mdx-code-block
|
||||
</APITable>
|
||||
|
|
@ -293,7 +295,7 @@ Accepted fields:
|
|||
| `description` | `string` | The first line of Markdown content | The description of your document, which will become the `<meta name="description" content="..."/>` and `<meta property="og:description" content="..."/>` in `<head>`, used by search engines. |
|
||||
| `image` | `string` | `undefined` | Cover or thumbnail image that will be used as the `<meta property="og:image" content="..."/>` in the `<head>`, enhancing link previews on social media and messaging platforms. |
|
||||
| `slug` | `string` | File path | Allows to customize the document URL (`/<routeBasePath>/<slug>`). Support multiple patterns: `slug: my-doc`, `slug: /my/path/myDoc`, `slug: /`. |
|
||||
| `tags` | `Tag[]` | `undefined` | A list of strings or objects of two string fields `label` and `permalink` to tag to your docs. |
|
||||
| `tags` | `Tag[]` | `undefined` | A list of strings or objects of two string fields `label` and `permalink` to tag to your docs. Strings can be a reference to keys of a [tags file](#tags-file) (usually `tags.yml`) |
|
||||
| `draft` | `boolean` | `false` | Draft documents will only be available during development. |
|
||||
| `unlisted` | `boolean` | `false` | Unlisted documents will be available in both development and production. They will be "hidden" in production, not indexed, excluded from sitemaps, and can only be accessed by users having a direct link. |
|
||||
| `last_update` | `FrontMatterLastUpdate` | `undefined` | Allows overriding the last update author/date. Date can be any [parsable date string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse). |
|
||||
|
|
@ -324,6 +326,7 @@ description: How do I find you when I cannot solve this problem
|
|||
keywords:
|
||||
- docs
|
||||
- docusaurus
|
||||
tags: [docusaurus]
|
||||
image: https://i.imgur.com/mErPwqL.png
|
||||
slug: /myDoc
|
||||
last_update:
|
||||
|
|
@ -336,6 +339,10 @@ last_update:
|
|||
My Document Markdown content
|
||||
```
|
||||
|
||||
import TagsFileApiRefSection from './_partial-tags-file-api-ref-section.mdx';
|
||||
|
||||
<TagsFileApiRefSection />
|
||||
|
||||
## i18n {#i18n}
|
||||
|
||||
Read the [i18n introduction](../../i18n/i18n-introduction.mdx) first.
|
||||
|
|
|
|||
|
|
@ -380,6 +380,35 @@ An author, either declared through front matter or through the authors map, need
|
|||
|
||||
:::
|
||||
|
||||
## Blog post tags {#blog-post-tags}
|
||||
|
||||
Tags are declared in the front matter and introduce another dimension of categorization.
|
||||
|
||||
It is possible to define tags inline, or to reference predefined tags declared in a [`tags file`](api/plugins/plugin-content-blog.mdx#tags-file) (optional, usually `blog/tags.yml`).
|
||||
|
||||
In the following example:
|
||||
|
||||
- `docusaurus` references a predefined tag key declared in `blog/tags.yml`
|
||||
- `Releases` is an inline tag, because it does not exist in `blog/tags.yml`
|
||||
|
||||
```md title="blog/my-post.md"
|
||||
---
|
||||
title: 'My blog post'
|
||||
tags:
|
||||
- Releases
|
||||
- docusaurus
|
||||
---
|
||||
|
||||
Content
|
||||
```
|
||||
|
||||
```yml title="blog/tags.yml"
|
||||
docusaurus:
|
||||
label: 'Docusaurus'
|
||||
permalink: '/docusaurus'
|
||||
description: 'Blog posts related to the Docusaurus framework'
|
||||
```
|
||||
|
||||
## Reading time {#reading-time}
|
||||
|
||||
Docusaurus generates a reading time estimation for each blog post based on word count. We provide an option to customize this.
|
||||
|
|
|
|||
|
|
@ -60,16 +60,32 @@ The [front matter](../markdown-features/markdown-features-intro.mdx#front-matter
|
|||
|
||||
## Doc tags {#doc-tags}
|
||||
|
||||
Optionally, you can add tags to your doc pages, which introduces another dimension of categorization in addition to the [docs sidebar](./sidebar/index.mdx). Tags are passed in the front matter as a list of labels:
|
||||
Tags are declared in the front matter and introduce another dimension of categorization in addition to the [docs sidebar](./sidebar/index.mdx).
|
||||
|
||||
```md "your-doc-page.md"
|
||||
It is possible to define tags inline, or to reference predefined tags declared in a [`tags file`](../../api/plugins/plugin-content-docs.mdx#tags-file) (optional, usually `docs/tags.yml`).
|
||||
|
||||
In the following example:
|
||||
|
||||
- `docusaurus` references a predefined tag key declared in `docs/tags.yml`
|
||||
- `Releases` is an inline tag, because it does not exist in `docs/tags.yml`
|
||||
|
||||
```md title="docs/my-doc.md"
|
||||
---
|
||||
id: doc-with-tags
|
||||
title: A doc with tags
|
||||
tags:
|
||||
- Demo
|
||||
- Getting started
|
||||
- Releases
|
||||
- docusaurus
|
||||
---
|
||||
|
||||
# Title
|
||||
|
||||
Content
|
||||
```
|
||||
|
||||
```yml title="docs/tags.yml"
|
||||
docusaurus:
|
||||
label: 'Docusaurus'
|
||||
permalink: '/docusaurus'
|
||||
description: 'Docs related to the Docusaurus framework'
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue