Repository structure

Repository structure

This repository contains both the body of the notes and the files that are used to render them into HTML so that they can be read by any browser. All the notes about a given subject should be included under the same directory.

Each directory should contain at least an index.md file that will be the source for the first page shown to the user when they click on a subject on the main page. Other markdown files may be included in the same directory, along with the assets (images and such) that are required by said files.

On each push to the main branch of the repository, a GitHub action will be triggered. Said action performs three main things:

• notes are converted from markdown to HTML;
• index page is updated to include all the new notes;
• everything is deployed on GitHub pages.

This repository uses pandoc both to convert markdown to HTML and as a template engine to place the produced HTML into a standardized page that will be the same for all the notes. Fore more information about the structure of the markdown files containing the body of the notes, see here.

To produce the main index.html landing page, we use a nastro adesivo approach that basically consists in using find&replace to write the list of all the available notes programmatically into the file.

A Docker container (that includes all the tools used to make all of this work) is provided. This container is also the same used by the GitHub action.