This is the website setup and content for kollitsch.dev. The site is hosted on Netlify and built via GoHugo and most of this repository is specifically set up to work on Netlify and use its features. Feel free to open an issue to ask questions, find out undocumented details, or to suggest improvements.
- General notes
- Setup
- Development
- Releasing
- Deployment
- Theme
- Advanced setup
- Netlify setup
- Hooks (WIP)
- Front matter parameters
- Linting
- License
- Troubleshooting
- The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119.
- I am working on Ubuntu which means that all code samples in this document are for Ubuntu. If you are using another operating system then you are on your own. I assume though due to the usage of open source that most tools, scripts and procedures will work on other systems too with the appropriate changes.
- Hugo
- Node.js
- Bash
- Shellcheck (
snap install -channel=edge shellcheck
)
- Copy
.env.sample
to.env
and fill in the values. This is 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 Keybase. - To set up Algolia search fill in the API information from your Algolia-Dashboard > API keys.
- Run
npm install
to install all dependencies.
If you want then install and set up pre-commit
to lint commits for quality and security. This requires Python to be installed. Then run the following commands to set up pre-commit
locally:
pip install pre-commit
pre-commit install
Other pre-commit
commands are:
pre-commit run blocklint -all-files # check specific hook on all files
pre-commit run -all-files # check rules on all files
pre-commit autoupdate # update repositories
pre-commit gc # garbage collection
If you installed pre-commit and one of your commits won't "get through" due to some weird overzealous configuration, then you can always commit manually via git commit -no-verify
. Use your brain on this one.
Make sure to have set IP
and PORT
for your local machine in .env
. IP
can also be a hostname (without protocol in the beginning).
IP=192.168.1.201
PORT=1313
This configures the Hugo server so that you can access the server from other machines (and mobile devices). Again: you must not commit this file to the repository as it might contain private information.
To start the development server run npm run server
. This runs the Hugo server with more or less paranoid settings (show translation issues, template issues, be verbose, debug, the more the better). Running just hugo server
starts Hugo on localhost:1313.
- Setup signed tags with
npm config set sign-git-tag true
- Create patch release with
npm run release
ornpm run release:patch
- Create minor release with
npm run release:minor
- Create major release with
npm run release:major
This repository is optimised for Netlify. To create a local copy of the website run npm run build
or ./bin/netlify/build
.
- running
npm run release
creates a new tag in themain
branch and release on Netlify.
The theme is part of this repository.
- Spacing is applied from top to bottom, meaning that margins are applied to the bottom of items.
- Responsive design principles are applied as mobile-first.
- No rows inside of rows (container>row>col>row>col) if this isn't explicitly required. It probably isn't required anyway.
- Do reuse and recycle styles.
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 for this by following Settings > Secrets > Actions
from the repositories home page.
npm install netlify-cli -g && netlify login
netlify --telemetry-disable // yeah, well, shouldn't that be default?
netlify init
netlify build
If any errors come up while running this then fix them.
Hooks are listed in their order of appearance
Hook | File | Runs | Depends on | Description |
---|---|---|---|---|
init | partials/init.html | 1 | before anything else runs (before pagination object is created) | |
init-end | partials/init.html | 1 | after the pagination object is created and in scratch | |
setup | _default/baseof.html | 1 | at the beginning of the main layout | |
body-start | _default/baseof.html | 1 | ||
body-end-pre-script | _default/baseof.html | 1 | ||
body-end | _default/baseof.html | 1 | ||
teardown | _default/baseof.html | 1 |
Sample:
theme:
comments: false
The following front matter parameters exist to fine-tune the layouts and theme options:
comments
- set to false to turn off comment forms and display (default: true)showdate
- set to false to turn off date per post display (default: true)
kollitsch.dev uses Vale to lint markdown content files. Styles and vocab are saved in tests/vale
.
Installation:
snap install --edge vale
Run tests:
vale content
vale README.md
npm run lint:vale
VSCode Plugin:
Install the Vale plugin. No configuration is required.
The content of this project itself is licensed under the CC BY-NC-SA 4.0, and the underlying source code used to format and display that content is licensed under the MIT License.
White this repository is available publicly, all content
is subject to copyright and may not be re-used or copied into other website projects. The content
is everything in the content
folder or documentation. Other parts of this project like assets
and layouts
are available for educational uses and can be used. The theme in its full may not be reused, but studied and parts reused.
Long story short: go and create something by yourself and if you want to know how a feature on this website was realised feel free to have a look.
Generating the component cards requires Inkscape and optipng. Install them with:
sudo apt install inkscape optipng