README.md

Pi4J website

Build state:

Sources of the documentation website of the Pi4J project.

Contribute

If you want to contribute to this website, make a fork and create a merge request.

New release

When a new release of Pi4J is created, following has to be modified in this website:

• Root _index.md: update version and date
• about/release-notes.md: update the content to match the new version

Created with GoHugo

This website is created with the static site generator Hugo.

Theme

Uses the Hugo-theme-learn.

Special layout components are explained on learn.netlify.app/en/shortcodes.

Text format

All pages are separate md-files inside the content directory. The formatting of the text needs to use the rules specified in commonmark.org.

Notes can be included like this:

{{% notice note %}}
GITHUB PROJECT: [https://github.com/Pi4J/pi4j-logo](https://github.com/Pi4J/pi4j-logo)
{{% /notice %}}

Available types:

• notice note: blue box
• notice tip: green box
• notice warning: red box

Example:

{{% notice tip %}}
Feel free to check the [Kotlin DSL for Serial](/kotlin/serial/)
{{% /notice %}}

Images

Location for images

Upload new images to /static/assets/ (please use a subdirectory per chapter).

Single image

To include a single image in your content use the following structure:

![DESCRIPTION](/assets/DIR/FILE)

For example:

![Wiring of a LED and button for the minimal example](/assets/getting-started/minimal/led-button_bb.png)

Gallery image view

For multiple images a gallery view can be used thanks to the integration of Hugo Easy Gallery.

Example use:

{{< gallery >}}
{{< figure link="/assets/DIR/FILE" caption="DESCRIPTION" caption-position="center" caption-effect="fade" >}}
{{< figure link="/assets/DIR/FILE" caption="DESCRIPTION" caption-position="center" caption-effect="fade" >}}
{{< /gallery >}}
{{< load-photoswipe >}}

Please note {{< load-photoswipe >}}, the last line only must be added once per page if multiple galleries are used.

For example:

{{< gallery >}}
{{< figure link="/assets/featured-projects/didier/IMG_20210831_125559-small.jpg" caption="Robot picture 1" caption-position="center" caption-effect="fade" >}}
{{< figure link="/assets/featured-projects/didier/IMG_20210831_125615-small.jpg" caption="Robot picture 2" caption-position="center" caption-effect="fade" >}}
{{< figure link="/assets/featured-projects/didier/IMG_20210920_083431-small.jpg" caption="Robot picture 3" caption-position="center" caption-effect="fade" >}}
{{< /gallery >}}
{{< load-photoswipe >}}

Test locally

To test the site locally, first install Hugo as described on "Install Hugo".

Example, for Mac:

brew install hugo

To run the site, open the terminal in the directory with the sources of this site and run the following command:

cd pi4j.github.io
hugo serve

The website is now available on localhost:1313.

Build and run on GitHub Pages

Using a GitHub Action, the site is published on each commit into the main branch of this repository.

The "docs" directory is auto-generated by this GitHub Action so should never be manually touched. This directory is pushed to GitHub Pages.

This process is described here:

• Automate your GitHub Pages Deployment using Hugo and Actions
• Deploy Hugo project to GitHub Pages with GitHub Actions