Best way to output Bookdown book as Markdown?

[matthew-brett]

---

By filing an issue to this repo, I promise that

• I have fully read the issue guide at https://yihui.name/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.

This follows on from my StackOverflow question.

What is the best way to build Bookdown project with Markdown instead of HTML or TeX?

I ask because I need to post-process the final Markdown output from Bookdown, in order to extract R and Python notebooks for download.

In more detail, I am using Bookdown to build a textbook that embeds notebooks to download, where the notebooks contain subsets of the code and text in the bookdown .Rmd files. For example, a single chapter could contain more than one notebook.

In order to do this, I put start and end comment markers in the RMarkdown input text to identify the section that will be a notebook, and then post-process the generated Markdown files to extract the notebook section. As in something like:

<!--- notebook: first_section.Rmd
-->

Some explanation, maybe using Bookdown extra markup such as @a_citation.

```{r}
a <- 1
a
```

<!--- end of notebook
-->

More markdown.

```{r}
# More code not in notebook.
b <- 2
```

Obviously I could use the input RMarkdown pages, but this would be ugly, because all the extended Bookdown markup such as citations, cross-references and so on, would appear in raw and ugly form in the generated notebook. So I'd really like to be able to get the final output Markdown, after merging, resolving of citations and cross references. Is there any way of doing that?

I have tried setting clean=FALSE in the bookdown::render_book call, but this resulted in intermediate Markdown files for each chapter, with citations and (ref:foo) style references not resolved. These intermediate files appear identical to the .md files already written to the output directory in my Knit / Merge build.

I have also tried output_format='rmarkdown::md_document' - but this appears to result in an output document _main.md, which is then deleted during the build.

I was considering looking into making my own output format - is that the right way to go? Or is there another way of doing this?

[matthew-brett]

I have got further with:

fmt = rmarkdown::md_document(variant='gfm')
fmt$pandoc$ext = ".gfm"
bookdown::render_book('index.Rmd', fmt)

This does get me a partly processed full Markdown file, in this case in Github Flavored Markdown, but where references have not been resolved. I see there is a process_markdown function in https://rdrr.io/github/rstudio/bookdown/src/R/ebook.R, that looks promising, but my inexperience in R means that it is not obvious to me how to best use something like that from the rmarkdown::md_document output format.

[matthew-brett]

This appears to do what I want, although, obviously, it's a nasty hack:

nb_document <- function () {
    fmt <- rmarkdown::md_document(variant='gfm')
    fmt$pandoc$ext = ".gfm"
    args = c()
    fig_caption = TRUE
    md_extensions = NULL
    number_sections = FALSE
    from = rmarkdown::from_rmarkdown(fig_caption, md_extensions)
    fmt$pre_processor = function(metadata, input_file, runtime, knit_meta,
                                 files_dir, output_dir) {
        bookdown:::process_markdown(input_file,
                                    from,
                                    args,
                                    number_sections)
        NULL
    }
    fmt
}

fmt <- nb_document()
bookdown::render_book('index.Rmd', fmt)

[yihui]

Good job! You were getting really close :)

In #742, we added an output format markdown_document2. You can just use this format, e.g.,

output: 
  bookdown::markdown_document2:
    base_format: rmarkdown::md_document
    variant: gfm

[matthew-brett]

Nice! Thanks.

[eitanf]

I'm trying out this new output format so I can publish to github pages, but am getting the following error:

$ Rscript -e "bookdown::render_book('index.Rmd', 'bookdown::markdown_document2')"`
`Error in base_format(fig_caption = fig_caption, md_extensions = md_extensions,  :   unused argument (fig_caption = fig_caption)`
`Calls: <Anonymous> ... <Anonymous> -> create_output_format -> do.call -> <Anonymous>
Execution halted`

My _output.yml file includes the following lines, per your suggestion:

bookdown::markdown_document2:
  base_format: rmarkdown::md_document
  variant: gfm

The only related issue I could find was 437, but I don't see how that helps.

[cderv]

Hi,

can you open a new issue linking to this one and following the issue guide (https://yihui.org/issue/) and template you'll get when opening ?

It will be easier to investigate.

Thank you !

[eitanf]

OK--per the guide I posted on stack overflow first.

[github-actions]

This old thread has been automatically locked. If you think you have found something related to this, please open a new issue by following the issue guide (https://yihui.org/issue/), and link to this old issue if necessary.