suckowbiz/simplepast repository overview

⁠SimplePast

SimplePast is a HTML/CSS/JavaSript based framework to publish a weblog on the World Wide Web.

It comes with a CLI called articlectl to create file based news posts.

⁠Features

The intention to implement SimplePast was to have a weblog that is easy to maintain and to setup. Further it should be able to run for months/years without relevant need for changes. This is achieved by:

• Lean architecture to apply KISS.
• Convention-over-configuration to keep configuration simple.
• Relying on containerized infrastructure to isolate the framework and package all requirements.
• File based storage to avoid database maintenance.
• Vanilla JavaScript and no external JS frameworks to keep the dependencies low.
• A handfull of freely available (MIT licensed) libraries to not reinvent the wheel.
• Semantic Versionning to enable a transparent release process.

⁠How it Works

SimplePast publishes text entries (articles) together with multimedia files such as images and/ or videos. Articles are displayed in reverse chronological order so that the most recent post appears first, at the top of the web page. Articles are grouped in years.

SimplePast runs in a Docker container, based on Caddy webserver. It mounts a configuration file to set up properties and an article folder that contains all postings.

JavaScript is executed on the client side, only. The client requests meta information from the server. This information is made available via JSON files.

⁠Basic Usage

Steps, to configure and run SimplePast:

1. Create a configuration file to set up SimplePlast:

   $ wget https://raw.githubusercontent.com/suckowbiz/simplepast/main/blueprints/config.json
   

   Copy

2. Create a local file storage as a root for articles. Consider current year as initial article folder:

   $ mkdir --parent articles/2023
   

   Copy

3. Bootstrap the first article to have content to display:

   $ docker run \
       --tty \
       --user $(id -u):$(id -g) \
       --volume $PWD/articles:/articles \
       suckowbiz/articlectl bootstrap /articles/2023/1
   
   $ .
     └── articles
         └── 2023
             └── 1
                 ├── content.txt
                 ├── date.txt
                 ├── heading.txt
                 ├── img
                 └── vid
   

   Copy

4. Provide news content to customize the bootstrapped article:

   $ vi articles/2023/1/content.txt
   $ vi articles/2023/1/heading.txt
   # (optional) place images into articles/2023/1/img/
   # (optional) place video(s) into articles/2023/1/vid/
   

   Copy

5. Use articlectl to create thumbnails and resize images of the created article.

   $ docker run \
       --tty \
       --user $(id -u):$(id -g) \
       --volume $PWD/articles:/articles \
       suckowbiz/articlectl mogrify /articles/2023/1
   

   Copy

6. Run SimplePast to publish the created article:

   # This example follows the basic Caddy example as of https://hub.docker.com/_/caddy.
   $ docker run \
       --rm \
       --name simplepast \
       --publish 80:80 \
       --volume $PWD/articles:/usr/share/caddy/articles \
       --volume $PWD/config.json:/usr/share/caddy/config.json \
       suckowbiz/simplepast
   

   Copy

7. Visit: https://localhost

⁠Customization

⁠(Caddy) Webserver Configuration

The SimplePlast Dockerfile is directly inheriting the official Caddy Dockerfile. Thus all options/examples of the official Caddy Dockerfile apply. See https://hub.docker.com/_/caddy⁠ for configuration options.

⁠SimplePast Configuration

The configuration options are:

⁠Frontpage Banner

Replace the default frontpage banner with a new one to customize it. It is assumed the new banner image is located at ./banner.png:

$ docker run -p 80:80 \
    --volume $PWD/articles:/usr/share/caddy/articles \
    --volume $PWD/config.json:/usr/share/caddy/config.json \
    --volume $PWD/banner.png:/usr/share/caddy/banner.png \
    suckowbiz/simplepast

⁠Google Site Verification

E.g. to verify ownership of a domain, Google requires a HTML site. SimplePast support verification meta tag. It can be configured with the SimplePast config option: googleSiteVerificationContent.

⁠3rd Party Software

SimplePast uses third party libraries to provide a web GUI:

• Twitter Bootstrap⁠ as frontend toolkit.
  License: MIT⁠
• Fontawesome⁠ as icon library.
  License: Free License⁠
• masonry⁠ for cascading grid layout.
  License: MIT⁠
• imagesloaded⁠ to detect when images have been loaded.
  License: MIT⁠
• PhotoSwipe⁠ as lightbox.
  License: MIT⁠

⁠SimplePast License

SimplePast is licensed under MIT license.