GroundLayer Website

Website created with WordPress and served as a static website with GitHub Pages.

Introduction

The website is built with WordPress on the local machine and the static website files (HTML, CSS, and JavaScript are exported and saved in a separate directory. The files in this directory are then served as a static website by GitHub Pages.

The project is based on the following tools:

Local: tool for running WordPress on a local machine (alternative to installing WordPress manually)
Simply Static: WordPress plugin for exporting a WordPress website as a static website
GitHub Pages: GitHub's service for serving static websites

The WordPress theme used for the website is Aeonium.

Directory structure

The repository contains of the following main directories:

wordpress: contains the WordPress project for the website being built
docs: contains the exported static website files to be served by GitHub Pages

Note: GitHub Pages can only serve from the / or /docs directories, which is the reason that the above directory containing "docs" and not something more pertinent like "site".

The following auxiliary directories also exist in the repository:

logo: contains design files for the website logo
scripts: contains various utility scripts

Initial setup

To start developing the website on a new machine, the following steps must be performed initially:

Install Local
Clone the repository
Import the WordPress website into Local
Log in to WordPress
Set up the Simply Static plugin

In the following, each step is described in more detail.

1. Install Local

On macOS, Local can be installed with Homebrew:

brew install local

For other platforms, the installers can be obtained from the Local website.

2. Clone the repository

git clone https://github.com/weibeld/groundlayer

3. Import website into Local

From the repository root directory, run the following script:
```
scripts/import.sh
```
This script adjusts the hardcoded project path in the SQL database file (wordpress/app/sql/local.sql), zips the resulting wordpress directory to wordpress.zip, and empties the current wordpress directory. This is necessary to correctly import the project into Local.
In Local, click File > Import site and select the wordpress.zip file created above
In the Local import dialog, use the following settings (you may need to click on Advanced options in the first dialog window):
- Local site name: groundlayer (may be something else too)
- Local site domain: groundlayer.local (may be something else too)
- Local site path: the (currently empty) wordpress directory in the repo (must be exactly this)
After the import, the wordpress directory should be populated with files again.
In Local, click on Open site and verify that the website displays correctly
In the repository, run git status to see if any files changed, and, if so, commit the changes

3. Log in to WordPress

In Local, click on WP Admin to open the WordPress Admin Dashboard for the website
Use the following credentials for the login dialog:
- Username: admin
- Password: admin

Note: these credentials are hardcoded in the WordPress project. Since this WordPress installation is only used locally and never exposed to the internet, no secure credentials are necessary.

4. Set up the Simply Static plugin

In the WordPress Admin Dashboard, go to Simply Static > Settings and ensure the following settings:

Delivery Method: Local Directory
Local Directory: the docs directory in the repository

TODO: after this issue has been fixed, add the following step: Simply Static > Settings > Advanced, check Clear local directory before export.

Editing the website

After the initial setup, the website can be edited as follows:

Edit the website through WordPress as usual
In Local, restart the website with right-click > Restart
- This step is necessary to ensure that the changes in WordPress are written to disk
In WordPress, export the static website files with Simply Static > Generate > Generate Static Files
In the repository, commit and push the changes

After the changes have been pushed, the new version of the website is automatically picked up and served by GitHub Pages.

Misc

Assets

Convert SVG files to PNG images (with a fixed with or height) with the following command:

for f in *.svg; do inkscape "$f" -w 200 -o "${f%.*}".png; done

Inkscape can be installed on macOS with brew install inkscape.

Change the colours of a PNG file with the following command:

convert file.png -fill "#ABCDEF" -colorize 100 file-out.png