rmarkdownrstudiopandocformatter

What markdown formatter does RStudio use to convert to canonical markdown?


I want to write a script to automatically convert .qmd, .Rmd, or .md files into the "canonical visual mode markdown" format that RStudio uses when writing Markdown in it. With that option selected, or if the Quarto YAML option editor: markdown: canonical: true is used, anytime you are editing and saving a Markdown document while in RStudio, it re-formats the Markdown into a standard format. This is really nice and useful when collaborating with others because then the Markdown is standardized. BUT! Not everyone uses RStudio, like for instance, if they make an edit to a GitHub repo directly through GitHub, the formatting doesn't happen. And I'd love to have a GitHub Action to run this automatically on the files.

So, I've been searching everywhere for how to convert Markdown into a "canonical" format. I've even dug deep into RStudio's source code to understand how they do it. Unfortunately, it's written in C++, TypeScript, and Java (based on a search), something I don't have experience or knowledge of. I've also tried to directly use Pandoc, and it sorta works, but messes with Quarto's shortcodes and does other things I don't want. The code below is an example of my starting attempts on this, but it's not ideal.

# Shell script
reformat_markdown () {
  pandoc \
    --from markdown-smart+yaml_metadata_block+raw_attribute+blank_before_header \
    --standalone \
    --markdown-headings=atx \
    --wrap=auto \
    --columns=72 \
    --to markdown-smart+yaml_metadata_block+raw_attribute+blank_before_header \
    -o $1.new \
    $1
}

Anyone have any suggestions on how I can accomplish this? Are there easier ways of doing this?


Solution

  • If you’re still looking for a way to format Markdown into RStudio’s canonical visual mode markdown (i.e., what happens when you enable Quarto’s editor: markdown: canonical: true option), I wanted to solve the same problem and ended up creating a shell script to automate it.

    Disclosure: I created the script linked below. I’m sharing it here because I believe it’s directly relevant to your question.


    Use Quarto to Canonically Format Markdown

    RStudio uses Quarto internally to apply the canonical formatting. Quarto uses a ton of custom Pandoc Lua filters to do a lot of that formatting.

    I couldn’t find a way to use Quarto-proper to “just format this Markdown file like RStudio”. However, using some shell scripting, you can get the equivalent of RStudio’s canonical Markdown using the quarto render subcommand.


    Script Solution

    This shell script wraps quarto render to format a Markdown file or clipboard contents using canonical formatting. It works by:

    1. Creating a temporary file with the temporary YAML header

      ---
      editor_options:
        markdown:
          wrap: 80
          canonical: true
      ---
      

      The wrap: 80 is because I also wanted the line wrap.

    2. Running

      quarto render "temp.qmd" --to md --output "output.md"
      

      on the temporary file.

    3. Removing the YAML header and copying over the file in-place.

    Example usage:

    # Format file in-place
    ./md2md.sh myfile.md
    
    # Format clipboard content (and copy result back to clipboard)
    ./md2md.sh
    

    There are other bells and whistles I have added, but I think this basically does what you’re looking for.