quarto-dev / quarto-dev/quarto-cli
Can't render README.qmd by default or recursively
Nobody has claimed this yet.
- 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:
- If I have a top-level file named
README.qmd, runningquarto renderdoes not render the file. However, if I modify_quarto.ymlto include
project:
render:
- README.qmd
then it will render just fine.
- Even if I modify the
_quarto.ymlfile,README.qmdfiles 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 checkin the "Quarto Check Output" text area? - documented the version of the quarto tools you're running, by providing the output from running
quarto tools checkin 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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