quarto-dev / quarto-dev/quarto-cli

Can't render README.qmd by default or recursively

Open
#1,615 10 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug projects
Dominant language
JavaScript
Stars
6k
Forks
458
Avg merge
1d 9h
Merged PRs (30d)
41

Description

Bug description

When running quarto render with the CLI, README.qmd files seem to be treated differently from files with other names. I have created minimal .qmd documents with nothing other than a top-level header, and the issue persists, so it is not related to the Quarto syntax of the documents. There are a few different scenarios where this occurs:

  1. If I have a top-level file named README.qmd, running quarto render does not render the file. However, if I modify _quarto.yml to include
project:
   render:
      - README.qmd

then it will render just fine.

  1. Even if I modify the _quarto.yml file, README.qmd files in lower-level directories are not rendered. This doesn't appear to be a globbing issue, as I've tried a few different wildcards.

Perhaps this is desired behavior, but it does not seem to be documented on the Quarto Projects page. It seems that rendering a bunch of README files in GFM for various subdirectories of a GitHub repo is a reasonable use case, so I think others may run into this issue in the future.

If this is indeed desired behavior, a simple workaround I've found is to name the Quarto file something like read_me.qmd and include output-file: README.md in the YAML header.

I am running this on MacOS Monterey 12.4.

quarto check Output
[✓] Checking Quarto installation......OK
      Version: 1.0.37
      Path: /Applications/quarto/bin

[✓] Checking basic markdown render....OK

[✓] Checking Python 3 installation....OK
      Version: 3.9.13
      Path: /usr/local/opt/python@3.9/bin/python3.9
      Jupyter: (None)

      Jupyter is not available in this Python installation.
      Install with python3 -m pip install jupyter

[✓] Checking R installation...........OK
      Version: 4.2.1
      Path: /Library/Frameworks/R.framework/Resources
      LibPaths:
        - /Users/MJ/R_Packages_4.1
        - /Library/Frameworks/R.framework/Versions/4.2/Resources/library
      rmarkdown: 2.14

[✓] Checking Knitr engine render......OK
quarto tools check Output
[✓] Inspecting tools

Tool         Status            Installed     Latest  
chromium     Not installed     ---           869685  
tinytex      Not installed     ---           v2022.07
Checklist
  • formatted your issue so it is easier for us to read?
  • included a minimal, fully reproducible example in a single .qmd file? Please provide the whole file rather than the snippet you believe is causing the issue.
  • documented the quarto version you're running, by pasting the output from running quarto check in the "Quarto Check Output" text area?
  • documented the version of the quarto tools you're running, by providing the output from running quarto tools check in the "Quarto Tools Check Output" text area?
  • documented the RStudio IDE version you're running (if applicable), by providing the value displayed in the "About RStudio" main menu dialog?
  • documented which operating system you're running? If on Linux, please provide the specific distribution as well.
  • upgraded to the latest version, including your versions of R, the RStudio IDE, and relevant R packages?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the top-level and nested README.qmd cases with the quarto render command, including the _quarto.yml render configuration described in the report. Done means README.qmd files render by default and recursively, or the intended exclusion and supported configuration are documented.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
cli
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.