GitHub special Markdown blocks aren't rendered in README section

[kbdharun]

Current Behavior

Currently, crates display the blockquote as it is in Markdown.

Expected Behavior

GitHub supports custom rendering for descriptions enclosed inside blockquote starting with [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], [!CAUTION] and this is widely used by many projects.

Syntax:

> [!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.

Which looks like this once rendered:

These descriptions in Crates README can be rendered similarly to how it is shown in GitHub.

Check out https://github.com/orgs/community/discussions/16925 for more information.

Steps To Reproduce

1. Go to a Crate using this kind of syntax in the README file i.e. https://crates.io/crates/tlrc.
2. Navigate to the note or relevant section.

Environment

• Browser: Google Chrome Version 124.0.6367.60 (Official Build) (64-bit)
• OS: Fedora Linux 39 (Workstation Edition)

Anything else?

No response

[fwcd]

Was just about to open the same feature request, would love to see this being added!

Though it seems like the Markdown rendering is largely delegated to comrak, so it might be worth filing the feature request there:

crates.io/crates/crates_io_markdown/lib.rs

Lines 62 to 106 in e01e384

	fn to_html(&self, text: &str) -> String {
	use comrak::{
	format_html, parse_document, Arena, ComrakExtensionOptions, ComrakOptions,
	ComrakRenderOptions,
	};
	let mut render_options = ComrakRenderOptions::default();
	// The output will be sanitized with `ammonia`
	render_options.unsafe_ = true;
	let mut extension_options = ComrakExtensionOptions::default();
	extension_options.autolink = true;
	extension_options.strikethrough = true;
	extension_options.table = true;
	extension_options.tagfilter = true;
	extension_options.tasklist = true;
	extension_options.header_ids = Some("user-content-".to_string());
	extension_options.footnotes = true;
	let options = ComrakOptions {
	render: render_options,
	extension: extension_options,
	..ComrakOptions::default()
	};
	let arena = Arena::new();
	let root = parse_document(&arena, text, &options);
	// Tweak annotations of code blocks.
	iter_nodes(root, &|node| {
	if let NodeValue::CodeBlock(ref mut ncb) = node.data.borrow_mut().value {
	let orig_annot = ncb.info.as_str();
	// Ignore characters after a comma for syntax highlighting to work correctly.
	if let Some((before_comma, _)) = orig_annot.split_once(',') {
	ncb.info = before_comma.to_string();
	}
	}
	});
	let mut html = Vec::new();
	format_html(root, &options, &mut html).unwrap();
	let rendered = String::from_utf8(html).unwrap();
	self.html_sanitizer.clean(&rendered).to_string()
	}

[Arteiii]

I have created an issue in the kivikakk/comrak repository proposing the addition of special GitHub Markdown blocks. You can view the issue here

I believe that adding support for these blocks would greatly improve the readability and usability of the documentation on crates.io as well.

However, I am not sure if I have the skills to implement this feature myself. If anyone is interested in helping, or has any suggestions on how to proceed, your input would be greatly appreciated.

[kbdharun]

Not sure how I missed this reply in my notifications 😅 , thanks for the code block @fwcd.

Support for this has been added upstream as mentioned by @Arteiii below, so IG the lib.rs file can be updated for the same after a new comrak release.

[Arteiii]

kivikakk/comrak#519

merged

either wait for release or add as git dependency

[kbdharun]

Thanks for the update.

[Turbo87]

#10428 updates us to the new comrak version that supports this. PRs for enabling that feature and styling it properly would be welcome 😉

[kbdharun]

#10428 updates us to the new comrak version that supports this. PRs for enabling that feature and styling it properly would be welcome 😉

Great, will try enabling it and will open a PR after testing. (Done, #10429)