explain archetypes

vignettes/config.Rmd

@@ -14,6 +14,8 @@ knitr::opts_chunk$set(
 )
 ```
 
+You need to read and apply this article if you wish to use hugodown on a website you did not create with a hugodown function `create_site_`.
+
 There are three types of configuration related to hugodown:
 
 -   hugo configuration, because hugodown assumes certain things to be true about your hugo setup.
@@ -55,7 +57,7 @@ hugodown does not work with every possible hugo site. There is some config that
           {{ . | safeHTML }}
         {{ end }}
 
--   To use mathjax, you will need to use a series of [small hacks][yihui-mathjax]. The easiest way is to copy from an existing template, like [tourmaline]. Take note of the [`footer_mathjax.html`][footer\_mathjax] partial, which is then included in the [`footer.html`][footer]. You'll also need to include [`math_code.js`][math\_code] in your `static/` directory. Once that's done you can use inline math like `$math$`, and display math like `` `$$ math $$` `` (note the extra backtick compared to usual).
+-   To use mathjax, you will need to use a series of [small hacks][yihui-mathjax]. The easiest way is to copy from an existing template, like [hugo-graphite](https://github.com/rstudio/hugo-graphite). Take note of the [`footer_mathjax.html`](https://github.com/rstudio/hugo-graphite/blob/master/layouts/partials/footer_mathjax.html) partial, which is then included in the [`footer.html`](https://github.com/rstudio/hugo-graphite/blob/master/layouts/partials/footer.html). You'll also need to include [`math_code.js`](https://github.com/rstudio/hugo-graphite/blob/master/static/js/math-code.js) in your `static/` directory. Once that's done you can use inline math like `$math$`, and display math like `` `$$ math $$` `` (note the extra backtick compared to usual).
 
 ## Syntax highlighting {#syntax-highlighting}
 
@@ -110,6 +112,65 @@ From easiest to hardest, based on the theme you chose:
 
 ## hugodown
 
+### Configuration file
+
 hugodown also has its own configuration file, `_hugodown.yaml`. Currently this has one option:
 
 -   `hugo_version`: this defines the version of hugo needed by the current site.
+
+### Archetype
+
+How to tweak your website to be able to use `use_post()` for creating new posts?
+
+You need [archetypes](https://gohugo.io/content-management/archetypes) i.e. templates!
+
+In practice you have to add a file called index.Rmd under `archetypes/post/index.Rmd` (one for each folder of post e.g. both `archetypes/post/index.Rmd` and `archetypes/talk/index.Rmd`; unless all your posts live in post/ or unless you define a default archetype under `archetypes/default/index.Rmd`).
+Note that hugodown use leaf bundles i.e. creates posts in a dedicated folder per post, as a file called index.Rmd.
+
+In hugodown archetypes
+
+* are found via Hugo so follow Hugo rules for finding which archetype to use for which path. 
+* use whisker so you can add variables to be filled-in.
+
+Every archetype e.g. `archetypes/post/index.Rmd` needs this line:
+
+```yaml
+output: hugodown::md_document
+```
+
+Now, `use_post()` will pass default data (date, author, slug) to the archetype, and also any data you enter via the `data` argument e.g. `use_post(data = list(category = "R", title = "yeah yeah"))` --- you can also override default data via the `data` argument if you e.g. don't want today as a date.
+
+To have this data _used_ you need [whisker](https://github.com/edwindj/whiske) syntax in the archetype.
+
+Very basic:
+
+```yaml
+date: {{ date }}
+author: {{ author }}
+```
+
+More: if you write `use_post("post/my-new-post", data = list(title = "Wow cool", category = "R"))` and if the archetype contains
+
+```yaml
+title: "{{ title }}"
+category: {{ category }}
+```
+
+the new post created will contain
+
+```yaml
+title: "Wow cool"
+category: R
+```
+
+To summarize, here's possible metadata in an `archetypes/post/index.Rmd` archetype.
+
+```yaml
+---
+output: hugodown::md_document
+date: {{ date }}
+author: {{ author }}
+title: "{{ title }}"
+category: {{ category }}
+---
+```