.Rmd to .md and Github YAML display

[kaijabean]

This is a long shot, but I'm wondering if there's any way to get rid of the YAML header in .md docs generated as a byproduct of knitting .Rmd to .html.

More details:
I have a .Rmd file that I'm knitting to .html. I selected "Keep markdown source file" in the Output Options dialog so that knitting will additionally generate a ".md" version to be used as a README file on GitHub.

Knitting works fine. But when the .md file is displayed on Github, the YAML header from the .Rmd document is displayed at the top, like this:

This is by design: this article from Github announces their intention to display YAML this way.

Call me picky, but I don't love this display: I'd like to display a nicely-formatted .md document on Github without that YAML rendering at the top.

I know I can get around some of this by manually entering the title, author, and date using markdown headings in the body of the document, but I don't think there's a way to get rid of the "html_document" and "keep_md:true" notes at the top.

Is there a trick to this, or should I just learn to live with a little YAML?

Thanks!

[cderv]

Why not output 2 documents from your Rmd source: html_document() and github_document() ?

The result of the latter will be a Markdown file without YAML header and using the expected Github Flavor Markdown syntax.
The intermediary knitted file may have some content that won't be compatible with Github markdown rendering engine.

You can render all format at once by using output_format = "all" in rmarkdown::render.

Is it something you already tried ?

Also, the intermediary .md file you currently use needs to have the YAML header because this file is used by Pandoc to convert to the HTML and the info in the YAML are used. So there is no way you can remove yaml header from this file - you would need to post process it which is less interesting than producing a second format from your Rmd.

[kaijabean]

Thanks so much for this suggestion! I was not aware that I could knit to multiple formats at once, and I didn't even think to look into that.

I've now done some googling, and it seems like I should indeed be able to knit to both "html_document" and "github_document" at the same time, but I can't quite get there. Your suggestion seems to bypass the "knit" button by directly using the rmarkdown::render() function, and I'd like to be able to use the button.

I got most of the way there by following the suggestion shown here, but for some reason the html file is not knitting correctly. I get a nice .md file without the YAML at the top, but no .html. Any idea why?

This is my YAML:

output:
  html_document: default
  github_document: default
knit: (function(inputFile, encoding) {
  rmarkdown::render(inputFile, encoding = encoding,
  output_format = c("html_document", "github_document")) })

The knitting works well, but no html document is produced.

[kaijabean]

I should add: I did also try your suggestion to use output_format = "all", and I had the same problem: a nice .md document was produced, but no .html.

[cderv]

I think I know:

Try setting html_preview = FALSE in github_document

There is a conflict when using github_document and html_document together with the same output file name. This is because by default github_document() will generate a HTML preview that would overwrite the other document.

Try in the other order c("github_document", "html_document") and you should see the two files.

This is a bit of an issue, I think there is one open but can't find it.
Not a lot of user are generating two different output from a github README.
Note that this means you could have a HTML preview file generated if you use github_document(keep_html = TRUE). This HTML file will use a look and feel similar that what you should have on Github. So it will be different look that html_document()

Hope it clarifies.

And yes you need a trick if you want the knit button to generate both.

[kaijabean]

This works!

I'm just going to show the code for anyone who comes across this issue later.

Both of @cderv's recommendations fix my problem. So, this works:

output:
  html_document: default
  github_document: # can leave html_document first if you set `html_preview: false` under github_document.
    html_preview: false
knit: (function(inputFile, encoding) {
  rmarkdown::render(inputFile, encoding = encoding,
  output_format = "all") })

...and this also works:

output:
  github_document: default # put github_document *before* html_document
  html_document: default
knit: (function(inputFile, encoding) {
  rmarkdown::render(inputFile, encoding = encoding,
  output_format = "all") })

Thank you very, very much! It's so rare to get not one, but two workable solutions to a problem. You've been incredibly helpful

[kaijabean]

I went looking for the issue you referenced, and I found this. Looks like there is a third, even simpler way to accomplish what I'm trying to do: just set keep_html: true under github_document and remove html_document and the knit: function definition.

Code (as far as I can tell, this works the same as the previous two solutions):

---
output:
  github_document:
    keep_html: true
---

I think I'll go with this one, since it's neatest. It would be nice if this could be documented officially somewhere: maybe here, where I expected to find code to generate multiple output formats, or here? Not sure if @yihui is working on an update to that chapter, or if there's a more appropriate place for that documentation to go, but I didn't find it anywhere.

[cderv]

@kaijabean

Looks like there is a third, even simpler way to accomplish what I'm trying to do: just set keep_html: true under github_document and remove html_document and the knit: function definition.

This what I tried to explain above:

@cderv

Note that this means you could have a HTML preview file generated if you use github_document(keep_html = TRUE) . This HTML file will use a look and feel similar that what you should have on Github. So it will be different look that html_document()

The html you'll get using this method won't be the same as with html_document as it does not use the same template. But maybe that is what you want.

This is a bit documented in the format help page ?github_document

Convert to GitHub Flavored Markdown — github_document

[kaijabean]

Thanks. You're right, I didn't read your response carefully enough.

I'll look more into the differences between the two html formats, but I suspect that for my purposes it will be fine.