Add basic site

.devcontainer/NO_DEV_CONTAINERS.md

@@ -0,0 +1,14 @@
+# DevContainers
+
+This repository doesn't use dev containers primarily because:
+
+**File watching doesn't work for dev containers on Windows.**
+
+This means that Hugo's dev server wouldn't pick up any changes made to the site itself.
+
+This is a deal breaker because it defeats the primary purpose of using Hugo's dev server.
+
+There are also some secondary reasons:
+
+* Building the site inside the container is way slower. On my machine it took Hugo 1.6 seconds to build a site - and it took Hugo 12 seconds inside the dev container.
+* It adds a hugo amount of memory usage to the development process (the dev container usually takes about 4-6 GB of memory to run.)

.gitattributes

@@ -1,40 +1,70 @@
-# Prevent git from messing around with line endings.
+#
+# NOTE: To re-apply all changes in this file to the current repository, run:
+#
+#  1. git-clean.cmd/.sh
+#  2. git rm --cached -r .
+#  3. git add -A
+#
+# NOTE: On Windows, you need to restore the Linux executable bit after doing this via:
+#
+#   git add --chmod=+x <file>
+#
+# For details for each file, use:
+#
+#   git status -v
+#
+
+# Prevent git from messing around with line endings (i.e. treat all files as binary by default).
 * -text
 
-# Store binary files in git-lfs
-**/*.exe filter=lfs diff=lfs merge=lfs -text
-**/*.dll filter=lfs diff=lfs merge=lfs -text
-
-**/*.gif filter=lfs diff=lfs merge=lfs -text
-**/*.png filter=lfs diff=lfs merge=lfs -text
-**/*.jpg filter=lfs diff=lfs merge=lfs -text
-**/*.jpeg filter=lfs diff=lfs merge=lfs -text
-**/*.tif filter=lfs diff=lfs merge=lfs -text
-**/*.bmp filter=lfs diff=lfs merge=lfs -text
-**/*.ico filter=lfs diff=lfs merge=lfs -text
-**/*.cur filter=lfs diff=lfs merge=lfs -text
-
-**/*.avi filter=lfs diff=lfs merge=lfs -text
-**/*.mpg filter=lfs diff=lfs merge=lfs -text
-**/*.mpeg filter=lfs diff=lfs merge=lfs -text
-
-**/*.wav filter=lfs diff=lfs merge=lfs -text
-**/*.mp3 filter=lfs diff=lfs merge=lfs -text
-**/*.m4a filter=lfs diff=lfs merge=lfs -text
-
-**/*.zip filter=lfs diff=lfs merge=lfs -text
-**/*.gz filter=lfs diff=lfs merge=lfs -text
-
-**/*.ttf filter=lfs diff=lfs merge=lfs -text
-
-**/*.doc filter=lfs diff=lfs merge=lfs -text
-**/*.docx filter=lfs diff=lfs merge=lfs -text
-**/*.xls filter=lfs diff=lfs merge=lfs -text
-**/*.xlsx filter=lfs diff=lfs merge=lfs -text
-**/*.ppt filter=lfs diff=lfs merge=lfs -text
-**/*.pptx filter=lfs diff=lfs merge=lfs -text
-**/*.pdf filter=lfs diff=lfs merge=lfs -text
-**/*.xps filter=lfs diff=lfs merge=lfs -text
-**/*.rtf filter=lfs diff=lfs merge=lfs -text
-
-**/*.bin filter=lfs diff=lfs merge=lfs -text
+#
+# Binary files - stored in git-lfs
+#
+
+# Application files
+**/*.exe filter=lfs diff=lfs merge=lfs
+**/*.dll filter=lfs diff=lfs merge=lfs
+
+# Image files
+**/*.gif filter=lfs diff=lfs merge=lfs
+**/*.png filter=lfs diff=lfs merge=lfs
+**/*.jpg filter=lfs diff=lfs merge=lfs
+**/*.jpeg filter=lfs diff=lfs merge=lfs
+**/*.tif filter=lfs diff=lfs merge=lfs
+**/*.bmp filter=lfs diff=lfs merge=lfs
+**/*.ico filter=lfs diff=lfs merge=lfs
+**/*.cur filter=lfs diff=lfs merge=lfs
+
+# Movie files
+**/*.avi filter=lfs diff=lfs merge=lfs
+**/*.mpg filter=lfs diff=lfs merge=lfs
+**/*.mpeg filter=lfs diff=lfs merge=lfs
+
+# Audio files
+**/*.wav filter=lfs diff=lfs merge=lfs
+**/*.mp3 filter=lfs diff=lfs merge=lfs
+**/*.m4a filter=lfs diff=lfs merge=lfs
+
+# Archive files
+**/*.zip filter=lfs diff=lfs merge=lfs
+**/*.gz filter=lfs diff=lfs merge=lfs
+
+# Font files
+**/*.ttf filter=lfs diff=lfs merge=lfs
+**/*.otf filter=lfs diff=lfs merge=lfs
+**/*.woff filter=lfs diff=lfs merge=lfs
+**/*.woff2 filter=lfs diff=lfs merge=lfs
+
+# Office documents
+**/*.doc filter=lfs diff=lfs merge=lfs
+**/*.docx filter=lfs diff=lfs merge=lfs
+**/*.xls filter=lfs diff=lfs merge=lfs
+**/*.xlsx filter=lfs diff=lfs merge=lfs
+**/*.ppt filter=lfs diff=lfs merge=lfs
+**/*.pptx filter=lfs diff=lfs merge=lfs
+**/*.pdf filter=lfs diff=lfs merge=lfs
+**/*.xps filter=lfs diff=lfs merge=lfs
+**/*.rtf filter=lfs diff=lfs merge=lfs
+
+# Other binary files
+**/*.bin filter=lfs diff=lfs merge=lfs

.github/workflows/README.md

@@ -0,0 +1,17 @@
+# GitHub Action Workflows
+
+This folder contains the GitHub actions workflow files for this repository.
+
+**Documentation:** <https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions>
+
+**Default Environment Variables:** <https://docs.github.com/en/actions/learn-github-actions/variables#default-environment-variables>
+
+## Security Considerations
+
+* The `permissions` properties defines the permissions for the `GITHUB_TOKEN`. The default permission may be too permissive. So, it's a good idea to reduce the necessary permissions as much as possible.
+  * Also, the default permission differ based on whether the workflow runs for a pull request from a fork or from the same repository.
+  * Note that a regular build and test workflow usually only needs the `contents: read` permission.
+  * For more details, see: <https://docs.github.com/en/actions/reference/authentication-in-a-workflow#permissions-for-the-github_token>
+* For 3rd party actions (i.e. actions that don't come from `actions/`) it's recommended to use `@sha` rather than `@tag`. Reason: If the source repository gets hacked, the attacker can add malicious code (send secrets to they attacker's server) and change the tag to the commit with the malicious code. If you pin a certain `sha`, the action is not vulnerable to this type of attack.
+  * Of course, with this you don't automatically get newer (good) versions of the action. Make sure to subscribe the action for new releases.
+  * Technically, if the `GITHUB_TOKEN` permissions only include read permissions (and if you don't have any other secrets in your repository), it's not necessary to do this. But since nothing is every static, doing this even in this scenario is simply another safety net.

.github/workflows/build-and-deploy.yaml

@@ -0,0 +1,107 @@
+#
+# GitHub Actions workflow: Builds the site and uploads it to the target server.
+#
+# For more details on workflows, see README.md.
+#
+# See also: https://gohugo.io/hosting-and-deployment/hosting-on-github/
+#
+
+name: Build and Deploy
+
+# When to run this workflow
+# See: https://docs.github.com/en/actions/reference/events-that-trigger-workflows
+# See: https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#on
+on:
+  # Trigger the workflow on push to the main branch (i.e. don't publish from pull requests or other branches).
+  push:
+    branches:
+      - main
+  # Allows you to run this workflow manually from the Actions tab.
+  workflow_dispatch:
+  # TODO: Remove!!!!!
+  pull_request:
+    branches:
+      - main
+
+# Permissions for GITHUB_TOKEN for this workflow.
+#   See: https://docs.github.com/en/actions/reference/authentication-in-a-workflow#permissions-for-the-github_token
+# NOTE: Because of this, we don't use "@hash" but "@vX" for non-GitHub steps below. Usually you would use "@hash"
+#   as a security measure to pin a specific version. However, since we run with the minimal permissions
+#   here, malicious code couldn't do much harm (most likely).
+#   See: https://blog.gitguardian.com/github-actions-security-cheat-sheet/#use-specific-action-version-tags
+#permissions:
+#  contents: read
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+# https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#concurrency
+concurrency:
+  # Makes this workflow part of the "deploy" concurrency group. (Note that this text can be chosen arbitrarily.)
+  group: deploy
+  cancel-in-progress: false
+
+# NOTE: Jobs run in parallel by default.
+# https://docs.github.com/en/actions/using-jobs/using-jobs-in-a-workflow
+jobs:
+  build-and-deploy:
+    # Name the job
+    name: Build & Deploy
+    # Set the type of machine to run on
+    # See: https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idruns-on
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Install Hugo CLI
+        run: sudo snap install hugo
+
+      # See: https://github.com/actions/setup-node
+      - name: Setup NodeJS environment
+        uses: actions/setup-node@v4
+        with:
+          node-version: 'latest'
+
+      # See: https://github.com/actions/checkout
+      - name: Clone Git repository
+        uses: actions/checkout@v4
+        with:
+          lfs: true
+          submodules: true
+          # IMPORTANT: Fetch the whole history. This is how Hugo determines the (publish) dates for the articles!!!
+          fetch-depth: 0
+
+      - name: Download node modules
+        run: npm install
+        working-directory: themes/devlog-theme/assets
+
+      - name: Build site
+        # NOTE: We don't use "--minify" here so that the output remains better readable.
+        run: hugo --gc --printPathWarnings --logLevel info -d ./public/
+
+      # See: https://github.com/marketplace/actions/ftp-deploy
+      - name: Deploy site
+        uses: SamKirkland/[email protected]
+        with:
+          # See: https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions
+          server: ${{ secrets.ftp_server }}
+          username: ${{ secrets.ftp_username }}
+          password: ${{ secrets.ftp_password }}
+
+          # Use an encrypted FTP connection.
+          protocol: ftps
+
+          #log-level: verbose
+
+          # NOTE: This action actually compares file hashes to determine if a file needs to be uploaded.
+          local-dir: ./public/
+          server-dir: ./public_www/
+          state-name: ../sync-state.json
+
+          # NOTE: By default, "exclude" contains "node_modules". We have to remove this exclude rule because
+          #   we use this to ship fontawesome.
+          #   For default, see: https://github.com/marketplace/actions/ftp-deploy#exclude-files
+          # NOTE: Unfortunately, you don't seem to be able to clear the exclude options because it then will simply
+          #   use the default value again. So we keep some common sense value (even though we don't actually need to
+          #   exclude anything).
+          exclude: |
+            **/.git*
+            **/.git*/**

.gitignore

@@ -23,3 +23,6 @@
 #
 # Repository custom ignores
 #
+.hugo_build.lock
+resources/_gen/
+public/

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "themes/devlog-theme"]
+	path = themes/devlog-theme
+	url = https://github.com/skrysmanski/devlog-theme.git

.vscode/settings.json

@@ -1,8 +1,12 @@
 {
 	"cSpell.language": "en",
 	"cSpell.words": [
+		"callout",
 		"editorconfig",
-		"markdownlint"
+		"fontawesome",
+		"Krysmanski",
+		"markdownlint",
+		"webfonts"
 	],
 
 	"markdownlint.config": {
@@ -17,4 +21,7 @@
 		// Inconsistent code blocks are sometimes nicer to write
 		"MD046": false,
 	},
+	"yaml.schemas": {
+		"./hugo.schema.json": "hugo.yaml"
+	},
 }

archetypes/default.md

@@ -0,0 +1,6 @@
+---
+title: "{{ replace .Name "-" " " | title }}"
+date: {{ .Date }}
+draft: true
+---
+

content/_index.md

@@ -0,0 +1,5 @@
+---
+title: Manski's Dev Log # Just for OpenGraph
+---
+
+This site is a place for me to post things that I feel may be interesting or helpful to other people. I mainly post about programming related stuff.

content/articles/containers/devcontainers.md

@@ -0,0 +1,94 @@
+---
+title: DevContainers
+tags:
+- containers
+- docker
+- vscode
+---
+
+For now, this page is just a quick collection of notes on DevContainers (especially the VSCode integration).
+
+## VSCode DevContainers
+
+Usually, you have two files in the `.devcontainer` folder:
+
+### devcontainers.json
+
+```json
+// For format details, see: https://aka.ms/devcontainer.json
+// For getting started: https://code.visualstudio.com/docs/devcontainers/tutorial
+//
+// NOTES and TIPS:
+//
+// * To open a terminal inside the devcontainer, call "Terminal: Create New Terminal" from the VSCode command palette.
+// * On Windows, this requires Docker to run as "Linux containers" (not "Windows containers").
+//
+{
+    "name": "Hugo",
+    "build": {
+        "dockerfile": "Dockerfile"
+    },
+
+    // Container Features
+    // NOTE: Features may only be available for certain distros (often, only Debian/Ubuntu is supported but not Alpine).
+    // All available features: https://containers.dev/features
+    // Specification: https://containers.dev/implementors/features/
+    "features": {
+        "ghcr.io/devcontainers/features/common-utils:2": {
+            "installZsh": "true",
+            //"username": "node",
+            "upgradePackages": "true"
+        }/*,
+        "ghcr.io/devcontainers/features/node:1": {
+            "version": "none"
+        },
+        "ghcr.io/devcontainers/features/git:1": {
+            "version": "latest",
+            "ppa": "false"
+        }*/
+    },
+
+    // Configure tool-specific properties.
+    "customizations": {
+        // Configure properties specific to VS Code.
+        "vscode": {
+            // Add the IDs of extensions you want installed when the container is created.
+            "extensions": [
+                "editorconfig.editorconfig",
+                "davidanson.vscode-markdownlint",
+                "streetsidesoftware.code-spell-checker",
+                "ms-azuretools.vscode-docker"
+            ]
+        }
+    },
+
+    // Set *default* container specific settings.json values on container create.
+    /*"settings": {
+        "php.validate.executablePath": "/usr/local/bin/php"
+    },
+
+    */
+
+    // Use 'forwardPorts' to make a list of ports inside the container available locally.
+    "forwardPorts": [1313],
+
+    // Use 'postCreateCommand' to run commands after the container is created.
+    //"postCreateCommand": "yarn install --prod",
+
+    // Comment out connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
+    "remoteUser": "vscode"
+}
+```
+
+### Dockerfile
+
+```Dockfile
+# See: https://hugomods.com/docs/docker/
+# Image is Alpine based and contains both NodeJS and Git.
+FROM hugomods/hugo
+
+# Add Git LFS (not installed by default).
+RUN apk add --no-cache git-lfs
+
+EXPOSE 1313
+```