yaml documentation: _site.yml vs yaml in .Rmd

[shannonpileggi]

Hi distill developers! Thank you so much for your work on this package, I am so thankful for its existence!

One thing that I struggled with in getting started with distill, and still struggle a bit with, is understanding all the options for the yaml in distill, and furthermore, understanding how the options may be used in an individual .Rmd for a blog post vs the _site.yml. In addition, I am also unclear as to whether this means I should read Rmarkdown documentation more generally or focus on distill documentation.

There is a lot of great content regarding the yaml throughout the distill documentation, which has helped me tremendously, and I thank you for that! Is there a single comprehensive list that lays out all the options? If it does exist and I have missed it, my sincere apologies, and please disregard this issue.

The closest to a full list that I have found is in the documentation for ymlthis. Questions I have about the various yaml options include:

• Is this option specific to distill or is it a more general Rmarkdown yaml option? (Maybe that could help with understanding which documentation to read for futher help.)
• Should this option be used in _site.yml, the yaml of a .Rmd, or possibly both?
• If possibly both, does one option override the other? Do they serve the same purpose or a different purpose?

For example, I have base_url in both my _site.yml and the yaml of my .Rmds. I think this would be the answers to the above questions:

• the base_url is a yaml option specific to distill
• the base_url can be specified in either the _site.yml or the yaml of a .Rmd
• when specified, it serves different purposes. _site.yml is for an RSS feed, .Rmd is for social media posts

Is this correct?

Thank you for taking the time to read this verbose issue! Please let me know if I can further clarify anything.

[EllaKaye]

Hello.

Firstly, I'd like to echo @shannonpileggi with my thanks for your work on distill and my deep love and appreciate of this package 😄

I am also experiencing some confusion about this issue, with things not working quite as I might have expected. For example, I have a custom syntax highlighting theme. In my _site.yml, I have this for output:

output:
  distill::distill_article:
    highlight: /Users/ellakaye/ellakaye-distill/ek_syntax_highlighting.theme
    includes:
      in_header:
      - _includes/header.html
      - _includes/utterances.html

However, when I create and knit a new post, it still highlights with the default theme. If I put the exact same above line for highlight in the yaml of the .Rmd file for the post, the post picks up my custom file just fine. I would have thought that having the theme specific in the _site.yml would apply it site wide, but am I wrong about that, or is this a glitch?

Another strange thing that's happening, which, again, I can't figure out is to be expected or glitchy, is in relation to adding utterances. I follow the guidance in this blogpost My utterances.html file is here, a tiny tweak on Miles McBain's. If I just knit posts, everything works as expected, but as soon as I build the site either using the 'Build Website' button in RStudio or using rmarkdown::render_site, the utterances comment box appears on the listings pages for my posts and talks. I raised this with Miles in this issue and he thought is was something glitchy. I have a workaround (unstaging the chunks where the script gets added to _site/posts.html and _site/talks.html before committing) but it's a bit clunky.