Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: document doc tags + refinements #5433

Merged
merged 2 commits into from
Aug 30, 2021
Merged

docs: document doc tags + refinements #5433

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
54c51e1
Various improvements
Josh-Cena Aug 27, 2021
b01e9f9
Oops
Josh-Cena Aug 27, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 11 additions & 6 deletions website/docs/blog.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -181,7 +181,8 @@ Blog post authors can be declared directly inside the FrontMatter:
values={[
{label: 'Single author', value: 'single'},
{label: 'Multiple authors', value: 'multiple'},
]}>
]}
groupId="author-frontmatter">
<TabItem value="single">

```yml title="my-blog-post.md"
Expand Down Expand Up @@ -225,15 +226,16 @@ This option works best to get started, or for casual, irregular authors.

Prefer usage of the `authors` FrontMatter, but the legacy `author_*` FrontMatter remains supported:

<!-- prettier-ignore-start -->
```yml title="my-blog-post.md"
---
author: Joel Marcey
author_title: Co-creator of Docusaurus 1
author_url: https://github.com/JoelMarcey
author_image_url: https://github.com/JoelMarcey.png
---

```
<!-- prettier-ignore-end -->

:::

Expand Down Expand Up @@ -271,7 +273,8 @@ In blog posts FrontMatter, you can reference the authors declared in the global
values={[
{label: 'Single author', value: 'single'},
{label: 'Multiple authors', value: 'multiple'},
]}>
]}
groupId="author-frontmatter">
<TabItem value="single">

```yml title="my-blog-post.md"
Expand Down Expand Up @@ -302,6 +305,7 @@ The `authors` system is very flexible and can suit more advanced use-case:

You can use global authors most of the time, and still use inline authors:

<!-- prettier-ignore-start -->
```yml title="my-blog-post.md"
---
authors:
Expand All @@ -312,16 +316,17 @@ authors:
url: https://github.com/inlineAuthor
image_url: https://github.com/inlineAuthor
---

```
<!-- prettier-ignore-end -->

</details>

<details>
<summary>Local override of global authors</summary>

You can customize the global author's data on per-blog-post basis
You can customize the global author's data on per-blog-post basis:

<!-- prettier-ignore-start -->
```yml title="my-blog-post.md"
---
authors:
Expand All @@ -330,8 +335,8 @@ authors:
- key: slorber
name: Sébastien Lorber's new name
---

```
<!-- prettier-ignore-end -->

</details>

Expand Down
16 changes: 16 additions & 0 deletions website/docs/guides/docs/docs-create-doc.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,3 +83,19 @@ With <code>{#custom-id}</code> syntax you can set your own header id.

</BrowserWindow>
```

## 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.md). Tags are passed in the front matter as a list of labels:

<!-- prettier-ignore-start -->
```yml "your-doc-page.md"
---
id: doc-with-tags
title: A doc with tags
tags:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've just tested Docusaurus beta.5 and this also works fine:

tags: [Demo, Getting Started]

Do you only want to show one way, or do you want to show both the list-format and the array-format?

Copy link
Collaborator Author

@Josh-Cena Josh-Cena Aug 28, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Um, they are both valid YAML formats anyways, not sure if the purpose here is to educate writing valid YAML objects

P.S. I actually prefer writing tags: [Demo, Getting Started]😁 But for several reasons:

  • tags: [Demo, Getting Started] is already demonstrated in blog front matter documentation and init template so users should realize it's valid
  • The - Demo syntax involves less programmatic construct (less JSONic) so it may be more readable

I in the end chose the YAML format instead of JSON

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh I never knew that the Markdown frontmatter is supposed to be a valid YAML object. I learned something new today... 😄

I'll let you decide what you like to do here. 😉

- Demo
- Getting started
---
```
<!-- prettier-ignore-end -->