Update pull_request_template.md

.github/pull_request_template.md

@@ -24,10 +24,15 @@ for an explanation on how to use task lists-->
 
 <!-- Please check if the following steps are OK:-->
 
-- [ ] My tutorial or article is placed in a subfolder of `tutorials/content`
+- [ ] My tutorial or article is placed in a subfolder of `tutorials/content/`
+- [ ] The novel tutorial has a meaningful name, in relation to the content of the tutorial.
 - [ ] The filename of my tutorial or article is `index.md`. In case of an Rmarkdown tutorial I have knitted my `index.Rmd` to `index.md` (both files are pushed to the repo). 
-- [ ] I have included `tags` in the YAML header (see the tags listed in the [tutorials website side bar](https://inbo.github.io/tutorials/) for tags that have been used before)
-- [ ] I have added `categories` to the YAML header and my category tags are from the [list of category tags](https://github.com/inbo/tutorials/blob/master/static/list_of_categories)
+- `yaml` header:
+    - [ ] *(recommended)* I am included as author in the `authors` yaml tag, using `[MY_AUTHOR_ID]`. An author information file exists in `<tutorials>/data/authors/<author>.toml`.
+    - [ ] I have added `categories` to the YAML header and my category tags are from the [list of categories](https://github.com/inbo/tutorials/blob/master/static/list_of_categories).
+    - [ ] I have included meaningful and applicable `tags` (i.e. keywords) in the YAML header to improve the visibility of the new tutorial (see the tags listed in the [tutorials website side bar](https://inbo.github.io/tutorials/)).
+    - [ ] The `date` is in format `YYYY-MM-DD` and adjusted.
+- [ ] *(recommended)* I have previewed this PR locally (see steps below; ask previous contributors for help) and confirmed that the new content renders as expected.
 
 
 ## Previewing the pull request
@@ -38,9 +43,15 @@ This provides a way to preview how these updates will look on the website, usefu
 ### Instructions to preview the updated website
 
 1) On the PR page, you can find a "details" link under "checks - On PR, build the site and ...". Go there, click on the top link in the left sidebar ("Summary"), and download the generated artifact at the bottom of the page.
-2) Decompress it and make sure the target directory is called 'tutorials' (you may need to rename it)
-3) From the parent directory (just above the `tutorials` folder you created/renamed), run `python -m http.server 8887`, _or_ launch the Google Chrome [Web Server app](https://chrome.google.com/webstore/detail/web-server-for-chrome/ofhbbkphhbklhfoeikjpcbhemlocgigb) and point it at the parent directory.
-4) Point your browser to http://localhost:8887/tutorials.
+2) Decompress it into a target directory, e.g. `Downloads/tutorials_preview`.
+3) To preview the website, use a program which can serve `http` sites on your local machine. One such option is [the `servr` package](https://github.com/yihui/servr) in R: `& '\C:\Program Files\R\R-4.4.2\bin\Rscript.exe' -e "servr::httd('./tutorials_preview')" -p8887` (*make sure to adjust the path to your `Rscript.exe`*; on Linux, simply use `Rscript -e [...]`).
+4) Point your browser to http://localhost:8887.
 5) Review the updated website. As a contributor, you can push extra commits to update the PR. As a reviewer, you can accept/refuse/comment the PR.
 
-**Note: for step 3, you can use any other simple HTTP server to serve the current directory if you don't have a Python 3 environment or Google Chrome available.**
+**Note: for step 3, you can use any other simple HTTP server to serve the current directory, e.g. [Python `http.server`](https://docs.python.org/3/library/http.server.html): `python -m http.server 8887 --bind localhost --directory path/to/tutorials_preview`**
+
+
+### Alternative: Locally Building the Site
+
+Alternatively, you can build the entire site locally ([see the README for instructions](https://github.com/inbo/tutorials?tab=readme-ov-file#building-the-site)); the Hugo preview server will update changes on the fly.
+This requires [Hugo](https://gohugo.io/getting-started) to be installed on your computer.

content/create_tutorial/index.md

@@ -15,7 +15,7 @@ In this page, the roadmap towards a new tutorial will be explained.
 
 ## Writing a tutorial
 
-Each tutorial is setup in a subfolder of the `content/tutorials` folder. Within this folder, different files and formats may exist as you create them, but a file with the name `index.md` will be used for the tutorials website. So, you can create the tutorial directly in markdown or create it based on a [Rmarkdown](https://rmarkdown.rstudio.com/), a [Jupyter notebook](https://jupyter.org/) or any other format, as long as there is a single markdown file with the name `index.md` in your tutorial folder. 
+Each tutorial is setup in a subfolder of the `content/tutorials` folder. Within this folder, different files and formats may exist as you create them, but a file with the name `index.md` will be used for the tutorials website. So, you can create the tutorial directly in markdown or create it based on a [Rmarkdown](https://rmarkdown.rstudio.com/), a [Jupyter notebook](https://jupyter.org/), [quarto](https://quarto.org/docs/output-formats/hugo.html) or any other format, as long as there is a single markdown file with the name `index.md` in your tutorial folder. 
 
 There are different ways to create this file. We will provide in this document specific instructions for markdown an Rmarkdown based tutorials. Still, if you got useful information or text in another format or you got stuck with the description, do not hesitate to describe your submission in a [new issue ](https://github.com/inbo/tutorials/issues/new). If you do not have a Github account, ask the [IT helpdesk](mailto:ict.helpdesk@inbo.be). We will try to support you as soon as possible. 
 
@@ -94,13 +94,13 @@ Next, click `commit new file` and your submission will be reviewed by the websit
 
 When you ever used git or Github before, either using the command line, rstudio, Github Desktop,... you can work on your own computer and submit the tutorial using git.  In this section, we assume you are familiar to the git command or interface and have some basic knowledge. If not, no worries, we have a dedicated course to get you up to speed, see the [INBO git course](https://inbo.github.io/git-course/).
 
-_**Notice**: The links in the different steps will refer to the Rstudio steps in the INBO git tutorial, but can be done using other interfaces or the command line as well. Pick the one you prefer_
+_**Notice**: The links in the different steps will refer to the Rstudio steps in the INBO git tutorial, but can be done using other interfaces or the command line as well. Pick the one you prefer._
 
 If it is your first submission using your computer, [clone](https://inbo.github.io/git-course/course_rstudio.html#23_clone_a_repo_to_work_locally) the [INBO tutorials](https://github.com/inbo/tutorials) repository (*so use the clone button on the https://github.com/inbo/tutorials page!*).
 
 Next, we use the [git workflow](https://inbo.github.io/git-course/workflow_rstudio.html) to submit the new tutorial:
 
-- Update your code and create a new branch, cfr. [STEP 1 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#option-1a-ill-make-a-new-branch-to-work-with). Provide a useful name for your branch related to the topic of your tutorial, e.g. `r_tidy_data` or `database_query_inboveg` and not ~~`my_tutorial`~~.
+- Update your code and create a new branch, *cf.* [STEP 1 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#option-1a-ill-make-a-new-branch-to-work-with). Provide a useful name for your branch related to the topic of your tutorial, e.g. `r_tidy_data` or `database_query_inboveg` and not ~~`my_tutorial`~~.
 - Navigate to the subfolder `content/tutorials` and create a new subfolder in this directory. This will be the directory of your tutorial. Again, use a representative name for the directory name similar to the branch name. 
 - Within the folder, create a new file markdown `index.md`.  The header of this file has an agreed format and you should copy paste this to start with:
 
@@ -128,7 +128,7 @@ Replace all the CAPITAL words with appropriate information:
 
 Underneath the last triple dahs (`---`), you can write the tutorial as you like using [markdown syntax](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).
 
-- `add`/`commit` the file to git, cfr. [STEP 2 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#while_editing). You can commit the tutorial all in once or split the commits in different steps, that is up to you. To make sure your work is updated online as well, `push` the tutorial as in [STEP 3 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#step_3:_push_your_changes_to_github).
+- `add`/`commit` the file to git, *cf.* [STEP 2 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#while_editing). You can commit the tutorial all in once or split the commits in different steps, that is up to you. To make sure your work is updated online as well, `push` the tutorial as in [STEP 3 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#step_3:_push_your_changes_to_github).
 - When ready, `push` your tutorial a last time and create a `Pull request` to the website maintainers as explained in [STEP 4 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#step_4:_pull_request_to_add_your_changes_to_the_current_master).
 
 After you pull request, your submission will be checked and reviewed. When accepted and merged, you tutorial will be online.
@@ -141,7 +141,7 @@ If it is your first submission using your computer, [clone](https://inbo.github.
 
 Next, we use the [git workflow](https://inbo.github.io/git-course/workflow_rstudio.html) to submit the new tutorial:
 
-- Update your code and create a new branch, cfr. [STEP 1 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#option-1a-ill-make-a-new-branch-to-work-with). Provide a useful name for your branch related to the topic of your tutorial, e.g. `r_tidy_data` or `database_query_inboveg` and not ~~`my_tutorial`~~.
+- Update your code and create a new branch, *cf.* [STEP 1 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#option-1a-ill-make-a-new-branch-to-work-with). Provide a useful name for your branch related to the topic of your tutorial, e.g. `r_tidy_data` or `database_query_inboveg` and not ~~`my_tutorial`~~.
 - Navigate to the subfolder `content/tutorials` and create a new subfolder in this directory. This will be the directory of your tutorial. Again, use a representative name for the directory name similar to the branch name. 
 - Within the folder, create a new file markdown `index.Rmd`.  The header of this file has an agreed format and you should copy paste this to start with:
 
@@ -172,15 +172,15 @@ Replace all the CAPITAL words with appropriate information:
 - multiple tags you can pick yourself, all lowercase words. Have a look at the current [wordcloud](https://inbo.github.io/tutorials/tags/) to check which would be useful for your submission.
 - leave the `output` section as it is
 
-Underneath the last triple dahs (`---`), you can write the tutorial as you like using [markdown syntax](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) and add code chunks to run R code. 
+Underneath the last triple dash (`---`), you can write the tutorial as you like using [markdown syntax](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) and add code chunks to run R code. 
 
 As the Rmarkown file will not be part of the website, make sure to click the `knit` button to create the equivalent markdown file (`index.md`) in the same directory:
 
 ![](images/knit_md.png)
 
 **Notice**: always knit the Rmarkdown file before you start committing the changes!
 
-- `add`/`commit` **both files** to git, cfr. [STEP 2 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#while_editing). You can commit the tutorial all in once or split the commits in different steps, that is up to you. To make sure your work is updated online as well, `push` the tutorial as in [STEP 3 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#step_3:_push_your_changes_to_github).
+- `add`/`commit` **both files** to git, *cf.* [STEP 2 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#while_editing). You can commit the tutorial all in once or split the commits in different steps, that is up to you. To make sure your work is updated online as well, `push` the tutorial as in [STEP 3 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#step_3:_push_your_changes_to_github).
 - When ready, `push` your tutorial a last time and create a `Pull request` to the website maintainers as explained in [STEP 4 of the workflow](https://inbo.github.io/git-course/workflow_rstudio.html#step_4:_pull_request_to_add_your_changes_to_the_current_master).
 
 After you pull request, your submission will be checked and reviewed. When accepted and merged, you tutorial will be online.