Tutorials

This repository contains the source files for the INBO tutorials website: a collection of instructions on the use, installation and development of research software at the Research Institute of Nature and Forest (INBO).

Adding content

New tutorials should go in a new directory in content/tutorials. Use plain markdown files (.md) as much a possible. Use Rmarkdown files (.Rmd) when calculations in R are required. For more information about creating a new tutorial, check the create tutorial page.

Reviewing the website in a pull request (before merging)

Thanks to GitHub Actions, an artifact (=zip file) of the rendered website is now automatically created on each pull request. Learn more about showing the development website of a pull request in your browser.

Building the site

The technology used to create the website is Hugo, a static website generator. Hugo will process all the markdown files - ignoring Rmd, which is why these need to be knit beforehand - and create the necessary files (html, css, js) for the website. These are served from the gh-pages branch.

GitHub actions

GitHub actions will automatically run the steps above (install Hugo, download theme, run Hugo, deploy website) for every commit to the master branch. You will see in the actions page if the build was successful. If not, check the logs to figure out what went wrong.

Building the site on your local computer

1. Install hugo
2. Clone the tutorials repository
3. In the cloned tutorials directory, install the theme with git clone https://github.com/MunifTanjim/minimo.git --branch v2.9.0 themes/minimo
4. Build and serve the site with hugo server

For more information, see Hugo's getting started documentation.

Customizing the theme

The tutorials website makes use of the Hugo theme minimo. This theme is not included in the repository, but downloaded by GitHub pages at build time. This avoids clutter and changes to the theme itself. To customize the theme:

1. Browse the layouts directory in the minimo repository to see which template file you want to customize
2. Copy the template file to the same path in the layouts directory of this repository
3. Edit the file to the desired effect. E.g. this update to the original minimo file adds a "edit this page" link for every page.
4. Hugo will now use your customized file instead of the default theme file.

For more information, see the Hugo theme customization documentation. To test theme customization, it is best to build the site on your local computer (see above).

Contributors

List of contributors

License

Creative Commons Attribution for content / MIT License for source code.