chore(deps): bump actions/checkout from 4 to 6

.github/workflows/docs.yml

@@ -7,41 +7,37 @@ on:
   pull_request:
   workflow_dispatch:
 
-env:
-  HOMEBREW_NO_INSTALL_CLEANUP: 1
-
 jobs:
   build:
-    runs-on: macos-latest
+    runs-on: ubuntu-latest
     steps:
-#      -
-#        name: Install some tools
-#        run: sudo apt-get install -y libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev
-#      -
-#        name: Set up Homebrew
-#        id: set-up-homebrew
-#        uses: Homebrew/actions/setup-homebrew@master
-      -
-        name: Install Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.13'
       -
         name: Set up Git repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
       -
-        name: Cache asdf installations
-        uses: actions/cache@v4
+        name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libcairo2-dev \
+            libpango1.0-dev \
+            libfreetype6-dev \
+            libffi-dev \
+            libjpeg-dev \
+            libpng-dev \
+            zlib1g-dev \
+            graphviz \
+            libgraphviz-dev
+      -
+        name: Install Python
+        uses: actions/setup-python@v5
         with:
-          path: |
-            ~/.asdf/installs
-            ~/.asdf/plugins
-            ~/.asdf/shims
-          key: ${{ runner.os }}-asdf-${{ hashFiles('.tool-versions') }}
-          restore-keys: |
-            ${{ runner.os }}-asdf-
+          python-version: '3.14'
+      -
+        name: Install uv
+        run: pip install uv
       -
         name: Cache uv dependencies
         uses: actions/cache@v4
@@ -52,14 +48,9 @@ jobs:
           key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock', 'pyproject.toml') }}
           restore-keys: |
             ${{ runner.os }}-uv-
-      -
-        name: Install asdf & tools
-        uses: asdf-vm/actions/install@v4
       -
         name: Install all MkDocs dependencies
-        run: |
-          # echo "/home/linuxbrew/.linuxbrew/bin/brew" >> $GITHUB_PATH
-          make --environment-overrides docs-install-github-actions
+        run: make --environment-overrides docs-install-github-actions
       -
         name: Build Site
         # Build runs on all branches and PRs to validate changes

.gitignore

@@ -59,3 +59,4 @@ out/
 *.xdy
 .venv/
 .pdm-python
+Screenshot*

.markdownlint.json

@@ -0,0 +1,11 @@
+{
+  "MD013": {
+    "line_length": 140,
+    "heading_line_length": 140,
+    "code_block_line_length": 140
+  },
+  "MD025": {
+    "front_matter_title": ""
+  }
+}
+

.python-version

@@ -0,0 +1,2 @@
+3.14.2
+

.vscode/settings.json

@@ -1,3 +1,10 @@
 {
-    "makefile.configureOnOpen": false
+  "yaml.schemas": {
+    "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"
+  },
+  "yaml.customTags": [
+    "tag:yaml.org,2002:python/name",
+    "tag:yaml.org,2002:python/object/apply"
+  ],
+  "makefile.configureOnOpen": false
 }

Makefile

@@ -23,15 +23,14 @@ endif
 endif
 
 #
-# Since we do not have asdf for Windows, we need to install these tools
-# on windows in a different way. Here we assume you did that yourself in
-# the local project's virtualenv directory (./.venv).
+# Windows note: install the required build tools separately (outside of this Makefile),
+# then run `make install` to create/use the local project's virtualenv (./.venv).
 #
 VENV_PYTHON := $(VIRTUAL_ENV)/bin/python3
 UV := uv
-PYTHON_VERSION := 3.13
+PYTHON_VERSION := 3.14.2
 
-PIPENV_DEFAULT_PYTHON_VERSION := 3.13
+PIPENV_DEFAULT_PYTHON_VERSION := 3.14.2
 PIPENV_VENV_IN_PROJECT := 1
 
 CURRENT_BRANCH := $(shell git branch --show-current)
@@ -69,6 +68,10 @@ docs-install: docs-install-brew docs-install-brew-packages docs-install-python-p
 docs-install-github-actions: docs-install-brew-packages docs-install-python-packages info
 
 .PHONY: docs-install-brew-packages
+ifeq ($(YOUR_OS), Linux)
+docs-install-brew-packages:
+	@echo "Skip Homebrew packages on Linux (installed via apt-get in CI)"
+else
 docs-install-brew-packages:
 	@echo "Install packages via HomeBrew:"
 	@brew upgrade cairo 2>/dev/null || brew install cairo
@@ -80,6 +83,7 @@ docs-install-brew-packages:
 	@brew upgrade zlib 2>/dev/null || brew install zlib
 	@brew upgrade graphviz 2>/dev/null || brew install graphviz
 	@brew upgrade uv 2>/dev/null || brew install uv
+endif
 
 .PHONY: docs-install-brew
 ifeq ($(YOUR_OS), Linux)
@@ -110,25 +114,8 @@ docs-install-brew-macos:
 	@if ! command -v brew >/dev/null 2>&1 ; then echo "Install HomeBrew" ; exit 1 ; fi
 	@brew --version
 
-.PHONY: docs-install-asdf
-docs-install-asdf: docs-install-brew
-	@echo "Install the asdf package manager:"
-	@if ! command -v asdf >/dev/null 2>&1; then \
-		brew upgrade asdf 2>/dev/null || brew install asdf; \
-	fi
-	@asdf plugin add python 2>/dev/null || true
-
-.PHONY: docs-install-asdf-packages
-docs-install-asdf-packages: docs-install-asdf
-	@echo "Install packages via asdf:"
-	asdf install
-
 .PHONY: docs-install-python-packages
-#ifneq ($(wildcard /home/runner/.*),)
-#docs-install-python-packages: docs-install-asdf
-#else
-docs-install-python-packages: docs-install-asdf-packages docs-install-standard-python-packages
-#endif
+docs-install-python-packages: docs-install-standard-python-packages
 
 .PHONY: docs-install-standard-python-packages
 docs-install-standard-python-packages: docs-ensure-venv
@@ -183,7 +170,7 @@ docs-serve-debug-non-strict: docs-ensure-venv
 
 .PHONY: docs-deploy
 docs-deploy: docs-ensure-venv
-	$(UV) run mkdocs gh-deploy --config-file $(MKDOCS_CONFIG_FILE) --verbose
+	$(UV) run mkdocs gh-deploy --config-file $(MKDOCS_CONFIG_FILE)
 
 .PHONY: docs-sync-from
 docs-sync-from: docs-sync-from-ekg-maturity docs-sync-from-ekg-principles

README.md

@@ -2,9 +2,17 @@
 
 Documenting the Use Case Tree method.
 
+## Python
+
+This repo uses **Python 3.13+** (see `pyproject.toml`) and **uv**.
+
+```bash
+uv sync
+```
+
 This is an initiative of:
 
-- agnos.ai UK Ltd
-- Enterprise Knowledge Graph Foundation
+- [agnos.ai UK Ltd](https://agnos.ai)
+- [Object Management Group](https://omg.org) (OMG) [Enterprise Knowledge Graph Forum](https://ekgf.org) (EKGF)
 
 The content of this repository is published as https://method.ekgf.org

docs-overrides/main.html

@@ -1,5 +1,11 @@
 {% extends "base.html" %}
 
+<!-- SEO Meta Tags -->
+{% block extrahead %}
+{{ super() }}
+{% include "partials/seo.html" %}
+{% endblock %}
+
 <!-- Content -->
 {% block content %}
 {% if page.meta.generated == True %}

docs-overrides/partials/seo.html

@@ -0,0 +1,92 @@
+{# SEO Meta Tags Partial #}
+
+{# Get page-specific description or fall back to site description #}
+{% set page_description = page.meta.description if page.meta and page.meta.description else config.site_description %}
+
+{# Get page title #}
+{% set page_title = page.title if page.title else config.site_name %}
+{% set full_title = page_title + " - " + config.site_name if page_title != config.site_name else config.site_name %}
+
+{# Get page URL #}
+{# Prefer MkDocs' canonical_url when available #}
+{% set page_url = page.canonical_url if page.canonical_url else (config.site_url + page.url if page.url else config.site_url) %}
+
+{# Get page image (use site logo or custom image) #}
+{% set page_image = config.site_url + "/assets/images/favicon.png" %}
+{% if page.meta and page.meta.image %}
+  {% set page_image = config.site_url + page.meta.image if page.meta.image.startswith("/") else page.meta.image %}
+{% endif %}
+
+{# Open Graph / Facebook #}
+<meta property="og:type" content="website">
+<meta property="og:url" content="{{ page_url }}">
+<meta property="og:title" content="{{ full_title }}">
+<meta property="og:description" content="{{ page_description }}">
+<meta property="og:image" content="{{ page_image }}">
+<meta property="og:site_name" content="{{ config.site_name }}">
+{% if config.site_author %}
+<meta property="og:locale" content="en_US">
+{% endif %}
+
+{# Twitter Card #}
+<meta name="twitter:card" content="summary_large_image">
+<meta name="twitter:url" content="{{ page_url }}">
+<meta name="twitter:title" content="{{ full_title }}">
+<meta name="twitter:description" content="{{ page_description }}">
+<meta name="twitter:image" content="{{ page_image }}">
+{% if config.extra.social %}
+  {% for social in config.extra.social %}
+    {% if "twitter" in social.link %}
+      <meta name="twitter:site" content="@{{ social.link.split('/')[-1] }}">
+    {% endif %}
+  {% endfor %}
+{% endif %}
+
+{# Additional SEO meta tags #}
+{% if page.meta and page.meta.keywords %}
+<meta name="keywords" content="{{ page.meta.keywords | join(', ') }}">
+{% endif %}
+
+{# Google Search Console verification #}
+{% if config.extra.google_site_verification %}
+<meta name="google-site-verification" content="{{ config.extra.google_site_verification }}">
+{% endif %}
+
+{# JSON-LD Structured Data #}
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "{% if page.meta and page.meta.schema_type %}{{ page.meta.schema_type }}{% else %}WebPage{% endif %}",
+  "name": "{{ full_title }}",
+  "description": "{{ page_description }}",
+  "url": "{{ page_url }}",
+  "inLanguage": "{{ config.theme.language }}",
+  "isPartOf": {
+    "@type": "WebSite",
+    "name": "{{ config.site_name }}",
+    "url": "{{ config.site_url }}"
+  }{% if config.site_author %},
+  "publisher": {
+    "@type": "Organization",
+    "name": "{{ config.site_author }}",
+    "url": "{{ config.site_url }}"
+  }{% endif %}{% if page.meta and page.meta.authors %},
+  "author": [
+    {% for author in page.meta.authors %}
+    {
+      "@type": "Person",
+      "name": "{{ author }}"
+    }{% if not loop.last %},{% endif %}
+    {% endfor %}
+  ]{% endif %}{% if page.meta and page.meta.date_published %},
+  "datePublished": "{{ page.meta.date_published }}"{% endif %}{% if page.meta and page.meta.date_modified %},
+  "dateModified": "{{ page.meta.date_modified }}"{% elif page.meta and page.meta.git_revision_date_localized %},
+  "dateModified": "{{ page.meta.git_revision_date_localized }}"{% endif %},
+  "mainEntity": {
+    "@type": "Article",
+    "headline": "{{ page_title }}",
+    "description": "{{ page_description }}"
+  }
+}
+</script>
+