Document output format for .Rmarkdown files

[apreshill]

(I also need to know the answer to this question!)

We have blogdown::html_page documented in the code, but it isn't clear how to knit an .Rmarkdown file to the appropriate .markdown file output format. I find myself trying to use the knit button to knit an .Rmarkdown post inside my own theme's exampleSite, and unable to knit to .markdown file I think because the project is not detected as a blogdown website by the IDE. The knit button knits straight to .html, and I cannot figure out how to ask for the .markdown output format.

[cderv]

I think this is related to another topic we discuss:

• How could blogdown offer a full markdown mode ?

By full markdown mode, the workflow where someone wants to use only the .Rmarkdown to .markdown mode of blogdown to let hugo handles all outputs to HTML. I guess in that case one would prefer to write .Rmd and output only .md file, without having to "play" with the extension.

I think in other terms, this would be how to include hugodown behavior inside blogdown ?

I am thinking more and more about that. That is not the place to develop maybe, but I think this is related because having a goldmark_output() or hugo_output() or else, would be very handy and coherent with how R Markdown works usually: I want to output another format, I use a different output format function. blogdown relies on extension for now for this...

By the way, this is also thoughts I have because the IDE uses pandoc extensions to output Goldmark format and hugodown does to (but differently it seems) - so I would think it is possible for blogdown to have a md_document variant to convert Pandoc Markdown to Goldmark markdown.

Anyway, if this is interesting, we could discuss it more.

Regarding your question now, from what I understand (it was a great opportunity to know more about blogdown internals, so sharing my understanding)

• The .Rmarkdown is only knitted to .markdown (no markdown conversion) as run_pandoc = FALSE in this case
  

  blogdown/R/render.R

  Lines 194 to 197 in e1be8b9

  	rmarkdown::render(
  	input, 'blogdown::html_page', envir = globalenv(), quiet = TRUE,
  	run_pandoc = !to_md, clean = !to_md
  	)

• But there are some post processing with bookdown:::process_markdown that I think assumes, the .Rmarkdown is written with Pandoc Markdown
  

  blogdown/R/render.R

  Line 217 in e1be8b9

  bookdown:::process_markdown(f, 'markdown', NULL, TRUE, TRUE)

  
  and another one if there are references:
  

  blogdown/R/render.R

  Lines 230 to 231 in e1be8b9

  	rmarkdown::pandoc_convert(
  	mds[1], from = 'markdown', to = 'gfm+tex_math_dollars+footnotes', output = mds[2],

Is this correct ?
If so, this could be a base for a documentation on this internal behavior, with a version toward end users.

[apreshill]

This is indeed a "mode" that would benefit many users, as we mention in the book:

"The main advantage of using .Rmarkdown is that the output files are cleaner because they are Markdown files."

Additional benefits:

• JJ built in support for goldmark md documents in the visual editor (https://rstudio.github.io/visual-markdown-editing/#/markdown?id=hugo-markdown)

• Populates the {{ .TableOfContents }} Hugo variable (https://gohugo.io/content-management/toc/)

• Users can configure their TOC via the goldmark renderer (https://gohugo.io/getting-started/configuration-markup/#table-of-contents)

• Users can benefit from Markdown render hooks via the goldmark renderer (https://gohugo.io/getting-started/configuration-markup/#markdown-render-hooks); like:

layouts
└── _default
    └── _markup
        ├── render-image.html
        ├── render-image.rss.xml
        └── render-link.html

It feels like .md should be one build method: https://bookdown.org/yihui/blogdown/methods.html#methods

.Rmarkdown --> .markdown is less portable and less familiar.

The keep_md YAML option was added, but this requires someone to add one or all html files to their ignoreFiles because of the Hugo trumping rules (.html > .md) (see: #445). This approach is even harder if by chance you have a few actual .html content files on purpose, so you'd have to start ignoring individual files by name instead of using wildcard characters. Also, your GitHub content folder will just bloat unless you also add all the .html files to your .gitignore too.

[maelle]

I would also like full Markdown support. A hack I've just tried

• Using a custom build method https://bookdown.org/yihui/blogdown/methods.html
• Having the build.R below to have index.Rmd knit to index.md with the hugodown output format

path <- rstudioapi::getSourceEditorContext()$path
rmarkdown::render(
  path,
  output_format = hugodown::md_document()
)
file.remove(sub(".Rmd", ".html", path))

It would work with other Markdown formats, of course, but I tried the hack to get downlit highlighting.

[cderv]

I find it odd that you need to remove the html file - using method = "custom" should only run build.R and you only generate a md document. 🤔 It is as if another render is happening.

Also, for this type of use case, it would be interested to pass build_rmd as an argument to build.R script so that it can be used inside the script.

blogdown/R/render.R

Lines 62 to 67 in 28bb4a8

	build_site = function(
	local = FALSE, method = c('html', 'custom'), run_hugo = TRUE, build_rmd = FALSE
	) {
	if (missing(method)) method = get_option('blogdown.method', method)
	method = match.arg(method)
	on.exit(run_script('R/build.R', as.character(local)), add = TRUE)

this would be a way to get the path of the file without having to rely on rstudioapi (which would currently not work if you try to use build_site() at command line and the Rmd needs to be knitted).

[maelle]

I thought the HTML file came from hugodown but I'm not so sure.

I actually use the knit button. (which might explain the HTML creation?)

[yihui]

I find myself trying to use the knit button to knit an .Rmarkdown post inside my own theme's exampleSite, and unable to knit to .markdown file I think because the project is not detected as a blogdown website by the IDE.

@apreshill If you are developing a theme, it's a little tricky to make the RStudio IDE recognize the type of the project and render posts under exampleSite/content/. There are two things that you need to do:

1. setwd('exampleSite'): https://github.com/yihui/hugo-prose/blob/master/.Rprofile
2. change the default root dir to WebsitePath: exampleSite: https://github.com/yihui/hugo-prose/blob/master/hugo-prose.Rproj

This should solve your original problem. The rest of replies brought up another issue, which I just tried to address:

It feels like .md should be one build method: https://bookdown.org/yihui/blogdown/methods.html#methods

@apreshill That makes sense. I left the option blogdown.method open in the original design of build_site() (with a vague feeling that I'd need to support more methods in the future), and now I'm glad that I did. I just provided options(blogdown.method = "markdown"). Once you set this option, .Rmd will be rendered to .md (under the hood, .Rmd receives the same treatment as .Rmarkdown, which was explained in detail by @cderv above).

I guess that will also solve @maelle's problem (no need to hack with method = "custom"; however, at this point, you still don't have downlit support with method = "markdown").

[maelle]

I can't get ".Rmd will be rendered to .md" to work.

• I re-installed blogdown, removed my build.R lines and changed the method in the Rprofile.
• I re-started R and even RStudio.

The Rmd still gets knit to html 🤔 https://github.com/maelle/apresacademic/tree/main/content/blog/2021-01-05-hi-blogdown

Sorry if I'm getting something wrong. I'm very excited about this update!

[cderv]

It seems there is something off in RStudio IDE when using the knit button.

Using blogdown::build_site(build_rmd = TRUE) will correctly render .Rmd to .md when the option is set.
Same with rmarkdown::render_site('<absolute_path_to_your_Rmd>') in the R console.
But Knitting with the button will output a HTML.

This happens only with .Rmd to .md - .Rmarkdown are correctly rendered to .markdown.

Still looking into this 🤔

[cderv]

Continuing the discussion in its own issue #562

This happens with method != "html" and not only with this new feature (b84bc8f) - I think it was also an issue with method = "custom" -> Knit button does not fully work with blogdown yet.

[yihui]

Sounds like a bug. Sorry I didn't test it yesterday since it was too late at night. I'm investigating now.

[cderv]

Just to be clear, I stumbled upon this bug before you added the feature here, while testing what @maelle was trying (#530 (comment)).

As it was happening also with the new method, it confirmed something was off.

I investigated this morning but was missing some information as I am not sure what the Knit button is really doing in RStudio IDE.

Happy to discuss it further !

[yihui]

Should be fixed now. Thanks for the report!

remotes::install_github('rstudio/blogdown')

[maelle]

It works now. 🎉 Thank you! It feels very natural to me to use the knit button. 🧶 😁