Supports GitHub Alerts with Markdown

[AlexV525]

pub.dev	GitHub

• https://pub.dev/packages/wechat_assets_picker/versions/9.0.0-dev.2/changelog
• https://github.com/fluttercandies/flutter_wechat_assets_picker/blob/4b0380efae5c86083d2b48b94422045cb741ba09/CHANGELOG.md?plain=1#L5-L8
• https://github.com/dart-lang/http/blob/db7f16552937ceb7a8813f9602990c655cfbdcee/pkgs/http/README.md?plain=1#L26-L29

Example:

Note

This is a note.

Context:

• https://github.com/orgs/community/discussions/16925
• https://learn.microsoft.com/en-us/contribute/content/markdown-reference#alerts-note-tip-important-caution-warning

[parlough]

Now that GitHub has stabilized the syntax and it's becoming more common, it likely should be a part of package:markdown and part of the gitHubWeb extension set.

Issue reference: dart-lang/tools#1343

For those interested in contributing to Dart's ecosystem, it would be a fun issue to work on!

[sigurdm]

@parlough where do we see that github stabilized this? I don't see it on https://github.github.com/gfm/ and https://github.com/orgs/community/discussions/16925 doesn't really seem settled (or is it, the thread is a bit unwieldy to read...).

[parlough]

@parlough where do we see that github stabilized this?

I guess I assumed so after they updated to the newer syntax for it and added it to their docs.

Either way, they made a blog post about it today: https://github.blog/changelog/2023-12-14-new-markdown-extension-alerts-provide-distinctive-styling-for-significant-content/. So perhaps with that, we can assume they won't make any further drastic changes.

[AlexV525]

I'm adding callout support for the package at dart-lang/markdown#570. Once it's ready we could use expand with our styles. Or I can make that support directly into this repo too.

[AlexV525]

You can now implement the block with the markdown: ^7.2.0. @sigurdm

[sigurdm]

Wonderful! - @isoos I guess we can upgrade and add the extension? How about dartdoc - are we keeping our markdown-integrations in sync?

[isoos]

How about dartdoc - are we keeping our markdown-integrations in sync?

It is now completely separate, we only set the dartdoc version we want to use, and it will be a global activate. I think, however, that it should pick it up automatically, at least it did for me locally.

[isoos]

We now have a slightly better version, but missing out on the icon:

[sigurdm]

Ah - are we missing some CSS?

[AlexV525]

Note

Highlights information that users should take into account, even when skimming.

Tip

Optional information to help a user be more successful.

Important

Crucial information necessary for users to succeed.

Warning

Critical content demanding immediate user attention due to potential risks.

Caution

Negative potential consequences of an action.

I think you can easily extract SVGs from these alerts.

[AlexV525]

Note:

<path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path>

Tip:

<path d="M8 1.5c-2.363 0-4 1.69-4 3.75 0 .984.424 1.625.984 2.304l.214.253c.223.264.47.556.673.848.284.411.537.896.621 1.49a.75.75 0 0 1-1.484.211c-.04-.282-.163-.547-.37-.847a8.456 8.456 0 0 0-.542-.68c-.084-.1-.173-.205-.268-.32C3.201 7.75 2.5 6.766 2.5 5.25 2.5 2.31 4.863 0 8 0s5.5 2.31 5.5 5.25c0 1.516-.701 2.5-1.328 3.259-.095.115-.184.22-.268.319-.207.245-.383.453-.541.681-.208.3-.33.565-.37.847a.751.751 0 0 1-1.485-.212c.084-.593.337-1.078.621-1.489.203-.292.45-.584.673-.848.075-.088.147-.173.213-.253.561-.679.985-1.32.985-2.304 0-2.06-1.637-3.75-4-3.75ZM5.75 12h4.5a.75.75 0 0 1 0 1.5h-4.5a.75.75 0 0 1 0-1.5ZM6 15.25a.75.75 0 0 1 .75-.75h2.5a.75.75 0 0 1 0 1.5h-2.5a.75.75 0 0 1-.75-.75Z"></path>

Important:

<path d="M0 1.75C0 .784.784 0 1.75 0h12.5C15.216 0 16 .784 16 1.75v9.5A1.75 1.75 0 0 1 14.25 13H8.06l-2.573 2.573A1.458 1.458 0 0 1 3 14.543V13H1.75A1.75 1.75 0 0 1 0 11.25Zm1.75-.25a.25.25 0 0 0-.25.25v9.5c0 .138.112.25.25.25h2a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h6.5a.25.25 0 0 0 .25-.25v-9.5a.25.25 0 0 0-.25-.25Zm7 2.25v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 9a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path>

Warning:

<path d="M6.457 1.047c.659-1.234 2.427-1.234 3.086 0l6.082 11.378A1.75 1.75 0 0 1 14.082 15H1.918a1.75 1.75 0 0 1-1.543-2.575Zm1.763.707a.25.25 0 0 0-.44 0L1.698 13.132a.25.25 0 0 0 .22.368h12.164a.25.25 0 0 0 .22-.368Zm.53 3.996v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path>

Caution:

<path d="M4.47.22A.749.749 0 0 1 5 0h6c.199 0 .389.079.53.22l4.25 4.25c.141.14.22.331.22.53v6a.749.749 0 0 1-.22.53l-4.25 4.25A.749.749 0 0 1 11 16H5a.749.749 0 0 1-.53-.22L.22 11.53A.749.749 0 0 1 0 11V5c0-.199.079-.389.22-.53Zm.84 1.28L1.5 5.31v5.38l3.81 3.81h5.38l3.81-3.81V5.31L10.69 1.5ZM8 4a.75.75 0 0 1 .75.75v3.5a.75.75 0 0 1-1.5 0v-3.5A.75.75 0 0 1 8 4Zm0 8a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path>

[isoos]

Ah - are we missing some CSS?

Not checked it yet, but it is possible we also prune the HTML output from markdown.

[JaffaKetchup]

I'm not sure how related this is, but I've noticed in the dartdoc generated docs from pub.dev, the blocks appear plain, as in this link.

However, the most recent version of dartdoc does definetely support them correctly. When generated locally:

I don't know if dartdoc is used to generate the markdown page. But maybe it's an outdated version, or as @isoos said, maybe it's being sanitized out. But it would be great to sort out the disparity!

[jonasfj]

We always have style for this, we can probably just copy what dartdoc does:

pub-dev/third_party/dartdoc/resources/styles.css

Lines 1249 to 1315 in 539457f

	/* github alert styles */
	.markdown-alert {
	margin-top: 1rem;
	margin-bottom: 1rem;
	padding: 1.25rem;
	}
	.markdown-alert>:last-child {
	margin-bottom: 0;
	}
	.markdown-alert-title {
	display: flex;
	align-items: center;
	gap: 0.4rem;
	margin-bottom: 0.5rem;
	font-weight: bold;
	-webkit-font-smoothing: antialiased;
	}
	.markdown-alert-title:before {
	font: 24px / 1 'Material Symbols Outlined';
	}
	/* note, tip, important, warning, caution */
	.markdown-alert.markdown-alert-note {
	background-color: var(--alert-info);
	}
	.markdown-alert-note .markdown-alert-title:before {
	content: 'info';
	}
	.markdown-alert.markdown-alert-tip {
	background-color: var(--alert-tip);
	}
	.markdown-alert-tip .markdown-alert-title:before {
	content: 'lightbulb';
	}
	.markdown-alert.markdown-alert-important {
	background-color: var(--alert-important);
	}
	.markdown-alert-important .markdown-alert-title:before {
	content: 'feedback';
	}
	.markdown-alert.markdown-alert-warning {
	background-color: var(--alert-warning);
	}
	.markdown-alert-warning .markdown-alert-title:before {
	content: 'warning';
	}
	.markdown-alert.markdown-alert-caution {
	background-color: var(--alert-error);
	}
	.markdown-alert-caution .markdown-alert-title:before {
	content: 'report';
	}

They would be useful in:
#8170

And they would be useful on the admin page when we warn publishers that only have a single member.

[isoos]

Btw. we do pull in some styles, but maybe the generated template behind it changed?
https://github.com/dart-lang/pub-dev/blob/master/pkg/web_css/lib/style.scss#L4
https://github.com/dart-lang/pub-dev/blob/master/third_party/css/dartdoc-github-alert.css
#7501

[EchoEllet]

It looks like this issue has been fixed and published (thanks to #8181)

[sigurdm]

Yeah - @isoos we are done here, right?

[isoos]

I think we can close the issue.