README.Rmd in a bookdown repo

R Markdown
#1

I have a bookdown project that uses a REAMDE.Rmd separately from the actual book: https://github.com/ropensci-books/targets. I prefer to use a README.Rmd to produce README.md so I can automatically generate the citation. But when I render README.Rmd, bookdown thinks it is part of the book, and it generates the final HTML file instead of README.md. Is there a way to tell bookdown that README.Rmd is not a chapter?

Side note: yes, https://github.com/ropensci-books/targets/blob/main/README.md appears to agree with https://github.com/ropensci-books/targets/blob/main/README.Rmd, but I am currently writing the former manually.

#2

By default, bookdown will look for every .Rmd file in the project directory, and in subdir if the option has been activated, ignoring only .Rmd file starting with an underscore _. This is explain in

To avoid the default mode, you can provide the Rmd files to use in the book using rmd_files key in _bookdown.yml. Example: in mastering shiny. README.Rmd won't be processed if not listed.

Subdir configuration is in another part of the book (https://bookdown.org/yihui/bookdown/configuration.html). If you don't activate it (the default), you can have you're README.Rmd file store in a folder, and a Makefile or other that would render it in the root directory.
Same if you name it with _README.Rmd to be rendered to README.md

Last trick (hack ?) is to use another extension - I believe that would not prevent the rendering to .md I believe but bookdown would ignore it.

Hope it helps

#4

As you are listing rmd_files, I am surprised the README.Rmd is taken into account. I'll look into that.

1 Like
#5

Thanks, @cderv! I appreciate that.

#6

I can't reproduce. I also tried to debug after cloning your repo, I debug the function that is selecting the files and README.Rmd is not one of them.

Also I may have misunderstood the issue because I don't find the README chapter in the current HTML book ? is the chapter there ?

Are you sure it is building this file when you build the book ?

Or is the issue that you can't knit the README.Rmd using the Knit button without the result being an HTML file ? If it is forget what I said in my previous answer as this is not related.

#7

About this, as I think it is the issue you meant initially that I can reproduce, this is because rmarkdown::render() with no output_format passed will use the first one found in _output.yaml + YAML header in the file. I bet you wanted the otherway around but it is like that that R Markdown works from a long time.

If you call rmarkdown::render("README.Rmd", "github_document") it will correctly render using the format github_document using the option you may have defined inside the document YAML header itself.

So for a bookdown project, I think the best solution would be to call this when you want to render your document using the other format.

This is an issue (or feature) from rmarkdown and it is not speific to bookdown it seems. I think it will happens with other type of project with similar structure.

If not already filled as a Github issue somewhere, maybe it is worth opening;

1 Like
#8

Thanks, @cderv. rmarkdown::render("README.Rmd", output_format = "github_document") is exactly what I need.

1 Like
#9

This topic was automatically closed 7 days after the last reply. New replies are no longer allowed.

If you have a query related to it or one of the replies, start a new topic and refer back with a link.

#3

That's certainly what I expected because I also use rmd_files in _bookdown.yml, yet bookdown still renders README.Rmd as a book chapter and does not update README.md. Also, I noticed https://github.com/hadley/mastering-shiny has a README.md but no README.Rmd.

Sounds like the other approaches you mentioned should work.