TBD Workshop

This repository contains Workshop Materials for TBD.

Init

This section contains hints for the setup of new workshop materials. It can be deleted once the initial setup has been completed.

Create project

See https://github.com/experimental-software/workshop-materials#getting-started

Setup checklist

• Update license information
• Update dummy config
• Update dummy home page text
• Update dummy subject
• Add legal text to imprint
• Replace all occurences of the placeholder "TBD"
• Create publish script or GitHub Action
• What should be in the .gitignore?
• Optional: Update reveal.js in upstream Hugo theme.

Publish script

Here is an example how a publish.sh script might look like:

#!/usr/bin/env bash

set -e

hugo
rsync -r public/* [email protected]:example-workshop
rsync -r public/.htaccess [email protected]:example-workshop

GitHub Action

If the workshop materials should be in a public repository and hosted by GitHub Pages, then they can be automatically published after each commit with the help of GitHub Actions.

Refer to https://github.com/peaceiris/actions-hugo#getting-started for instructions how to setup a GitHub Action for the Hugo-based workshop materials.

License

This template repository is licensed under the CreativeCommons Zero license.

Development

Clone repository

Use the following command to clone the repository:

ORG=experimental-software
REPO=example
git clone --recurse [email protected]:${ORG}/${REPO}.git

Run Hugo server

To a development server that always re-renders after every change, run the following command:

hugo server

Build website

To generate the HTML for publication, run the following command:

hugo --destination docs/

Content authoring

Page structure

https://fontawesome.com/v5/search?m=free&s=solid%2Cbrands

Tutorials

Tutorials provide the use with a step-by-step guide for a complex scenario. The content can be created using Markdown syntax.

Run the following command to add a new presentation in the content directory:

hugo new --kind tutorial subject-two/my-tutorial

Articles

Articles provide a free-text page for guides for simple scenarios. The content can be created using Markdown syntax.

Run the following command to add a new article in the content directory:

hugo new --kind article subject-two/my-tutorial

Presentations

Presentations provide slides for a high-level overview over a topic. The content can be created using plain HTML with the reveal.js syntax.

Run the following command to add a new presentation in the content directory:

hugo new --kind presentation subject-two/my-presentation

Markdown extentions

Along with the Markdown syntax, you can use the following custom Hugo shortcodes:

Info callout box

{{< info >}}
Lorem [impsum](https://example.com) dolor sit amet.
{{< /info >}}

Tip callout box

{{< tip >}}
Lorem [impsum](https://example.com) dolor sit amet.
{{< /tip >}}

Warning callout box

{{< warning >}}
Lorem [impsum](https://example.com) dolor sit amet.
{{< /warning >}}

Table

{{< bootstrap-table table_class="table table-bordered" >}}

| Key | Value |
|--|--|
| `content-type` | `application/x-www-form-urlencoded` |

{{< /bootstrap-table >}}

Maintenance

Improve theme

Usually, while working on the contents of a workshop, it turns out that the theme needs some improvements. Follow those steps in a workshop repository, to get started with improving the theme.

cd themes/workshop-materials
{
git remote remove origin
git remote add origin [email protected]:experimental-software/workshop-materials.git
git fetch origin
git checkout master
git branch --set-upstream-to=origin/master
}

Update theme

{
git submodule update --remote
git add .
git commit -m "Update theme"
}

git push 

License

TBD