dev: standardise github workflow and mkdocs configuration

.github/CODEOWNERS

@@ -3,4 +3,4 @@
 # Default owner accounts for the current repository
 # Automatically added as a reviewr to all pull requests (not including drafts)
 
-*  @practicalli-john
+*  @practicalli-johnny

.github/config/gitleaks.toml

@@ -0,0 +1,23 @@
+title = "gitleaks config"
+
+[allowlist]
+description = "global allow lists"
+paths = [
+    '''gitleaks.toml''',
+    '''(.*?)(jpg|gif|doc|docx|zip|xls|pdf|bin|svg|socket)$''',
+    '''(go.mod|go.sum)$''',
+    '''gradle.lockfile''',
+    '''node_modules''',
+    '''package-lock.json''',
+    '''pnpm-lock.yaml''',
+    '''Database.refactorlog''',
+    '''vendor''',
+]
+
+[[rules]]
+description = "AWS Example API Key"
+id = "aws-example-api-key"
+regex = '''AKIAIOSFODNN7EXAMPLE'''
+keywords = [
+    "awstoken",
+]

.github/config/lychee.toml

@@ -0,0 +1,24 @@
+
+# ---------------------------------------- 
+# Base URL or website root directory to check relative URLs.
+base = "https://practical.li/"
+
+# Only test links with the given schemes (e.g. https).
+# Omit to check links with any other scheme.
+# At the moment, we support http, https, file, and mailto.
+scheme = ["https"]
+
+# ---------------------------------------- 
+# Exclusions
+
+# Exclude URLs and mail addresses from checking (supports regex).
+# exclude = ['^https://www\.linkedin\.com', '^https://web\.archive\.org/web/']
+
+# Exclude all private IPs from checking.
+# Equivalent to setting `exclude_private`, `exclude_link_local`, and
+# `exclude_loopback` to true.
+exclude_all_private = false
+
+# Check mail addresses
+include_mail = false
+# ---------------------------------------- 

.github/config/markdown-lint.jsonc

@@ -244,13 +244,19 @@
   "MD045": true,
 
   // MD046/code-block-style - Code block style
-  "MD046": false,
+  "MD046": {
+    // Block style
+    "style": "consistent"
+  },
 
   // MD047/single-trailing-newline - Files should end with a single newline character
   "MD047": true,
 
   // MD048/code-fence-style - Code fence style
-  "MD048": false,
+  "MD048": {
+    // Code fence style
+    "style": "consistent"
+  },
 
   // MD049/emphasis-style - Emphasis style should be consistent
   "MD049": {

.github/config/megalinter.yaml

@@ -2,10 +2,15 @@
 # Configuration file for MegaLinter
 #
 # General configuration:
-# https://oxsecurity.github.io/megalinter/configuration/
+# https://megalinter.io/latest/configuration/
 #
 # Specific Linters:
-# https://oxsecurity.github.io/megalinter/latest/supported-linters/
+# https://megalinter.io/latest/supported-linters/
+
+# ------------------------
+# Validate all files if true
+# or new / edited files if false
+VALIDATE_ALL_CODEBASE: false
 
 # ------------------------
 # Linters
@@ -29,6 +34,7 @@ ENABLE:
 
 # CLOJURE_CLJ_KONDO_CONFIG_FILE: ".github/config/clj-kondo-ci-config.edn"
 # CLOJURE_CLJ_KONDO_ARGUMENTS: "--lint deps.edn"
+# CLOJURE_CLJ_KONDO_FILTER_REGEX_EXCLUDE: "dev|develop"
 # CLOJURE_CLJ_KONDO_FILTER_REGEX_EXCLUDE: "resources"
 
 # CREDENTIALS_SECRETLINT_DISABLE_ERRORS: true
@@ -43,11 +49,13 @@ MARKDOWN_MARKDOWN_LINK_CHECK_CONFIG_FILE: ".github/config/markdown-link-check.js
 MARKDOWN_REMARK_LINT_DISABLE_ERRORS: true
 # MARKDOWN_MARKDOWN_TABLE_FORMATTER_DISABLE_ERRORS: false
 
+REPOSITORY_GITLEAKS_CONFIG_FILE: ".github/config/gitleaks.toml"
 REPOSITORY_TRUFFLEHOG_DISABLE_ERRORS: true # Errors only as warnings
 
 # SPELL_CSPELL_DISABLE_ERRORS: true
 SPELL_MISSPELL_DISABLE_ERRORS: true
-SPELL_LYCHEE_DISABLE_ERRORS: true # Errors are only warnings
+SPELL_LYCHEE_CONFIG_FILE: ".github/config/lychee.toml"
+# SPELL_LYCHEE_DISABLE_ERRORS: true # Errors are only warnings
 
 # YAML_PRETTIER_FILTER_REGEX_EXCLUDE: (docs/)
 # YAML_YAMLLINT_FILTER_REGEX_EXCLUDE: (docs/)
@@ -85,7 +93,6 @@ SHOW_ELAPSED_TIME: true
 
 # Upload reports to file.io
 FILEIO_REPORTER: false
-
 # ------------------------
 
 # ------------------------

.github/pull_request_template.md

@@ -1,3 +1,13 @@
+:memo: Description
+
+
+:white_check_mark: Checklist
+
+- [ ] Commits should be cryptographically signed (SSH or GPG)
+
+
+## Practicalli Guidelines
+
 Please follow these guidelines when submitting a pull request
 
 - refer to all relevant issues, using `#` followed by the issue number (or paste full link to the issue)
@@ -20,4 +30,4 @@ Please raise an issue so we can discuss changes first, especially changes relate
 
 ## Review process
 
-All pull requests are reviewed by @practicalli-john and feedback provided, usually the same day but please be patient.
+All pull requests are reviewed by @practicalli-johnny and feedback provided, usually the same day but please be patient.

.github/workflows/changelog-check.yaml

@@ -6,7 +6,6 @@ on:
   pull_request:
     paths-ignore:
       - "README.md"
-      - "CHANGELOG.md"
     types: [opened, synchronize, reopened, ready_for_review, labeled, unlabeled]
 
 jobs:
@@ -20,10 +19,15 @@ jobs:
 
       # Git Checkout
       - name: Checkout Code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
-          token: "${{ secrets.PAT || secrets.GITHUB_TOKEN }}"
-      - run: echo "🐙 ${{ github.repository }} repository was cloned to the runner."
+          fetch-depth: 0
+          sparse-checkout: |
+            docs
+            overrides
+            .github
+            CHANGELOG.md
+      - run: echo "🐙 Sparse Checkout of ${{ github.repository }} repository to the CI runner."
 
       # Changelog Enforcer
       - name: Changelog Enforcer

.github/workflows/megalinter.yaml

@@ -7,9 +7,9 @@ name: MegaLinter
 on:
   workflow_dispatch:
   pull_request:
-    branches: [ main ]
+    branches: [main]
   push:
-    branches: [ main ]
+    branches: [main]
 
 # Run Linters in parallel
 # Cancel running job if new job is triggered
@@ -28,11 +28,14 @@ jobs:
 
       # Git Checkout
       - name: Checkout Code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
-          token: "${{ secrets.PAT || secrets.GITHUB_TOKEN }}"
           fetch-depth: 0
-      - run: echo "🐙 ${{ github.repository }} repository was cloned to the runner."
+          sparse-checkout: |
+            docs
+            overrides
+            .github
+      - run: echo "🐙 Sparse Checkout of ${{ github.repository }} repository to the CI runner."
 
       # MegaLinter Configuration
       - name: MegaLinter Run
@@ -51,7 +54,7 @@ jobs:
       # Upload MegaLinter artifacts
       - name: Archive production artifacts
         if: ${{ success() }} || ${{ failure() }}
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: MegaLinter reports
           path: |

.github/workflows/publish-book.yaml

@@ -22,18 +22,38 @@ permissions:
   contents: write
 
 jobs:
-  deploy:
+  publish-book:
+    name: MkDocs Publish
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - run: echo "🚀 Job automatically triggered by ${{ github.event_name }}"
+      - run: echo "🐧 Job running on ${{ runner.os }} server"
+      - run: echo "🐙 Using ${{ github.ref }} branch from ${{ github.repository }} repository"
+
+      - name: Checkout Code
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - uses: actions/setup-python@v4
+          sparse-checkout: |
+            docs
+            overrides
+      - run: echo "🐙 ${{ github.repository }} repository sparse-checkout to the CI runner."
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
         with:
           python-version: 3.x
-      - uses: actions/cache@v3
+
+      - name: Cache
+        uses: actions/cache@v4
         with:
           key: ${{ github.ref }}
           path: .cache
+
       - run: pip install mkdocs-material mkdocs-callouts mkdocs-glightbox mkdocs-git-revision-date-localized-plugin mkdocs-redirects pillow cairosvg
       - run: mkdocs gh-deploy --force
+      - run: echo "🐙 ."
+
+      # Summary and status
+      - run: echo "🎨 MkDocs Publish Book workflow completed"
+      - run: echo "🍏 Job status is ${{ job.status }}."

.github/workflows/scheduled-version-check.yaml

@@ -31,10 +31,13 @@ jobs:
       - run: echo "🐧 Job running on ${{ runner.os }} server"
       - run: echo "🐙 Using ${{ github.ref }} branch from ${{ github.repository }} repository"
 
-      - name: "Checkout code"
-        uses: actions/checkout@v3
-      - run: echo "🐙 ${{ github.repository }} repository was cloned to the runner."
-
+      - name: Checkout Code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          sparse-checkout: |
+            .github
+      - run: echo "🐙 ${{ github.repository }} repository sparse-checkout to the CI runner."
       - name: "Antq Check versions"
         uses: liquidz/antq-action@main
         with:
@@ -44,4 +47,3 @@ jobs:
       # Summary
       - run: echo "🎨 library versions checked with liquidz/antq"
       - run: echo "🍏 Job status is ${{ job.status }}."
-

.gitignore

@@ -1,3 +1,25 @@
-*.log
-.cache
-**/site
+# Exclude all files from root directory
+/*
+
+# ------------------------
+# Common project files
+!CHANGELOG.md
+!README.md
+!LICENSE
+
+# ------------------------
+# Include MkDocs files
+!docs/
+!includes/
+!overrides/
+!mkdocs.yml
+
+# ------------------------
+# Project automation
+!Makefile
+
+# ------------------------
+# Version Control
+!.gitignore
+!.github/
+

CHANGELOG.md

@@ -22,3 +22,5 @@
 
 ### Changed
 - ci: spell lychee & repository trufflehog linters warn only (false positives) 
+- intro: refactor learning path order and enhance content
+- dev: standardise github workflow and mkdocs configuration

Makefile

@@ -16,7 +16,8 @@
 HELP-DESCRIPTION-SPACING := 24
 
 # Tool Commands
-MEGALINTER_RUNNER := npx mega-linter-runner --flavor documentation --env "'MEGALINTER_CONFIG=.github/config/megalinter.yaml'" --remove-container
+MEGALINTER_RUNNER := npx mega-linter-runner --flavor documentation --env "'MEGALINTER_CONFIG=.github/config/megalinter.yaml'" --env "'VALIDATE_ALL_CODEBASE=true'"  --remove-container
+MKDOCS_SERVER := mkdocs serve --dev-addr localhost:7777
 
 # Makefile file and directory name wildcard
 EDN-FILES := $(wildcard *.edn)
@@ -41,11 +42,11 @@ lint-clean:  ## Clean MegaLinter report information
 # --- Documentation Generation  ------ #
 docs:  ## Build and run mkdocs in local server
 	$(info --------- Mkdocs Local Server ---------)
-	mkdocs serve --dev-addr localhost:7777
+	$(MKDOCS_SERVER)
 
 docs-changed:  ## Build only changed files and run mkdocs in local server
 	$(info --------- Mkdocs Local Server ---------)
-	mkdocs serve --dirtyreload --dev-addr localhost:7777
+	$(MKDOCS_SERVER) --dirtyreload
 
 docs-build:  ## Build mkdocs
 	$(info --------- Mkdocs Local Server ---------)
@@ -60,4 +61,3 @@ help:  ## Describe available tasks in Makefile
 	sort | \
 	awk -F ':.*?## ' 'NF==2 {printf "\033[36m  %-$(HELP-DESCRIPTION-SPACING)s\033[0m %s\n", $$1, $$2}'
 # ------------------------------------ #
-