Procedural creation of project pages on Github - free GH Pages hosting and node.js script

.
GitHub Pages is a free hosting service that allows you to publish static HTML pages. However, it does not support running server-side scripts, which means no support for backend languages such as PHP, Python or Ruby. In this tutorial, I will show a potential way around this limitation - procedural HTML generation using Node.js via GitHub Actions.

Node.js is a server-side JavaScript runtime environment that allows us to create web applications, generate files and automate various processes. With Node.js, for example, we can write a script that dynamically creates static HTML files, which can then be published on GitHub Pages. In this way, we can, to a certain extent, 'simulate' a backend on a static host and, more precisely, generate all the expected pages 'for the future'.

GitHub Actions is a tool for automating processes in the GitHub repository. It allows the creation of so-called workflows that can run automatically, e.g. with each push to the repository.

The aim of the project is to automatically create device pages for my list of programmable IoT hardware . I already have one aggregate page-search engine that takes data from a JSON file and runs in the browser, but in addition I want each device to have a separate link with its own page.

This is where the first doubt arises - but how can Node.js if you can't run server-side scripts? Indeed, you can't run server-side scripts, but during changes to the repository you can run a one-time GitHub Workflow which will generate static HTML and save it to the gh-pages branch.

So the organisation of the repository will look as follows:
- branch main contains the main information we provide, the source data, in my example it will be a JSON file with device information
- branch gh-pages will be empty by default
- in addition, in branch main there will be a GitHub workflow which, at the time of each change in main, parses the JSON file and generates static HTML files and writes them to gh pages, which then publishes them on GitHub

Generate HTML locally (on your own computer) .
Let's consider the contents of the main branch. The most important file there is devices.json, here is an example of the contents:
.
It describes the devices for which we want to generate pages.
Now you can add the JS script that will do this.
We need in turn:
- clear the old GH Pages content
- load the devices.json file
- spell out each device object and generate HTML for it into a separate file to the gh-pages branch
Minimal example, deletion section:
.
Loading JSON, creating a folder for the devices and iterating:


Device processing function:

pageNameForDevice converts the name of the manufacturer and model of the device into a page name, and sanitizeFilename makes sure it is file system friendly. Not all characters can be in file names. We are left with createDeviceHTML. Here is an example implementation:
.
. For clarity I have removed the HTML file - the latest version of the script can be seen here: https://github.com/OpenBekenIOT/webapp/blob/main/generate-devices.js .
The code above has a few features added from me, such as displaying the GPIO of the device, but this is not relevant to this example.

Now it's time to test how the system works - we run the script via node.js:
.
The whole thing should execute correctly and generate files for our JSON database:
.


Generate HTML on GitHub (automatically with each change to the main branch) .
We have already developed the generation of HTML files for each device from a JSON file and tested this locally with Node.js. Now it's time to go one step further. GitHub allows us to automatically perform operations with every change on a branch, we can use this to automatically run our script and save the results to gh pages. This way every, even the smallest, change to the data in devices.json will update our documentation.
We create a file .github/workflows/gh-pages.yml :
.
Let's consider the operation of this script. The script is called after a push to the main branch. Then, on a machine with the latest version of ubuntu, first Node.js is installed and then the script developed earlier is executed. The results are then saved to gh-pages, i.e. published on GitHub.

Verified working on GitHub .
Let's see how this works in practice. I've added some changes via the GitHub GUI:
.
A commit with a "bird" appears on GitHub:
.
In the preview we have information about the success of the deploy operation:
.
In the details we have the entire log of the operation:
.
Now we can look at the gh-pages branch:
.
There is a devices folder generated on it:
.
Our HTML files are also in it:
.


Final result .
The HTML itself is beyond the scope of this presentation, so I'll just write that I also modified the search engine to link to the generated device pages. The result is available here:
https://openbekeniot.github.io/webapp/devicesList.html
Example device page:
https://openbekeniot.github.io/webapp/devices/Tuya_ATLO_SW1_TUYA.html
From now on, each device has its own page where I can additionally display configuration tips and links to related topics on Elektroda.

Direct link to the repository (for reference):
https://github.com/OpenBekenIOT/webapp

Summary .
GitHub only offers hosting of static HTML code, but clever use of GitHub Actions allows you to automatically pregenerate any kind of page which then mimics a site with a dynamic backend.. For finer work, on the other hand, you can harness JavaScript, on which my main search engine is based - fully client-side. I think this is a convenient and practical solution and will probably use it more than once.
PS: In a separate topic I will show how the same mechanism can be used to automatically generate project documentation.
PS2: Anticipating the question - I put the code snippets as images due to the limitations of our forum. Javascript was turning on spam protection and I couldn't save the topic....