Automattic / Automattic/jetpack

Enhancement: Update GitHub Flavored Markdown parser to support "Alerts" syntax

Open
#45,907 0 comments 0 reactions 0 assignees View on GitHub
[Feature] Markdown Enhancement
Dominant language
PHP
Stars
1.8k
Forks
898
Avg merge
1d 18h
Merged PRs (30d)
774

Description

### Impacted plugin

None / Other

### What

Update GitHub Flavored Markdown parser to support "Alerts" syntax

### How

GitHub now extends Markdown syntax to support showing alerts, which would be nice to support as part of [the `WPCom_GHF_Markdown_Parser` class](https://github.com/Automattic/jetpack/blob/trunk/projects/plugins/jetpack/_inc/lib/markdown/gfm.php).

**Documentation:** https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts

**Examples:**

> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.

**Syntax Reference:**

```
> [!NOTE]
> Useful information that users should know, even when skimming content.

> [!TIP]
> Helpful advice for doing things better or more easily.

> [!IMPORTANT]
> Key information users need to know to achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.
```

**Use-Case:**

Documentation on [the WordPress Developer Resources site](https://developer.wordpress.org/) uses this parser class to parse Markdown shown on the site, for example from documentation authored in [the Gutenberg plugin](https://github.com/WordPress/gutenberg). Without support for this feature, it is difficult to author documentation which would consistently show alert content in both GitHub and the developer site.

Examples:

- Using `

`
- [Appears correctly on developer.wordpress.org](https://developer.wordpress.org/block-editor/reference-guides/data/data-core-annotations/)
- [Does not appear correctly on GitHub](https://github.com/WordPress/gutenberg/blob/trunk/docs/reference-guides/data/data-core-annotations.md)
- Using GitHub Flavored Markdown syntax `[!NOTE]`
- [Appears correctly on GitHub](https://github.com/WordPress/gutenberg/blob/6fcc181cf676e61655ae5403f884f8a36b9b8cc1/packages/theme/README.md#color-tokens)
- [Does not appear correctly on developer.wordpress.org](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-theme/#color-tokens)

Contributor guide

Open the contributing guide

Research direction

Start with the WPCom_GHF_Markdown_Parser class in projects/plugins/jetpack/_inc/lib/markdown/gfm.php and compare its handling of blockquotes with the linked GitHub Alerts syntax examples. Done means the five documented alert forms are parsed consistently for the WordPress Developer Resources use case.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
documentation
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.