Move custom hugodown Rmd archetype to project root

[apreshill]

Currently with create_site_academic() the function overwrites the default post archetype with an index.Rmd file in: themes/academic/archetypes/post/. But, if a user updates their Hugo theme (which is recommended periodically), this archetype will be overwritten. Would you consider instead writing to archetypes/post/ in the project root? That would be more robust, and encourage good practices w/r/t updating themes when running into errors (just like we encourage folks to update their R packages).

[hadley]

I tried that, but then you get both index.md and index.Rmd in the post — i.e. the archetypes are unioned together. (There's a note to that effect in the comments which is how I remembered 😄)

I'm also not sure that regularly updating themes is a good idea, or something that we should be recommending. The hugo stack is sufficiently fragile that regularly updating is likely to break stuff as much as fix it. For example, the latest released version of academic doesn't work with the latest released version of hugo. This is a different situation to R because CRAN checks that the latest version of all packages work together; nothing plays that role in the hugo ecosystem.

[apreshill]

Oy. Yes, because the extension is different. And I agree that the stack is fragile and I appreciate trying to insulate users from some of that. On the other hand, editing the themes/ folder feels brittle. There are a number of really good reasons to update a theme/Hugo (and the Academic theme attempts to support this with versioning, updating guides, etc). I would rather not discourage it, and I've found with teaching Hugo that I cannot not talk about it.

Also given the issues with HTML widgets (issue #36), one recommendation to users might be to add a custom page parameter (like to disable jquery), which they'll also need to add to an archetype. So many folks will likely need to override the hugodown version with a local archetype at some point.

All that said, here are 2 possible alternative strategies to consider:

1. hugodown deletes the original post archetype provided by the theme in themes/ but adds the .Rmd archetype in the project root of the same name (this is my least preferred solution, as it will still get overwritten)

2. hugodown keeps the original post archetype provided by the theme in themes/ but adds the .Rmd archetype in the project root called post-rmd or rmd-post, and then use_post() uses the Rmd version as the default kind. Less seamless than the current setup, but more robust and transparent what hugodown is actually doing, which I like.

[jemus42]

I might misunderstand the issue, but is it not possible to use /archetypes/ to override /themes/archetypes, as is possible with a regular hugo site to prevent users having to "dirty" /themes/? This is what I do with my blog, but I admittedly use neither academic nor (currently) hugodown.

[apreshill]

@jemus42 because the extensions differ, you get what @hadley mentioned:

"I tried that, but then you get both index.md and index.Rmd in the post — i.e. the archetypes are unioned together. (There's a note to that effect in the comments which is how I remembered 😄)"

[hadley]

What if we had an update_site_academic() that would reapply our changes to the themes directory?

[apreshill]

Yes, that would be a good way to provide a clean slate too (if they do accidentally change a file in the theme).

[hadley]

I've refactored create_site_academic() to make updating easier in the future. We can look at that in more detail when 4.9.0 is released.