diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
new file mode 100644
index 0000000..0e3467f
--- /dev/null
+++ b/.github/workflows/tests.yml
@@ -0,0 +1,20 @@
+# The gate of the site (docs/ci-cd.md):
+# python / coverage tools/sitecheck.py under coverage.py, 95 percent, the
+# bar for project-authored code. The suite ends by
+# running the checker over this repository, so a broken
+# link, a missing asset, a plain HTTP link or an asset
+# no page references fails the check before the page is
+# served.
+# Required on main. Thresholds are only ever raised.
+name: tests
+on:
+ pull_request:
+ push:
+ branches: [main]
+jobs:
+ python:
+ uses: keel-linux/.github/.github/workflows/test-python.yml@main
+ with:
+ threshold: 95
+ package: tools
+ tests: tests
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..b1e26b2
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,5 @@
+__pycache__/
+.pytest_cache/
+.coverage
+coverage.txt
+*.egg-info/
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..712a086
--- /dev/null
+++ b/README.md
@@ -0,0 +1,27 @@
+# keellinux.org
+
+The project site, served by GitHub Pages from `main`: two static pages, one
+stylesheet and the brand assets. Nothing builds it, so what is in the
+repository is what the browser gets.
+
+| Path | What it is |
+|------|------------|
+| `index.html` | the home page, also served at `www` |
+| `guidelines.html` | how the organization works, and the mark |
+| `style.css` | the whole stylesheet, light and dark |
+| `assets/` | the mark in its variants and the social card |
+| `tools/sitecheck.py` | the checks a build step would have done |
+| `tests/` | one test per rule, ending with the site itself |
+
+## The check
+
+```
+python3 tools/sitecheck.py .
+```
+
+It exits 0 when the site is sound and 1 with one line per finding: an
+internal link that resolves to nothing, a fragment naming an id that is not
+there, a referenced asset that is missing, an asset no page references, an
+external link that is not https, or a page without a language, a title or
+exactly one h1. The gate `python / coverage` runs the same checks on every
+pull request and is required on `main`.
diff --git a/guidelines.html b/guidelines.html
index 9f80b2f..589423b 100644
--- a/guidelines.html
+++ b/guidelines.html
@@ -93,6 +93,16 @@
Upstream
Forks keep TurnKey Linux as an upstream remote.
Changes are offered back upstream where they apply.
+
+
The mark
+
The mark is a keel seen from astern, with the waterline across it and a drop below. It is drawn as a vector and every other size is an export of it; a change to the mark is a re-export, never an edit of an export.
Keep the clear space around it equal to the height of the drop, do not recolour it, and do not set it on a background that leaves the waterline invisible.
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000..0372f76
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,12 @@
+# The site has no build step: the files in the repository are the files the
+# browser gets. tools/sitecheck.py is the check that a build step would have
+# done, and this file is only here to measure it.
+
+[tool.coverage.run]
+branch = true
+source = ["tools"]
+
+[tool.coverage.report]
+show_missing = true
+# The bar for project-authored code (decision 0003). Only ever raised.
+fail_under = 95
diff --git a/tests/test_sitecheck.py b/tests/test_sitecheck.py
new file mode 100644
index 0000000..d0346ca
--- /dev/null
+++ b/tests/test_sitecheck.py
@@ -0,0 +1,272 @@
+# Copyright (c) 2026 KeelLinux maintainers
+"""Every rule the site checker enforces, and the site itself
+
+The checker is a pure function of a mapping of path to text, so each rule is
+stated here as the smallest page that breaks it. The last test runs the
+checker over the repository it lives in, which is what the gate does: the
+rules are only worth having if the site actually satisfies them.
+"""
+
+import os
+import sys
+import unittest
+from os.path import abspath, dirname, join
+
+ROOT = dirname(dirname(abspath(__file__)))
+sys.path.insert(0, join(ROOT, "tools"))
+
+import sitecheck # noqa: E402
+
+HEAD = 'Keel'
+BODY = "
Keel
"
+
+
+def page(body: str = "", head: str = HEAD, heading: str = BODY) -> str:
+ return f"{head}{heading}{body}"
+
+
+class TestShape(unittest.TestCase):
+ def test_a_well_formed_page_has_no_findings(self):
+ self.assertEqual(sitecheck.check({"index.html": page()}), [])
+
+ def test_a_page_without_a_language_is_reported(self):
+ text = page(head="K")
+ self.assertIn(
+ "index.html: the html element has no lang",
+ sitecheck.check({"index.html": text}),
+ )
+
+ def test_a_page_without_a_title_is_reported(self):
+ text = page(head='')
+ self.assertIn("index.html: no title", sitecheck.check({"index.html": text}))
+
+ def test_an_empty_title_counts_as_none(self):
+ text = page(head='')
+ self.assertIn("index.html: no title", sitecheck.check({"index.html": text}))
+
+ def test_a_page_without_an_h1_is_reported(self):
+ findings = sitecheck.check({"index.html": page(heading="
")
+ self.assertIn(
+ "index.html: 2 h1 elements, expected 1",
+ sitecheck.check({"index.html": text}),
+ )
+
+
+class TestInternalLinks(unittest.TestCase):
+ def test_a_link_to_a_missing_page_is_reported(self):
+ findings = sitecheck.check({"index.html": page('x')})
+ self.assertEqual(
+ findings, ["index.html: gone.html does not resolve to a file"]
+ )
+
+ def test_a_link_to_a_page_that_is_there_passes(self):
+ pages = {"index.html": page('x'), "two.html": page()}
+ self.assertEqual(sitecheck.check(pages), [])
+
+ def test_a_link_out_of_the_site_root_is_reported(self):
+ findings = sitecheck.check(
+ {"index.html": page('x')}
+ )
+ self.assertEqual(
+ findings, ["index.html: ../secret.html does not resolve to a file"]
+ )
+
+ def test_an_absolute_path_is_read_from_the_site_root(self):
+ pages = {"index.html": page('x'), "two.html": page()}
+ self.assertEqual(sitecheck.check(pages), [])
+
+ def test_a_link_from_a_page_in_a_directory_resolves_beside_it(self):
+ pages = {
+ "docs/one.html": page('x'),
+ "docs/two.html": page(),
+ }
+ self.assertEqual(sitecheck.check(pages), [])
+
+
+class TestFragments(unittest.TestCase):
+ def test_a_fragment_on_the_same_page_must_exist(self):
+ text = page('x')
+ self.assertEqual(
+ sitecheck.check({"index.html": text}),
+ ["index.html: #nowhere names an id that is not there"],
+ )
+
+ def test_a_fragment_that_exists_passes(self):
+ text = page('x')
+ self.assertEqual(sitecheck.check({"index.html": text}), [])
+
+ def test_a_fragment_of_another_page_must_exist_there(self):
+ pages = {
+ "index.html": page('x'),
+ "two.html": page(''),
+ }
+ self.assertEqual(
+ sitecheck.check(pages),
+ ["index.html: two.html#gone names an id that is not there"],
+ )
+
+ def test_a_fragment_of_another_page_that_exists_passes(self):
+ pages = {
+ "index.html": page('x'),
+ "two.html": page(''),
+ }
+ self.assertEqual(sitecheck.check(pages), [])
+
+ def test_a_fragment_of_an_asset_is_reported(self):
+ text = page('x')
+ findings = sitecheck.check({"index.html": text}, {"assets/a.svg"})
+ self.assertEqual(
+ findings,
+ [
+ "index.html: assets/a.svg#part names a fragment of a file"
+ " that is not a page"
+ ],
+ )
+
+ def test_an_empty_id_attribute_is_not_a_target(self):
+ text = page('x')
+ self.assertEqual(len(sitecheck.check({"index.html": text})), 1)
+
+
+class TestAssets(unittest.TestCase):
+ def test_a_referenced_asset_that_is_missing_is_reported(self):
+ text = page('')
+ self.assertEqual(
+ sitecheck.check({"index.html": text}, set()),
+ ["index.html: assets/gone.png does not resolve to a file"],
+ )
+
+ def test_a_referenced_asset_that_is_there_passes(self):
+ text = page('')
+ self.assertEqual(sitecheck.check({"index.html": text}, {"assets/here.png"}), [])
+
+ def test_an_asset_no_page_references_is_reported(self):
+ findings = sitecheck.check({"index.html": page()}, {"assets/orphan.png"})
+ self.assertEqual(findings, ["assets/orphan.png: no page references it"])
+
+ def test_assets_are_not_checked_when_none_are_given(self):
+ text = page('')
+ self.assertEqual(sitecheck.check({"index.html": text}), [])
+
+ def test_the_social_card_of_a_meta_tag_counts_as_a_reference(self):
+ text = page(
+ ''
+ )
+ self.assertEqual(sitecheck.check({"index.html": text}, {"assets/card.png"}), [])
+
+ def test_a_twitter_image_counts_as_a_reference(self):
+ text = page('')
+ self.assertEqual(sitecheck.check({"index.html": text}, {"assets/card.png"}), [])
+
+ def test_a_meta_tag_that_is_not_a_reference_is_ignored(self):
+ text = page('')
+ self.assertEqual(sitecheck.check({"index.html": text}), [])
+
+ def test_a_poster_and_a_stylesheet_count_as_references(self):
+ text = page(
+ ''
+ ''
+ )
+ self.assertEqual(
+ sitecheck.check({"index.html": text}, {"style.css", "assets/still.png"}),
+ [],
+ )
+
+
+class TestExternalLinks(unittest.TestCase):
+ def test_an_https_link_passes(self):
+ text = page('x')
+ self.assertEqual(sitecheck.check({"index.html": text}), [])
+
+ def test_a_plain_http_link_is_reported(self):
+ text = page('x')
+ self.assertEqual(
+ sitecheck.check({"index.html": text}),
+ ["index.html: http://example.org/x is not https"],
+ )
+
+ def test_a_protocol_relative_link_is_reported(self):
+ text = page('x')
+ self.assertEqual(
+ sitecheck.check({"index.html": text}),
+ ["index.html: //example.org/x is not https"],
+ )
+
+ def test_a_mailto_link_passes(self):
+ text = page('x')
+ self.assertEqual(sitecheck.check({"index.html": text}), [])
+
+ def test_a_data_uri_is_not_a_reference(self):
+ text = page('')
+ self.assertEqual(sitecheck.check({"index.html": text}, set()), [])
+
+
+class TestReadSite(unittest.TestCase):
+ def test_it_reads_pages_and_assets_and_skips_the_rest(self):
+ pages, assets = sitecheck.read_site(ROOT)
+ self.assertIn("index.html", pages)
+ self.assertIn("assets/keel-mark.svg", assets)
+ self.assertNotIn("tools/sitecheck.py", assets)
+ self.assertFalse([path for path in assets if path.startswith(".git")])
+
+ def test_packaging_metadata_is_not_part_of_the_site(self):
+ import tempfile
+
+ with tempfile.TemporaryDirectory() as tmp:
+ for directory in ("site.egg-info", "tools", "tests", "build"):
+ os.makedirs(join(tmp, directory))
+ with open(join(tmp, directory, "leftover.txt"), "w") as fob:
+ fob.write("x")
+ with open(join(tmp, "index.html"), "w") as fob:
+ fob.write(page())
+ pages, assets = sitecheck.read_site(tmp)
+
+ self.assertEqual(sorted(pages), ["index.html"])
+ self.assertEqual(assets, set())
+
+ def test_a_dotted_directory_is_skipped(self):
+ pages, assets = sitecheck.read_site(ROOT)
+ self.assertFalse([path for path in pages if "/." in path])
+
+
+class TestCommandLine(unittest.TestCase):
+ def test_the_site_of_this_repository_has_no_findings(self):
+ self.assertEqual(sitecheck.main(["sitecheck", ROOT]), 0)
+
+ def test_a_tree_with_no_page_is_a_usage_failure(self):
+ self.assertEqual(sitecheck.main(["sitecheck", join(ROOT, "assets")]), 2)
+
+ def test_it_exits_1_on_a_finding(self):
+ import tempfile
+
+ with tempfile.TemporaryDirectory() as tmp:
+ with open(join(tmp, "index.html"), "w") as fob:
+ fob.write(page('x'))
+ self.assertEqual(sitecheck.main(["sitecheck", tmp]), 1)
+
+ def test_the_script_runs_as_a_program(self):
+ import subprocess
+
+ out = subprocess.run(
+ [sys.executable, join(ROOT, "tools", "sitecheck.py"), ROOT],
+ capture_output=True,
+ text=True,
+ )
+ self.assertEqual(out.returncode, 0, out.stderr)
+ self.assertIn("findings", out.stderr)
+
+ def test_the_default_root_is_the_working_directory(self):
+ here = os.getcwd()
+ os.chdir(ROOT)
+ try:
+ self.assertEqual(sitecheck.main(["sitecheck"]), 0)
+ finally:
+ os.chdir(here)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tools/sitecheck.py b/tools/sitecheck.py
new file mode 100644
index 0000000..900a9a5
--- /dev/null
+++ b/tools/sitecheck.py
@@ -0,0 +1,279 @@
+# Copyright (c) 2026 KeelLinux maintainers
+"""What a static site must satisfy before it is served
+
+The site is the public face of the project and nothing builds it: the files
+in the repository are the files the browser gets. So the checks that a build
+step would have done are here instead, and the gate runs them over the
+repository's own pages.
+
+What is checked, and why each one is worth a failed build:
+
+ - every internal link resolves to a file in the repository, so a page
+ never answers 404 from its own navigation;
+ - every fragment resolves to an id on the page it names, including the
+ fragments of another page, which is what silently rots when a heading
+ is renamed;
+ - every asset a page references exists, and every asset in the tree is
+ referenced by some page, so a removed image is caught and an orphan is
+ not served forever;
+ - an external link is https, because a page served over TLS that links
+ over plain HTTP teaches the reader the wrong habit;
+ - a page carries a title, a language and one h1, which is the least a
+ reader and a search engine can expect.
+
+Pure but for `read_site`: `check` is given a mapping of path to text and
+returns the findings, so every rule is tested without a filesystem.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from html.parser import HTMLParser
+
+# Attributes that carry a reference to something else
+REFERENCE_ATTRS = ("href", "src", "srcset", "poster")
+# Extensions that are pages rather than assets
+PAGE_SUFFIX = ".html"
+# meta tags whose content is a reference, not text: the social card is
+# fetched by a crawler, so a wrong path there breaks a link nobody sees
+# until it is shared
+META_REFERENCE_KEYS = (
+ "og:image",
+ "og:image:url",
+ "og:url",
+ "twitter:image",
+)
+# Directories that are in the repository but are not the site: this checker,
+# its tests, and whatever a tool leaves behind. Packaging metadata is the
+# reason this list exists rather than a suffix rule alone: an editable install
+# writes *.egg-info/*.txt into the tree, and a .txt is something a site can
+# serve, so the tree has to say which directories are the site at all.
+EXCLUDE_DIRS = ("tools", "tests", "node_modules", "build", "dist")
+EXCLUDE_DIR_SUFFIXES = (".egg-info", ".dist-info")
+# What the site serves. A file of any other kind in the tree is repository
+# furniture (this checker, its tests, the packaging) and is not an asset.
+ASSET_SUFFIXES = (
+ ".css", ".js", ".png", ".svg", ".jpg", ".jpeg", ".webp", ".avif",
+ ".ico", ".gif", ".woff", ".woff2", ".txt", ".json", ".xml", ".pdf",
+ ".webmanifest",
+)
+
+
+class Page(HTMLParser):
+ """The parts of one page the checks look at"""
+
+ def __init__(self) -> None:
+ super().__init__(convert_charrefs=True)
+ self.references: list[str] = []
+ self.ids: set[str] = set()
+ self.titles: list[str] = []
+ self.headings: list[str] = []
+ self.language = ""
+ self._in_title = False
+ self._in_h1 = False
+
+ def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+ values = {name: (value or "") for name, value in attrs}
+ if tag == "html":
+ self.language = values.get("lang", "")
+ if tag == "title":
+ self._in_title = True
+ self.titles.append("")
+ if tag == "h1":
+ self._in_h1 = True
+ self.headings.append("")
+ if "id" in values and values["id"]:
+ self.ids.add(values["id"])
+ if tag == "meta":
+ key = values.get("property") or values.get("name") or ""
+ content = values.get("content", "").strip()
+ if key.lower() in META_REFERENCE_KEYS and content:
+ self.references.append(content)
+ for attr in REFERENCE_ATTRS:
+ value = values.get(attr, "").strip()
+ if value:
+ self.references.append(value)
+
+ def handle_endtag(self, tag: str) -> None:
+ if tag == "title":
+ self._in_title = False
+ if tag == "h1":
+ self._in_h1 = False
+
+ def handle_data(self, data: str) -> None:
+ if self._in_title and self.titles:
+ self.titles[-1] += data
+ if self._in_h1 and self.headings:
+ self.headings[-1] += data
+
+
+def parse(text: str) -> Page:
+ page = Page()
+ page.feed(text)
+ page.close()
+ return page
+
+
+def is_external(reference: str) -> bool:
+ return "//" in reference.split("?")[0] or reference.startswith("mailto:")
+
+
+def split_fragment(reference: str) -> tuple[str, str]:
+ """A reference as (path, fragment); either part may be empty"""
+ path, _, fragment = reference.partition("#")
+ return path, fragment
+
+
+def check(pages: dict[str, str], assets: set[str] | None = None) -> list[str]:
+ """Findings for a site given as {path: text}, one line each
+
+ `assets` is every non page file in the tree, used to find the ones no
+ page references. Leave it out to skip that rule.
+ """
+ findings: list[str] = []
+ parsed = {path: parse(text) for path, text in sorted(pages.items())}
+ referenced: set[str] = set()
+
+ for path, page in parsed.items():
+ findings.extend(_check_shape(path, page))
+ for reference in page.references:
+ if reference.startswith("data:"):
+ continue
+ if is_external(reference):
+ findings.extend(_check_external(path, reference))
+ continue
+ target, fragment = split_fragment(reference)
+ if target:
+ referenced.add(_resolve(path, target))
+ findings.extend(
+ _check_internal(
+ path, reference, target, fragment, parsed, assets
+ )
+ )
+
+ if assets is not None:
+ for asset in sorted(assets - referenced):
+ findings.append(f"{asset}: no page references it")
+ return findings
+
+
+def _check_shape(path: str, page: Page) -> list[str]:
+ findings = []
+ if not page.language.strip():
+ findings.append(f"{path}: the html element has no lang")
+ titles = [title.strip() for title in page.titles if title.strip()]
+ if not titles:
+ findings.append(f"{path}: no title")
+ headings = [text.strip() for text in page.headings if text.strip()]
+ if len(headings) != 1:
+ findings.append(f"{path}: {len(headings)} h1 elements, expected 1")
+ return findings
+
+
+def _check_external(path: str, reference: str) -> list[str]:
+ if reference.startswith(("https://", "mailto:")):
+ return []
+ return [f"{path}: {reference} is not https"]
+
+
+def _resolve(path: str, target: str) -> str:
+ """A reference on `path` as a site path, without normalising away ..
+
+ A target that climbs above the site root is returned as it was, so the
+ internal check reports it as missing rather than reaching outside.
+ """
+ if target.startswith("/"):
+ return target.lstrip("/")
+ base = os.path.dirname(path)
+ joined = os.path.normpath(os.path.join(base, target)) if base else target
+ return os.path.normpath(joined)
+
+
+def _check_internal(
+ path: str,
+ reference: str,
+ target: str,
+ fragment: str,
+ parsed: dict[str, Page],
+ assets: set[str] | None,
+) -> list[str]:
+ """Findings for one internal reference made on `path`
+
+ A reference to a page is resolved against the pages, which are all
+ known. A reference to an asset is resolved against `assets` when the
+ caller gave them, and left alone when it did not, so a caller that only
+ has the pages is not told that every image is missing.
+ """
+ findings = []
+ resolved = _resolve(path, target) if target else path
+ if target and not _resolves(resolved, parsed, assets):
+ return [f"{path}: {reference} does not resolve to a file"]
+ if not fragment:
+ return findings
+ if resolved not in parsed:
+ return [
+ f"{path}: {reference} names a fragment of a file"
+ " that is not a page"
+ ]
+ if fragment not in parsed[resolved].ids:
+ findings.append(f"{path}: {reference} names an id that is not there")
+ return findings
+
+
+def _resolves(
+ resolved: str, parsed: dict[str, Page], assets: set[str] | None
+) -> bool:
+ if resolved.endswith(PAGE_SUFFIX):
+ return resolved in parsed
+ if assets is None:
+ return True
+ return resolved in assets
+
+
+def read_site(root: str) -> tuple[dict[str, str], set[str]]:
+ """The pages and the assets of the tree at `root`"""
+ pages: dict[str, str] = {}
+ assets: set[str] = set()
+ for base, dirs, names in os.walk(root):
+ dirs[:] = [name for name in dirs if not _is_excluded_dir(name)]
+ for name in names:
+ if name.startswith("."):
+ continue
+ full = os.path.join(base, name)
+ path = os.path.relpath(full, root)
+ if name.endswith(PAGE_SUFFIX):
+ with open(full, encoding="utf-8") as fob:
+ pages[path] = fob.read()
+ elif name.lower().endswith(ASSET_SUFFIXES):
+ assets.add(path)
+ return pages, assets
+
+
+def _is_excluded_dir(name: str) -> bool:
+ """Whether a directory is repository furniture rather than the site"""
+ return (
+ name.startswith(".")
+ or name in EXCLUDE_DIRS
+ or name.endswith(EXCLUDE_DIR_SUFFIXES)
+ )
+
+
+def main(argv: list[str]) -> int:
+ root = argv[1] if len(argv) > 1 else "."
+ pages, assets = read_site(root)
+ if not pages:
+ print(f"{root}: no pages found", file=sys.stderr)
+ return 2
+ findings = check(pages, assets)
+ for finding in findings:
+ print(finding)
+ print(
+ f"{len(pages)} pages, {len(assets)} assets, {len(findings)} findings",
+ file=sys.stderr,
+ )
+ return 1 if findings else 0
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv))