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

Update Markdown in MDN docs to use GFM syntax #33384

Merged
merged 5 commits into from
Jul 23, 2024
Merged

Update Markdown in MDN docs to use GFM syntax #33384

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
f00e6de
Update Markdown in MDN docs to use GFM syntax
queengooborg May 3, 2024
eceeab3
Apply suggestions from code review
queengooborg May 4, 2024
5b954a8
Merge branch 'main' into queengooborg-patch-1
queengooborg Jul 23, 2024
6c78bd9
Fix formatting
queengooborg Jul 23, 2024
bb54975
Update wording slightly
queengooborg Jul 23, 2024
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
60 changes: 25 additions & 35 deletions files/en-us/mdn/writing_guidelines/howto/markdown_in_mdn/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -176,15 +176,19 @@ This issue was resolved in:

## Notes, warnings, and callouts

Sometimes writers want to call special attention to a piece of content. To do this, they will use a GFM blockquote with a special first paragraph. There are three types of these: notes, warnings, and callouts.
Sometimes writers want to call special attention to a piece of content. To do this, they will use the [GFM noteblock syntax](https://github.com/orgs/community/discussions/16925), which is a GFM blockquote with a special first line. There are three types of these: notes, warnings, and callouts.

- To add a note, create a GFM blockquote whose first paragraph starts with `**Note:**`.
- To add a warning, create a GFM blockquote whose first paragraph starts with `**Warning:**`.
- To add a callout, create a GFM blockquote whose first paragraph starts with `**Callout:**`.
> [!NOTE]
> MDN Web Docs supported noteblocks with its own syntax before GFM adopted syntax. As such, MDN supports only two of the five noteblock types GFM supports, and supports an additional type that GFM does not.
queengooborg marked this conversation as resolved.
Show resolved Hide resolved

Notes and warnings will render the **Note:** or **Warning:** text in the output, while callouts will not. This makes callouts a good choice when an author wants to provide a custom title.
- To add a note, create a GFM blockquote whose first line is `[!NOTE]`.
- To add a warning, create a GFM blockquote whose first line is `[!WARNING]`.
- To add a callout, create a GFM blockquote whose first line is `[!CALLOUT]`.

Processing of the markup works on the AST it produces, not on the exact characters provided. This means that providing `<strong>Note:</strong>` will also generate a note. However, the Markdown syntax is required as a matter of style.
Notes and warnings will add a localized **Note:** or **Warning:** to the beginning of the output, while callouts will not. This makes callouts a good choice when an author wants to provide a custom title.

> [!WARNING]
> In the older MDN syntax, the type was localized and added to the first paragraph in bold text, i.e. `**Note:** Foo bar` instead of `[!NOTE] ⏎ Foo bar`. This syntax is still supported for migration purposes. Avoid using it in new documentation.
queengooborg marked this conversation as resolved.
Show resolved Hide resolved

Multiple lines are produced by an empty block quote line in the same way as normal paragraphs. Further, multiple lines without a space are also treated like normal Markdown lines, and concatenated.

Expand All @@ -195,7 +199,8 @@ The blockquote can contain code blocks or other block elements.
#### Note

```md
> **Note:** This is how you write a note.
> [!NOTE]
> This is how you write a note.
>
> It can have multiple lines.
```
Expand All @@ -211,14 +216,16 @@ This will produce the following HTML:

This HTML will be rendered as a highlighted box:

> **Note:** This is how you write a note.
> [!NOTE]
> This is how you write a note.
>
> It can have multiple lines.

#### Warnings

```md
> **Warning:** This is how you write a warning.
> [!WARNING]
> This is how you write a warning.
>
> It can have multiple paragraphs.
```
Expand All @@ -234,14 +241,16 @@ This will produce the following HTML:

This HTML will be rendered as a highlighted box:

> **Warning:** This is how you write a warning.
> [!WARNING]
> This is how you write a warning.
>
> It can have multiple paragraphs.

#### Callouts

```md
> **Callout:** **This is how you write a callout.**
> [!CALLOUT]
> **This is how you write a callout.**
Copy link
Contributor

Choose a reason for hiding this comment

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

[mdn-linter] reported by reviewdog 🐶

Suggested change
> [!CALLOUT]
> **This is how you write a callout.**
> [!CALLOUT] > **This is how you write a callout.**

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Uh oh, that's not proper!

Copy link
Member

Choose a reason for hiding this comment

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

A markdownlint rule kicking in here, I guess.

Copy link
Member

@bsmth bsmth May 3, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

You need to change this in mdlint config:

"no-blanks-blockquote": true,

edit: https://github.com/DavidAnson/markdownlint/blob/main/doc/md028.md

Copy link
Member

@bsmth bsmth May 3, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

Although disabling this rule and running yarn run lint:md you get:

Linting: 12280 file(s)
Summary: 244 error(s)

Which is what the mdlint config comment says (consecutive admonitions) so this breaks:

> [!Note]
> The above behavior of block layout changes if ...

> [!Note]
> HTML (_HyperText Markup Language_) elements ...

Copy link
Member

Choose a reason for hiding this comment

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

or maybe I'm wrong, is it just happening with Callouts?

Copy link
Member

Choose a reason for hiding this comment

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

It seems that prettier caused this problem, see playground, issue: prettier/prettier#9099

A workaround to resolve this:

> [!CALLOUT]
>
> **This is how you write a callout.**

maybe we need to resolve the wrong parser logic of yari (as this could not be rendered correctly by yari)?

image

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I just submitted mdn/yari#11108 to fix the rendering!

Copy link
Member

Choose a reason for hiding this comment

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

Well spotted 👍🏻

queengooborg marked this conversation as resolved.
Show resolved Hide resolved
>
> It can have multiple paragraphs.
```
Expand All @@ -257,38 +266,18 @@ This will produce the following HTML:

This HTML will be rendered as a highlighted box:

> **Callout:**
>
> [!CALLOUT]
Copy link
Member

Choose a reason for hiding this comment

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

Everything looks fine, but this still looks broken on the preview, are we waiting for a Yari version to land in the content repo for this or what's the plan? Otherwise looking good!

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

The preview looks broken because it's running a version of Yari prior to the bug fix, which isn't yet released. We can probably merge this now and then it'll automatically be fixed once Yari's been updated, but WDYT?

Copy link
Member

Choose a reason for hiding this comment

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

It's just on this page, right? If it's only one occurrence, which it looks like, it's probably fine to land this. Other instances (137 cases) use the older syntax:

grep -r "\*\*Callout:\*\*" ./files | wc -l
     137

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

So far, it's just this one, yeah!

> **This is how you write a callout.**
queengooborg marked this conversation as resolved.
Show resolved Hide resolved
queengooborg marked this conversation as resolved.
Show resolved Hide resolved
>
> It can have multiple paragraphs.

#### Translated warning

Because the text "Note:" or "Warning:" also appears in the rendered output, it has to be sensitive to translations. In practice this means that every locale supported by MDN must supply its own translation of these strings, and the platform must recognize them as indicating that the construct needs special treatment.

The localizations are stored in [Yari](https://github.com/mdn/yari/tree/main/markdown/localizations) as JSON files in [gettext](https://www.gnu.org/software/gettext/) format. Refer to these files to determine what string should be used in place of "Note:" or "Warning:" for that locale. If a locale file is not defined, English will be used as a fallback.

For example, if we want to use "Warnung" for "Warning" in German, then in German pages we would write:

```md
> **Warnung:** So schreibt man eine Warnung.
```

And this will produce:

```html
<div class="notecard warning">
<p><strong>Warnung:</strong> So schreibt man eine Warnung.</p>
</div>
```

#### Note containing a code block

This example contains a code block.

````md
> **Note:** This is how you write a note.
> [!NOTE]
> This is how you write a note.
>
> It can contain code blocks.
>
Expand All @@ -312,7 +301,8 @@ This will produce the following HTML:

This HTML will be rendered as with a code block:

> **Note:** This is how you write a note.
> [!NOTE]
> This is how you write a note.
>
> It can contain code blocks.
>
Expand Down
Loading