Skip to main content
DEVELOPERNOTES

Setup

Install this repository and all submodules via git clone --recurse-submodules https://gitlab.com/davidsneighbour/kollitsch.dev.git. If you have cloned the repository before reading this, run git submodule update --init --recursive to get the submodules up-to-date.

Prepare the development environment

  • Hugo (Installation instructions)
  • Node.js (I recommend using NVM to install Node.js)
  • Bash (available on any self-respecting operating system)
  • Shellcheck (snap install -channel=edge shellcheck)
  • Running npm install will add all set-up requirements
  • Copy .env.sample to .env and specify the values used by scripts and the build systems for various tasks. You MUST NOT commit the .env file to the repository for privacy and security reasons. Take notes of your configuration data somewhere safe, like in Keybase or a password manager.
  • Setup signed tags with npm config set sign-git-tag true

Advanced setup steps

  • GitHub Actions: To enable the step to debug logging for the GitHub Workflows, you must set the following secret in the repository that contains the workflow: ACTIONS_STEP_DEBUG to true. You find the settings page by following Settings > Secrets > Actions from the repositories home page.

Pre-Commit

Install and set up pre-commit to lint commits for quality and security. Python is required for this. Then run the following commands to set up pre-commit locally:

1pip install pre-commit
2pre-commit install

Other pre-commit commands are: If you installed pre-commit and one of your commits won’t “get through” due to some weird overzealous configuration, you can always commit manually via git commit --no-verify; use your brain on this one.

SSL/TLS setup

Hugo introduced a new SSL feature in v0.113.0. The setup is still quite manual, but it’s a start. To enable SSL/TLS, you need to do the following:

Development

Dev Setup

Set IP and PORT for your local machine in .env. IP MAY also be a hostname (without protocol).

1IP=192.168.1.201
2PORT=1313

This configures the Hugo server so you can access the site from other machines (and mobile devices) in your local network. Again: you MUST NOT commit this file to any public code versioning system as it contains private information.

To start the development server, run npm run server, which runs the Hugo server with more or less paranoid settings (show translation issues, template issues, be verbose, debug, the more, the better). For example, running just hugo server will start Hugo on localhost:1313.

Release

Sidenote: I use these scripts only if I want to create a new minor or major release of the website. All other “releases” are done when deploying the website (see Deploy).

  • Create patch release with npm run release or npm run release:patch
  • Create minor release with npm run release:minor
  • Create major release with npm run release:major

Deploy

As noted, this repository is optimized for Netlify. To create a local copy of the website, run npm run build or ./bin/netlify/build.

Running npm run deploy creates a new tag in the main branch and deploys the site on Netlify.

Theme

The theme is part of this repository, mainly in the layouts folder.

Paradigms

  • Spacing (margin and padding) is applied from top to bottom.
  • We use responsive design principles with mobile-first. No unnecessary rows inside of rows (container>row>col>row>col) if this isn’t explicitly required. It isn’t needed anyway.
  • Do re-use and recycle styles.

Netlify setup

1npm install netlify-cli -g && netlify login
2netlify --telemetry-disable // shouldn't that be the default?
3netlify init
4netlify build

If any errors come up while running this, then fix them.


In this section

  • Overview
  • Configuration
  • Developernotes — Setup Install this repository and all submodules via git clone –recurse-submodules https://gitlab.com/davidsneighbour/kollitsch.dev.git. If you have cloned the repository before reading this, run git submodule update –init –recursive to get the submodules up-to-date. Prepare the development environment Hugo (Installation instructions) Node.
  • Content — [!WARNING] This documentation is under (re)construction. Check back later for changes and feel free to open an issue if you have questions or suggestions. General notes Content Archetypes This website has the following archetypes with their respective front matters and features:
  • Hook and Filters — [!WARNING] This documentation is under (re)construction. Check back later for changes and feel free to open an issue if you have questions or suggestions. General notes Hooks are listed in their order of appearance. Hook File Runs Depends on Description init partials/init.
  • Troubleshooting — Inkscape Generating the component cards requires Inkscape and optipng. Install them with the following: bash COPY 1sudo apt install inkscape optipng
Back to top
Back Forward