Enable footnotes for README.md files

[jyn514]

There's an actual missing feature still, looking at this diff — footnotes. Do you know if these are actually used in Markdown files parsed by docs.rs? They're not supported by GitHub's own README.md renderer, for what it's worth.

Footnotes are now a part of github-favored markdown¹, is it now possible to add this feature to the docs?

This mostly involves enabling in Comrak, where they're already supported.

Originally posted by @zStruCat in #117 (comment)

Footnotes

1. https://github.blog/changelog/2021-09-30-footnotes-now-supported-in-markdown-fields/ ↩

[BGR360]

I'm confused. I've used footnotes in my rustdocs before and they're rendered on docs.rs: https://docs.rs/minecraft-assets/latest/minecraft_assets/versions/index.html#fn1.

What's the issue? Is it when you do #[doc = include_str!("README.md")]?

[jyn514]

@BGR360 this is specifically for the README, which docs.rs renders even for crates which don't get documented by rustdoc (e.g. binaries): https://docs.rs/crate/bat/latest

[jyn514]

This looks like the right part of the code:

docs.rs/src/web/markdown.rs

Lines 51 to 70 in a43b0fb

	fn render_with_highlighter(
	text: &str,
	highlighter: impl Fn(Option<&str>, &str) -> String,
	) -> String {
	comrak::markdown_to_html_with_plugins(
	text,
	&ComrakOptions {
	extension: ComrakExtensionOptions {
	superscript: true,
	table: true,
	autolink: true,
	tasklist: true,
	strikethrough: true,
	..ComrakExtensionOptions::default()
	},
	..ComrakOptions::default()
	},
	&ComrakPlugins {
	render: ComrakRenderPlugins {
	codefence_syntax_highlighter: Some(&CodeAdapter(highlighter)),

[BGR360]

Ah, I see. Thanks.

@rustbot claim

EDIT: aw, no rustbot ;_;

[BGR360]

I think the docs.rs build environment is busted on M1 macs. It's trying to run x86 docker containers.

running `Command { std: "docker" "create" "-v" "/Users/ben/Documents/Rust/rust-lang/docs.rs/.workspace/builds/essential-files-20221130-1.67.0-nightly-c97b539e4/target:/opt/rustwide/target:rw,Z" "-v" "/Users/ben/Documents/Rust/rust-lang/docs.rs/.workspace/builds/essential-files-20221130-1.67.0-nightly-c97b539e4/source:/opt/rustwide/workdir:ro,Z" "-v" "/Users/ben/Documents/Rust/rust-lang/docs.rs/.workspace/cargo-home:/opt/rustwide/cargo-home:ro,Z" "-v" "/Users/ben/Documents/Rust/rust-lang/docs.rs/.workspace/rustup-home:/opt/rustwide/rustup-home:ro,Z" "-e" "SOURCE_DIR=/opt/rustwide/workdir" "-e" "CARGO_TARGET_DIR=/opt/rustwide/target" "-e" "DOCS_RS=1" "-e" "CARGO_HOME=/opt/rustwide/cargo-home" "-e" "RUSTUP_HOME=/opt/rustwide/rustup-home" "-w" "/opt/rustwide/workdir" "-m" "3221225472" "--user" "501:20" "--network" "none" "ghcr.io/rust-lang/crates-build-env/linux-micro" "/opt/rustwide/cargo-home/bin/cargo" "+nightly" "rustdoc" "--lib" "-Zrustdoc-map" "-Z" "unstable-options" "--config" "build.rustdocflags=[\"-Z\", \"unstable-options\", \"--emit=unversioned-shared-resources,toolchain-shared-resources\", \"--resource-suffix\", \"-20221130-1.67.0-nightly-c97b539e4\", \"--static-root-path\", \"/-/rustdoc.static/\", \"--cap-lints\", \"warn\", \"--disable-per-crate-search\", \"--extern-html-root-takes-precedence\"]" "--offline" "-Zunstable-options" "--config=doc.extern-map.registries.crates-io=\"https://docs.rs/{pkg_name}/{version}/aarch64-apple-darwin\"" "--target" "aarch64-apple-darwin", kill_on_drop: false }` log.target="rustwide::cmd" log.module_path="rustwide::cmd" log.file="/Users/ben/.cargo/registry/src/github.202132.xyz-1ecc6299db9ec823/rustwide-0.15.2/src/cmd/mod.rs" log.line=479
2022-12-01T05:36:52.536450Z  INFO log: [stderr] WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested log.target="rustwide::cmd" log.module_path="rustwide::cmd" log.file="/Users/ben/.cargo/registry/src/github.202132.xyz-1ecc6299db9ec823/rustwide-0.15.2/src/cmd/mod.rs" log.line=621
2022-12-01T05:36:52.536514Z  INFO log: [stdout] 06e3ad4d5d4c6c5807228ae22b3e4b4ec36a48b33376da0338c7fa25be7ddd53 log.target="rustwide::cmd" log.module_path="rustwide::cmd" log.file="/Users/ben/.cargo/registry/src/github.202132.xyz-1ecc6299db9ec823/rustwide-0.15.2/src/cmd/mod.rs" log.line=621
2022-12-01T05:36:52.550261Z  INFO log: running `Command { std: "docker" "start" "-a" "06e3ad4d5d4c6c5807228ae22b3e4b4ec36a48b33376da0338c7fa25be7ddd53", kill_on_drop: false }` log.target="rustwide::cmd" log.module_path="rustwide::cmd" log.file="/Users/ben/.cargo/registry/src/github.202132.xyz-1ecc6299db9ec823/rustwide-0.15.2/src/cmd/mod.rs" log.line=479
2022-12-01T05:36:52.851696Z  INFO log: [stderr] standard_init_linux.go:228: exec user process caused: exec format error log.target="rustwide::cmd" log.module_path="rustwide::cmd" log.file="/Users/ben/.cargo/registry/src/github.202132.xyz-1ecc6299db9ec823/rustwide-0.15.2/src/cmd/mod.rs" log.line=621

[syphar]

I think the docs.rs build environment is busted on M1 macs. It's trying to run x86 docker containers.

yep, it definitely is. On intel macs you needed to run the build inside the web container, which worked, but not any more on M1.

[BGR360]

Can you please call this out more clearly in the README? To save future folks the time wasted trying.

[syphar]

sorry about that.

Btw, if it's only about this issue, the readme is stored in the database (releases.readme), so you might be able to just put in a record into releases and crates, and test the Markdown rendering accordingly.