Add meta/ directory with JSON metadata for each tool

- Created docs_to_json.py script to convert *.docs.md files to JSON
- Each tool now has a meta/<slug>.json file with description and commit hash
- Updated build_colophon.py, gather_links.py, build_by_month.py to read from meta/ JSON files
- Updated write_docs.py to also generate meta/ JSON files when creating docs

haiku.json intentionally omitted to test rebuild capability

Author: claude

build_by_month.py

@@ -31,44 +31,19 @@ def _get_first_n_words(text: str, n: int = 15) -> str:
     return " ".join(words[:n]) + "..."
 
 
-def _extract_summary(docs_path: Path, word_limit: int = 30) -> str:
-    """Extract the first paragraph of the docs file, limited to word_limit words."""
-    if not docs_path.exists():
+def _extract_summary(meta_path: Path, word_limit: int = 30) -> str:
+    """Extract the description from the meta JSON file, limited to word_limit words."""
+    if not meta_path.exists():
         return ""
 
     try:
-        content = docs_path.read_text("utf-8").strip()
-    except OSError:
+        import json
+        data = json.load(meta_path.open("r", encoding="utf-8"))
+        description = data.get("description", "")
+        return _get_first_n_words(description, word_limit)
+    except (OSError, json.JSONDecodeError):
         return ""
 
-    # Remove HTML comments
-    if "<!--" in content:
-        content = content.split("<!--", 1)[0]
-
-    # Strip any markdown heading lines first
-    content_lines = [
-        line for line in content.splitlines()
-        if not line.lstrip().startswith("# ")
-        and not line.lstrip().startswith("## ")
-        and not line.lstrip().startswith("### ")
-        and not line.lstrip().startswith("#### ")
-        and not line.lstrip().startswith("##### ")
-        and not line.lstrip().startswith("###### ")
-    ]
-
-    # Get first paragraph
-    lines = []
-    for line in content_lines:
-        stripped = line.strip()
-        if not stripped:
-            if lines:
-                break
-            continue
-        lines.append(stripped)
-
-    paragraph = " ".join(lines)
-    return _get_first_n_words(paragraph, word_limit)
-
 
 def _load_gathered_links() -> dict:
     if not GATHERED_LINKS_PATH.exists():
@@ -105,8 +80,8 @@ def build_by_month() -> None:
 
         # Get the docs summary
         slug = page_name.replace(".html", "")
-        docs_path = Path(f"{slug}.docs.md")
-        summary = _extract_summary(docs_path)
+        meta_path = Path("meta") / f"{slug}.json"
+        summary = _extract_summary(meta_path)
 
         tools_by_month[month_key].append({
             "filename": page_name,

build_colophon.py

@@ -260,29 +260,21 @@ def get_most_recent_date(page_data):
             </h2>
         </div>
 """
-        # Check for corresponding docs.md file
-        docs_file = page_name.replace(".html", ".docs.md")
-        if Path(docs_file).exists():
+        # Check for corresponding meta JSON file
+        slug = page_name.replace(".html", "")
+        meta_file = Path("meta") / f"{slug}.json"
+        if meta_file.exists():
             try:
-                with open(docs_file, "r") as f:
-                    docs_content = f.read()
-                    # Strip any markdown heading lines first
-                    docs_lines = [
-                        line for line in docs_content.splitlines()
-                        if not line.lstrip().startswith("# ")
-                        and not line.lstrip().startswith("## ")
-                        and not line.lstrip().startswith("### ")
-                        and not line.lstrip().startswith("#### ")
-                        and not line.lstrip().startswith("##### ")
-                        and not line.lstrip().startswith("###### ")
-                    ]
-                    docs_content = "\n".join(docs_lines)
-                    # Render markdown to HTML
-                    docs_html = markdown.markdown(docs_content)
-                    # Add docs above commits
-                    html_content += '<div class="docs">' + docs_html + "</div>"
+                with open(meta_file, "r") as f:
+                    meta_data = json.load(f)
+                    description = meta_data.get("description", "")
+                    if description:
+                        # Render markdown to HTML
+                        docs_html = markdown.markdown(description)
+                        # Add docs above commits
+                        html_content += '<div class="docs">' + docs_html + "</div>"
             except Exception as e:
-                print(f"Error reading {docs_file}: {e}")
+                print(f"Error reading {meta_file}: {e}")
 
         # Wrap commits in details/summary tags
         html_content += f"""

docs_to_json.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""Convert *.docs.md files to JSON files in meta/ directory."""
+
+import json
+import re
+from pathlib import Path
+
+
+def extract_description(content: str) -> str:
+    """Extract the first paragraph (description) from docs.md content."""
+    # Remove HTML comments
+    if "<!--" in content:
+        content = content.split("<!--", 1)[0]
+
+    # Strip any markdown heading lines
+    content_lines = [
+        line for line in content.splitlines()
+        if not line.lstrip().startswith("# ")
+        and not line.lstrip().startswith("## ")
+        and not line.lstrip().startswith("### ")
+        and not line.lstrip().startswith("#### ")
+        and not line.lstrip().startswith("##### ")
+        and not line.lstrip().startswith("###### ")
+    ]
+
+    # Get first paragraph
+    lines = []
+    for line in content_lines:
+        stripped = line.strip()
+        if not stripped:
+            if lines:
+                break
+            continue
+        lines.append(stripped)
+
+    return " ".join(lines)
+
+
+def extract_commit(content: str) -> str:
+    """Extract the commit hash from the HTML comment."""
+    match = re.search(r"<!-- Generated from commit: ([a-f0-9]+) -->", content)
+    if match:
+        return match.group(1)
+    return ""
+
+
+def main():
+    # Create meta directory if it doesn't exist
+    meta_dir = Path("meta")
+    meta_dir.mkdir(exist_ok=True)
+
+    # Find all docs.md files in the current directory
+    docs_files = sorted(Path(".").glob("*.docs.md"))
+
+    converted_count = 0
+
+    for docs_file in docs_files:
+        # Read the content
+        content = docs_file.read_text("utf-8")
+
+        # Extract description and commit
+        description = extract_description(content)
+        commit = extract_commit(content)
+
+        # Determine output filename (e.g., ai-adoption.docs.md -> meta/ai-adoption.json)
+        slug = docs_file.stem.replace(".docs", "")
+        output_file = meta_dir / f"{slug}.json"
+
+        # Create JSON object
+        data = {
+            "description": description,
+            "commit": commit,
+        }
+
+        # Write to file with pretty printing
+        output_file.write_text(json.dumps(data, indent=2) + "\n", "utf-8")
+        converted_count += 1
+        print(f"Converted {docs_file} -> {output_file}")
+
+    print(f"\nConverted {converted_count} files to JSON in meta/")
+
+
+if __name__ == "__main__":
+    main()

gather_links.py

@@ -67,30 +67,17 @@ def extract_urls(text):
     return re.findall(url_pattern, text)
 
 
-def extract_description(docs_path: Path) -> str:
-    """Extract the first paragraph of the generated docs markdown file."""
-    if not docs_path.exists():
+def extract_description(meta_path: Path) -> str:
+    """Extract the description from the meta JSON file."""
+    if not meta_path.exists():
         return ""
 
     try:
-        content = docs_path.read_text("utf-8").strip()
-    except OSError:
+        data = json.load(meta_path.open("r", encoding="utf-8"))
+        return data.get("description", "")
+    except (OSError, json.JSONDecodeError):
         return ""
 
-    if "<!--" in content:
-        content = content.split("<!--", 1)[0]
-
-    lines = []
-    for line in content.splitlines():
-        stripped = line.strip()
-        if not stripped:
-            if lines:
-                break
-            continue
-        lines.append(stripped)
-
-    return " ".join(lines)
-
 
 def extract_title(html_path: Path) -> str:
     """Extract the <title> from an HTML file."""
@@ -147,8 +134,8 @@ def main():
         if not commits:
             continue
 
-        docs_path = html_file.with_suffix(".docs.md")
-        description = extract_description(docs_path)
+        meta_path = Path("meta") / f"{html_file.stem}.json"
+        description = extract_description(meta_path)
 
         created_date = commits[-1]["date"] if commits else None
         updated_date = commits[0]["date"] if commits else None

meta/ai-adoption.json

@@ -0,0 +1,4 @@
+{
+  "description": "View AI adoption trends across different firm sizes by analyzing survey data on artificial intelligence usage in the workplace. This page runs a Python analysis using Pyodide to fetch employment survey data, calculate six-survey rolling averages, and generate an interactive visualization showing adoption rates by company size from November 2023 through August 2025. Download the resulting chart as PNG or SVG for further use or presentation.",
+  "commit": "ecc4d0ed023901a9d26d99aea2b3bd34258e5241"
+}

meta/alt-text-extractor.json

@@ -0,0 +1,4 @@
+{
+  "description": "Extract alternative text and image URLs from rich text content pasted into this tool. Simply paste content from web pages, and the tool automatically detects embedded images, displays them alongside their alt text descriptions, and provides copy buttons for convenient access to both the alt text and image URLs. This utility is particularly useful for accessibility audits, content analysis, and archiving image metadata.",
+  "commit": "e468d4b9566e27850d234e609f9d99cafbd9c78b"
+}

meta/analytics.json

@@ -0,0 +1,4 @@
+{
+  "description": "Track your browsing activity and viewing patterns with this personal analytics dashboard that stores all data locally in your browser. The tool displays comprehensive statistics including total visits, unique pages visited, and time-based breakdowns through interactive charts showing visits by day or hour. A detailed table view shows your most visited pages and recent activity, with options to export your analytics data as JSON or clear all stored information at any time.",
+  "commit": "41099d1fcf99cf91a2d2be88e96597abc776ef21"
+}

meta/animated-rainbow-border.json

@@ -0,0 +1,4 @@
+{
+  "description": "Display an animated rainbow gradient border effect around a centered box with interactive controls. The page features a dark theme with a glowing, color-shifting border that can be toggled on and off using the provided button. The animation combines gradient shifting and pulsing effects to create a dynamic, eye-catching visual presentation.",
+  "commit": "99021c5a96c4d188e92a9341621a105e0d3600ca"
+}

meta/annotated-presentations.json

@@ -0,0 +1,4 @@
+{
+  "description": "Create annotated presentation slides with alt text and markdown notes. Upload your slide images, add accessibility descriptions and annotations with markdown support, then generate HTML output using customizable templates. The tool automatically saves your work and includes optional OCR functionality to extract text from slides.",
+  "commit": "6c429482d2b7eb09c5e2554fe33c6157137f7bcc"
+}

meta/apsw-query.json

@@ -0,0 +1,4 @@
+{
+  "description": "Analyze and explain SQLite queries using APSW by entering SQL code and executing it in an in-browser Python environment. The tool provides detailed query analysis including execution plans, expanded SQL, and query information to help understand how SQLite processes your queries. Optional setup SQL can be run before the main query to create tables or initialize data, and parameterized queries are supported through labeled input fields.",
+  "commit": "0af31729167e3de7f6ac73afd5e5bc03ba3b68fb"
+}