rmd_subdir in _bookdown.yml ignores plain Markdown files

[kylelundstedt]

The rmd_subdir option in the _bookdown.yml file only works for a subdirectory that contains R Markdown files (.Rmd), not for a subdirectory containing plain Markdown files (.md). However, the bookdown documentation seems to suggest that plain Markdown should work:

Although we have been talking about R Markdown files, the chapter files do not actually have to be R Markdown. They can be plain Markdown files (.md), and do not have to contain R code chunks at all.

---

By filing an issue to this repo, I promise that

• I have fully read the issue guide at https://yihui.org/issue/.
• I have provided the necessary information about my issue.
  • If I'm asking a question, I have already asked it on Stack Overflow or RStudio Community, waited for at least 24 hours, and included a link to my question there.
  • If I'm filing a bug report, I have included a minimal, self-contained, and reproducible example, and have also included xfun::session_info('bookdown'). I have upgraded all my packages to their latest versions (e.g., R, RStudio, and R packages), and also tried the development version: remotes::install_github('rstudio/bookdown').
  • If I have posted the same issue elsewhere, I have also mentioned it in this issue.
• I have learned the Github Markdown syntax, and formatted my issue correctly.

I understand that my issue may be closed if I don't fulfill my promises.

[cderv]

Hi !

I had a look at this .md file support and it seems it is only supported currently if you provide those file in rmd_files explicitly.

By default, if no rmd_files or rmd_subdir is provided, bookdown will not select the .md files, only the .Rmd.

Let's note you can use paths to the file in subdirectory using rmd_files

rmd_files: ["index.Rmd", "other/abstract.md"]

@yihui in the book it is said

Although we have been talking about R Markdown files, the chapter files do not actually have to be R Markdown. They can be plain Markdown files (.md), and do not have to contain R code chunks at all. You can certainly use bookdown to compose novels or poems!

Will that .md support was aimed only when precised in rmd_files ?
We could change the pattern in source_files but this could create some weird content addition in existing book ? (I am thinking of the README.md that often are in bookdown source project - but we could ignore)

What do you think on this one ? Thanks.

[kylelundstedt]

Hi @cderv

You are quite correct. If you use the rmd_files option AND list the .md files explicitly, it works.
If you do NOT list the *.md files explicitly, it does NOT work.
IMHO, this inconsistent treatment is a bug.

The current bookdown(in dev, but not released yet) allows the use of the rmd_files and rmd_subdir options simultaneously.

rmd_files: "index.Rmd"
rmd_subdir: ["collected-poems-in-markdown-format"]

I believe using both would address your concerns about README.md files in the top-level directory without having to make any special exceptions. Therefore, I think the rmd_subdir option should allow for both explicit and implicit inclusion of plain Markdown files.

What do you think?

[cderv]

Therefore, I think the rmd_subdir option should allow for both explicit and implicit inclusion of plain Markdown files.

IMO rmd_subdir: TRUE or rmd_subdir: ["collected-poems-in-markdown-format"] should behave like the default behavior regarding root directory : Automatic selection of files. This would be consistend

Currently, .md files are not looked for automatically as I said. Could be consider a bug, but as it seems to always has been the case, it seems more like a new feature to add.

I see several solutions :

• Add an include_md parameter defaulting to FALSE, that would activate the automatic look up for .md file too in bookdown.
• Modify only rmd_subdir to look for .md files by default. but .md file in root dir would not be found. If one wants to include .md file it would need to be in a subdir (or set in rmd_files explicitly)
• Add the feature to bookdown to also pick the .md files in the project by default - this could have unwanted consequence on existing project if people have .md files in the project currently unpicked and without _ as prefix.

Maybe first option is the best to provide this feature for people who want it - but it adds another option 😕

[kylelundstedt]

@cderv I'll defer to your knowledge and experience here. Cheers!

[nigiord]

@kylelundstedt Was this really completed? Which solution has been chosen?

[cderv]

I don't think we did anything about that. I'll reopen

[katrinabrock]

Would you accept a PR to fix this? If so, which of the options would you like to be implemented?

[cderv]

Sure we would accept PR. @yihui do you have any insight on a preferred solution ?

Personally, the one with minimum impact to current project would be to prefer. So probably an opt-in to this.

[katrinabrock]

BTW - Here is my current workaround:

In R:

options(yaml.eval.expr=TRUE)

In _bookdown.yml:

rmd_files: !expr list.files('.', '[.][Rr]?md$', ignore.case=TRUE)

[yihui]

Sure we would accept PR. @yihui do you have any insight on a preferred solution ?

Perhaps the first option? i.e., include_md: false by default. That won't be a breaking change.

BTW, in litedown, I'll use both .Rmd and .md by default. The rules are here: https://github.com/yihui/litedown/blob/1c70dd31346fe902d765d0263d7fa70acd603c4c/R/site.R#L162-L166