Format markdown documents containing Rust

I was wanting to do something similar to #1695, although in my case I've got a bunch of markdown files containing Rust snippets which I'd like to format.

I knocked up a quick Python script which almost does this (gist).

However it looks like rustfmt will skip any file not ending in *.rs... Would it be possible to allow non-Rust files if they are explicitly specified using the --file-lines argument?

Output of running rustfmt from Python:

python rustfmt.py 

b"Warning: Extra file listed in file_lines option '/home/michael/Documents/playground/static-analyser-in-rust/src/codemap.md'\nWarning: Extra file listed in file_lines option '/home/michael/Documents/playground/static-analyser-in-rust/src/lib.md'\nWarning: Extra file listed in file_lines option '/home/michael/Documents/playground/static-analyser-in-rust/src/parse.md'\nWarning: Extra file listed in file_lines option '/home/michael/Documents/playground/static-analyser-in-rust/src/lowering.md'\nWarning: Extra file listed in file_lines option '/home/michael/Documents/playground/static-analyser-in-rust/src/analysis.md'\nWarning: Extra file listed in file_lines option '/home/michael/Documents/playground/static-analyser-in-rust/src/errors.md'\nWarning: Extra file listed in file_lines option '/home/michael/Documents/playground/static-analyser-in-rust/src/lex.md'\n\n"
b''

Rustfmt formats Rust programs not Rust files - it runs according to the declared module structure. Therefore, running on markdown files might be a little complicated and I'm not sure how to do it. However, it definitely should be possible - it is basically the same idea as testing snippets in markdown.

Ah that makes sense given how rustfmt-nightly uses bits of the compiler for parsing and analysis. So the process is a little more complicated than just "here's a string containing some Rust code, please format it".

Would there be any prospects for formatting markdown files or doc-comment examples in the future?

Would there be any prospects for formatting markdown files or doc-comment examples in the future?

Yeah, it seems like something that it would be good to do and I'm pretty sure it is possible, I'm just not sure how to do it :-)

Hi! I'm helping with the translation of TRPL to Brazilian Portuguese (pt-BR) and I'm seeing demand for the same thing. There are many Rust snippets in markdown source that have to be translated, some symbols are translated in batch with search/replace, and it would be nice to run one command to rectify substitutions that have caused formatting mistakes.

Of course this should be super useful to anyone producing Rust content, so the Content Team should be all over this =D Is this the right place to upvote/show support for the feature? Thank you!

I would like to have this same feature. In my case it's the separate .md doc files that I have that describe the usage of my library. For instance this one: https://github.com/JelteF/derive_more/blob/master/doc/add.md

I too would like to see a feature like this.

It would help with things like this:

rustic-games/things@ae5280d

Which uses the (unstable) external_doc feature.

Although, I guess, this would be a bit more complicated, as there are references to modules that only make sense once that external code gets inlined into the main code itself.

Still though, having this would bring this "full circle", allowing you to externally document your library, while still getting proper formatting in those external files.

@hukkinj1

I've been discussing this with @hukkinj1 for Maud: lambda-fairy/maud#231

The conversation is focused on mdformat, which is written in Python. But I can imagine a hypothetical Markdown formatter using pulldown-cmark that does the same thing.

My quick-and-dirty hack is to:

create a throwaway Cargo project
enable format_code_in_doc_comments in that project
copy the markdown file into the project's lib.rs as documentation for a function
format the library
strip out the documentation comments and function and copy it back to the original file

This seems to work OK.

Script to format markdown

#!/usr/bin/env bash

set -euo pipefail

scratch_dir=$(mktemp -d)
project_dir="${scratch_dir}/scratch"

cargo_toml="${project_dir}/Cargo.toml"
rustfmt_toml="${project_dir}/rustfmt.toml"
lib_rs="${project_dir}/src/lib.rs"

cargo new --lib "${project_dir}"

cat <<-EOF > "${rustfmt_toml}"
format_code_in_doc_comments = true
EOF

for markdown_file in $(git ls-files | rg '.md$'); do
    awk '{ print "/// " $0 } END { print "fn dummy() {}"}' "${markdown_file}" > "${lib_rs}"
    cargo +nightly fmt --manifest-path="${cargo_toml}"
    sed -E -e '$ d' -e 's@/// ?@@' "${lib_rs}" > "${markdown_file}"
done

Also works, doesn't write any files:

cat README.md | (
  while IFS= read -r LINE; do
    if [[ -z ${LINE} ]]; then
      echo "///"
    else
      echo "/// ${LINE}"
    fi
  done
  echo "fn dummy() {}"
) | rustfmt --check --config unstable_features=true,format_code_in_doc_comments=true,max_width=80

Notably rustfmt still returns a zero exit code even if it wants to make changes, so you should check that there is no output if this is somehow part of your CI.

I would like to have this same feature.

Feature Request: Support Formatting Code Blocks in Markdown Files

Current Behavior:
The cargo fmt tool (powered by rustfmt) is designed to format Rust source files (.rs). However, it does not currently support formatting code blocks embedded within Markdown files.

Desired Behavior:
It would be beneficial if cargo fmt could directly format fenced code blocks in Markdown files, especially for Rust code. Additionally, supporting line-range formatting (e.g., --line startline --endline endline) would allow users to format specific portions of a file without affecting the entire document.

Use Case:
Many developers use Markdown for documentation and include Rust code snippets. Manually formatting these snippets can be time-consuming and error-prone. Extending cargo fmt to handle Markdown files would streamline this process.

Example Command:

cargo fmt --file README.md --line 10 --endline 20

Navigation Menu

Repository navigation

Format markdown documents containing Rust #2036

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Format markdown documents containing Rust #2036

Description

Activity

nrc commented on Oct 6, 2017

Michael-F-Bryan commented on Oct 6, 2017

nrc commented on Oct 7, 2017

hsribei commented on Mar 6, 2018

JelteF commented on Mar 14, 2018

JeanMertz commented on Nov 14, 2018

lambda-fairy commented on Jan 15, 2021

shepmaster commented on Sep 17, 2021

mumbleskates commented on Feb 17, 2024

djukyo commented on Feb 21, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions