[pull] main from dwmkerr:main

.github/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+## [0.3.2](https://github.com/dwmkerr/hacker-laws/compare/v0.3.1...v0.3.2) (2025-03-31)
+
+
+### Bug Fixes
+
+* update ebook download link ([4546562](https://github.com/dwmkerr/hacker-laws/commit/454656237d9508c8fadafffbc1c1286fc134f8cf))
+
+## [0.3.1](https://github.com/dwmkerr/hacker-laws/compare/v0.3.0...v0.3.1) (2025-03-31)
+
+
+### Bug Fixes
+
+* effective shell links ([6353fe4](https://github.com/dwmkerr/hacker-laws/commit/6353fe4b8f044456d66dac0af950e41989c56c5a))
+
+## [0.3.0](https://github.com/dwmkerr/hacker-laws/compare/v0.2.1...v0.3.0) (2025-03-31)
+
+
+### Features
+
+* add Koomey's Law ([dcdcfdf](https://github.com/dwmkerr/hacker-laws/commit/dcdcfdfc25ee121b6bcb931a71e185fa7ffeedcd))
+
+## [0.2.1](https://github.com/dwmkerr/hacker-laws/compare/v0.2.0...v0.2.1) (2025-03-31)
+
+
+### Bug Fixes
+
+* remove frontmatter ([2140429](https://github.com/dwmkerr/hacker-laws/commit/2140429b959a8284b452c3fa05e1c9fd03e5ebab))
+
+## [0.2.0](https://github.com/dwmkerr/hacker-laws/compare/v0.1.0...v0.2.0) (2025-03-31)
+
+
+### Features
+
+* 90-90 rule ([4477907](https://github.com/dwmkerr/hacker-laws/commit/44779074caa6495198214100e5bd0a886cc1e680))
+* add section for Kerckhoff's principle ([5f74607](https://github.com/dwmkerr/hacker-laws/commit/5f74607c63d3a76009ec0546ba515f8f7c1d3864))
+* add ukranian language to README ([#320](https://github.com/dwmkerr/hacker-laws/issues/320)) ([015d251](https://github.com/dwmkerr/hacker-laws/commit/015d25197f808d66c4dfebcdd0b54675af6a3eae)), closes [#236](https://github.com/dwmkerr/hacker-laws/issues/236)
+* Dunning Kruger Effect ([3dbc237](https://github.com/dwmkerr/hacker-laws/commit/3dbc237c1f1c59e809969320cc0ae4347a4b45c3))
+* Dunning-Kruger Effect ([#318](https://github.com/dwmkerr/hacker-laws/issues/318)) ([34c38d8](https://github.com/dwmkerr/hacker-laws/commit/34c38d87edba4b0e36d2ad9488b97d0c77f9b550))
+* **pages:** update index.html and pages.yaml for deployment ([beb3d57](https://github.com/dwmkerr/hacker-laws/commit/beb3d57a6a5a3a38aa9e692ed13eb01060b85ded))
+* principle of least astonishment ([4be4827](https://github.com/dwmkerr/hacker-laws/commit/4be482731b6a6009453af7d303d3cd2470a2e73e))
+* principle of least astonishment ([e4662cb](https://github.com/dwmkerr/hacker-laws/commit/e4662cbc27d04fb968220837633034420b7fb11a))
+* the scout rule ([716aef8](https://github.com/dwmkerr/hacker-laws/commit/716aef807e758bd8df976f323089db525da9f708))
+* the scout rule ([c6fccf4](https://github.com/dwmkerr/hacker-laws/commit/c6fccf4978d9483637fba8c7887127abad3de581)), closes [#144](https://github.com/dwmkerr/hacker-laws/issues/144)
+* twyman's law ([b9ad4c6](https://github.com/dwmkerr/hacker-laws/commit/b9ad4c6f99f991a1bda9a2cfdddef62787e6ae82))
+
+
+### Bug Fixes
+
+* correct facebook link on website ([6f9b1e3](https://github.com/dwmkerr/hacker-laws/commit/6f9b1e33345bc1332428f0fba8c7aa2900147500))
+* correct formatting around quote ([d83d439](https://github.com/dwmkerr/hacker-laws/commit/d83d439df89e8af50ae53bafa3a791f8d92a6991))
+* Fix section's links ([#317](https://github.com/dwmkerr/hacker-laws/issues/317)) ([7b341fc](https://github.com/dwmkerr/hacker-laws/commit/7b341fc0d205f076e25ff8fedb972e652201c3c6))
+* image paths ([692b7cc](https://github.com/dwmkerr/hacker-laws/commit/692b7cca1a97eb62384db170297b504f51ea408e))
+* remove superfluous 'is' ([3b78ae6](https://github.com/dwmkerr/hacker-laws/commit/3b78ae65f02fca457bb8adbf113135e1ed042a46))

.github/contributing.md

@@ -2,12 +2,13 @@
 
 <!-- vim-markdown-toc GFM -->
 
-* [Goal of the Project](#goal-of-the-project)
-* [Example Law: The Law of Leaky Abstractions](#example-law-the-law-of-leaky-abstractions)
-* [Translations](#translations)
-* [How do I know if a law is relevant?](#how-do-i-know-if-a-law-is-relevant)
-* [How do I know if a law is 'well known' enough?](#how-do-i-know-if-a-law-is-well-known-enough)
-* [Use of Images](#use-of-images)
+- [Goal of the Project](#goal-of-the-project)
+- [Example Law: The Law of Leaky Abstractions](#example-law-the-law-of-leaky-abstractions)
+- [Translations](#translations)
+- [How do I know if a law is relevant?](#how-do-i-know-if-a-law-is-relevant)
+- [How do I know if a law is 'well known' enough?](#how-do-i-know-if-a-law-is-well-known-enough)
+- [Use of Images](#use-of-images)
+- [Developer Guide](#developer-guide)
 
 <!-- vim-markdown-toc -->
 
@@ -87,3 +88,18 @@ A good test is 'If I search for it on Google, will I find it in the first few re
 ## Use of Images
 
 Please make sure to attribute images properly if you are referencing them. Also, include a white background, as some viewers will be viewing the site in 'Dark Mode' which can make images with a transparent background difficult to read.
+
+## Developer Guide
+
+Where possible, anything which is not the core `README.md` file is kept in the `.github/` folder to keep the landing page for the repository as clean as possible.
+
+To use the makefile, pass its path explicitly, e.g:
+
+```bash
+make -f .github/makefile
+```
+
+Or create an alias:
+
+```bash
+alias hlmake="make -f .github/makefile"

.github/makefile

@@ -0,0 +1,22 @@
+default: help
+
+.PHONY: help
+help: # Show help for each of the Makefile recipes.
+	@grep -E '^[a-zA-Z0-9 -]+:.*#'  Makefile | sort | while read -r l; do printf "\033[1;32m$$(echo $$l | cut -f 1 -d':')\033[00m:$$(echo $$l | cut -f 2- -d'#')\n"; done
+
+.PHONY: prepare-markdown
+prepare-markdown: # Prepare the markdown for PDF output.
+	./scripts/prepare-markdown-for-ebook.sh "README.md" "hacker-laws.md"
+
+.PHONY: create-pdf
+create-pdf: # Create the PDF.
+	docker run --rm \
+		--platform linux/amd64 \
+		-v ${PWD}:/data \
+		pandoc/latex:3.6 \
+		-V toc-title:"Table Of Contents" \
+		--toc \
+		--pdf-engine=lualatex \
+		--standalone \
+		--output hacker-laws.pdf \
+		hacker-laws.md

.github/release-please-config.json

@@ -0,0 +1,18 @@
+{
+  "release-type": "simple",
+  "bump-minor-pre-major": true,
+  "packages": {
+    ".": {
+      "release-type": "simple",
+      "extra-files": [
+        {
+          "type": "generic",
+          "path": "README.md"
+        }
+      ],
+     "changelog-path": ".github/CHANGELOG.md"
+    }
+  }
+}
+
+

.github/release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.3.2"
+}

.github/website/src/index.html.jinja

@@ -59,10 +59,8 @@
         {{ section.full_content | safe }}
         <div class="social-sharing">
           <a href="https://twitter.com/intent/tweet?url=https://hacker-laws.com/#{{ section.id}}?hashtags=example" title="Share on Twitter" target="_blank"><i class="bi bi-twitter"></i></a>
-          <a href="https://facebook.com/share?url=https://hacker-laws.com/&num;{{ section.id }}" title="Share on Facebook" target="_blank"><i class="bi bi-facebook"></i></a>
-          <a href="#" onclick="navigator.clipboard.writeText(window.location.href + '#{{ section.id }}'); alert('Copied!');" title="Copy Link" target="_blank"><i class="bi bi-clipboard"></i></a>
+          <a href="https://www.facebook.com/sharer/sharer.php?u=https://hacker-laws.com/&num;{{ section.id }}" title="Share on Facebook" target="_blank"><i class="bi bi-facebook"></i></a>
         </div>
-        <div class="back-to-top"><a href="#top">↑ Back to Top</a></div>
       </section>
       {% endfor %}
 

.github/website/src/script.js

@@ -15,4 +15,7 @@ $(document).ready(function() {
         // Append to the heading
         $heading.append($anchor);
     });
+
+    //  Bootstrap requires that blockquote elements have the 'blockquote' class.
+    $('blockquote').addClass('blockquote').addClass('.quote');
 });

.github/website/src/styles.css

@@ -11,17 +11,24 @@ body {
 .container {
   max-width: 800px;
 }
+
 header {
   text-align: center;
   margin-bottom: 2rem;
   padding: 2rem 0;
   border-bottom: 1px solid #e5e5e5;
 }
+
 h1, h2, h3, h4, h5, h6 {
   font-family: 'Libre Baskerville', serif;
   /* Avoid scrolling under the sticky header. */
   scroll-margin-top: 80px;
 }
+
+blockquote {
+  font-style: italic;
+}
+
 .law-section {
   margin-bottom: 2rem;
   padding: 1.5rem;

.github/workflows/cicd.yaml

@@ -0,0 +1,110 @@
+name: CI/CD
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+# Permissions to check contents and open PR (release pleases) and update pages.
+permissions:
+  contents: write
+  pull-requests: write
+  pages: write
+  id-token: write
+
+jobs:
+  test-website-build:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Test Website Build
+        run: |
+          cd .github/website
+          make install
+          make build
+          cp -r build/. '../pages'
+          ls -al "../pages"
+
+  release:
+    needs: test-website-build
+    runs-on: ubuntu-24.04
+    outputs:
+      released: ${{ steps.release-please.outputs.release_created }}
+      tag: ${{ steps.release-please.outputs.tag_name }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release-please
+        with:
+          manifest-file: .github/release-please-manifest.json
+          config-file: .github/release-please-config.json
+
+  release-pdf:
+    runs-on: ubuntu-24.04
+    needs: release
+    if: ${{ needs.release.outputs.released }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # Set a descriptive version. For PRs it'll be the short sha.
+      - name: Check Version
+        run: echo "${VERSION}"
+        env:
+          VERSION: ${{ needs.release.outputs.tag }}
+
+      # Set a descriptive version. For PRs it'll be the short sha.
+      - name: Prepare Markdown
+        run: |
+          # Set the env vars we use (version set for clarity).
+          export DATE=$(date +%F)
+          export VERSION="${VERSION}"
+          make -f .github/makefile prepare-markdown
+        env:
+          VERSION: ${{ needs.release.outputs.tag }}
+
+      # Create the PDF files.
+      - name: Create PDF
+        run: make -f .github/makefile create-pdf
+
+      # Publish the PDF and intermediate markdown as an artifact.
+      # - name: Publish PDF Artifact
+      #   uses: actions/upload-artifact@3
+      #   with:
+      #     name: hacker-laws.pdf
+      #     path: hacker-laws.pdf
+
+      - name: Attach assets to GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release upload "${{ needs.release.outputs.tag }}" --clobber hacker-laws.pdf hacker-laws.md
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-24.04
+    needs: release
+    if: ${{ needs.release.outputs.released }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Build Website
+        run: |
+          cd .github/website
+          make install
+          make build
+          cp -r build/. '../pages'
+          ls -al "../pages"
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './.github/pages'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4