Free, open source blog writer for Claude Code. Researches current sources, writes answer-first posts for Google and AI answers, has an independent reviewer score each one out of 100 and ships only after five delivery gates. 32 skills, 30 /blog commands, 5 agents. Active development at AI-Marketing-Hub/claude-blog; public releases ship here.
Python agent-skillsaiai-citationsai-contentai-marketingai-marketing-hubblogblog-writingclaude-codeclaude-code-skillclaude-pluginclaude-skillcontent-creationcontent-optimizationcontent-strategyeeatgeomultilingualopen-sourceseo
#!/usr/bin/env python3
"""blog_hygiene.py: deterministic, judgment-free structural hygiene for blog drafts.
Applies only fixes that never need editorial judgment, so it is safe to run
automatically. It is an OPTIONAL helper, not a delivery-contract gate: it never
blocks delivery and always exits 0 on a successful run.
Fixes:
1. HTML: add loading="lazy" to <img> tags that lack a loading attribute,
except the first image (the hero / above the fold image), any image with
a fetchpriority attribute, and any image whose class contains "hero".
Lazy-loading the largest contentful image slows LCP, so those are left alone.
<img> text inside <pre>, <code> and HTML comments is documentation, not a
real image, and is never touched or reported.
2. HTML: report (never invent) <img> tags missing alt text.
3. Markdown: insert an idempotent Table of Contents before the first body H2
on posts over the word threshold (default 2000) when none is present.
Safety:
- Refuses symlinked inputs and non-regular files; only rewrites the file passed.
- Default is dry-run (report only). Pass --apply to write changes back.
Output: a JSON object on stdout. Exit code 0 on success, 2 on usage/IO error.
Usage:
python3 scripts/blog_hygiene.py --md post.md [--html post.html] [--apply]
python3 scripts/blog_hygiene.py --html post.html --apply
"""
from __future__ import annotations
import argparse
import json
import os
import re
import sys
import unicodedata
from pathlib import Path
TOC_BEGIN = "<!-- blog-hygiene:toc:begin -->"
TOC_END = "<!-- blog-hygiene:toc:end -->"
DEFAULT_TOC_HEADING = "In this article"
def slugify(text: str) -> str:
"""Convert heading text to a GitHub-style anchor slug (ASCII, lowercase)."""
text = unicodedata.normalize("NFKD", text).encode("ascii", "ignore").decode("ascii")
text = text.lower()
text = re.sub(r"[^\w\s-]", "", text)
text = re.sub(r"[\s_]+", "-", text).strip("-")
return text
_PROTECTED_OPENERS = (
("<!--", "-->"),
("<pre", "</pre"),
("<code", "</code"),
)
def _protected_spans(html: str) -> list[tuple[int, int]]:
"""Spans of HTML comments, <pre> and <code> blocks (unclosed ones run to the end)."""
lowered = html.lower()
spans: list[tuple[int, int]] = []
pos = 0
while True:
hits = []
for opener, closer in _PROTECTED_OPENERS:
at = lowered.find(opener, pos)
if at != -1 and (opener == "<!--" or lowered[at + len(opener): at + len(opener) + 1] in (">", " ", "\t", "\n", "\r", "/")):
hits.append((at, opener, closer))
if not hits:
return spans
at, opener, closer = min(hits)
end = lowered.find(closer, at + len(opener))
if end == -1:
spans.append((at, len(html)))
return spans
end = lowered.find(">", end)
end = len(html) if end == -1 else end + 1
spans.append((at, end))
pos = end
def _in_spans(index: int, spans: list[tuple[int, int]]) -> bool:
return any(start <= index < end for start, end in spans)
_HERO_CLASS_RE = re.compile(r"""\bclass\s*=\s*["'][^"']*\bhero\b""", re.IGNORECASE)
def _is_priority_image(tag: str) -> bool:
"""True for an image that must load eagerly: fetchpriority set or class hero."""
return bool(re.search(r"\bfetchpriority\s*=", tag, re.IGNORECASE) or _HERO_CLASS_RE.search(tag))
def fix_html_lazy_loading(html: str) -> tuple[str, int]:
"""Add loading="lazy" to below-the-fold <img> tags lacking a loading attribute. Pure.
The first real image, images with fetchpriority or a hero class, and images
inside <pre>, <code> or comments are never changed.
"""
spans = _protected_spans(html)
count = 0
seen_first = False
out: list[str] = []
last = 0
for m in re.finditer(r"<img\b[^>]*>", html, flags=re.IGNORECASE | re.DOTALL):
if _in_spans(m.start(), spans):
continue
tag = m.group(0)
is_first = not seen_first
seen_first = True
if is_first or _is_priority_image(tag) or re.search(r"\bloading\s*=", tag, re.IGNORECASE):
continue
count += 1
out.append(html[last:m.start()])
# insert right after the "<img" token (first 4 chars of the match)
out.append(tag[:4] + ' loading="lazy"' + tag[4:])
last = m.end()
out.append(html[last:])
return "".join(out), count
def find_missing_alt(html: str) -> list[str]:
"""Return srcs of <img> tags missing an alt attribute (cannot auto-fix)."""
missing: list[str] = []
spans = _protected_spans(html)
for m in re.finditer(r"<img\b([^>]*)>", html, re.IGNORECASE | re.DOTALL):
if _in_spans(m.start(), spans):
continue
attrs = m.group(1)
if not re.search(r"\balt\s*=", attrs, re.IGNORECASE):
src_m = re.search(r'\bsrc\s*=\s*["\']([^"\']+)["\']', attrs, re.IGNORECASE)
missing.append(src_m.group(1) if src_m else "(unknown)")
return missing
def split_frontmatter(text: str) -> tuple[str, str]:
"""Return (frontmatter_including_fences_or_empty, body)."""
if text.startswith("---"):
end = text.find("\n---", 3)
if end != -1:
nl = text.find("\n", end + 1)
if nl != -1:
return text[: nl + 1], text[nl + 1:]
return "", text
def count_words(body: str) -> int:
"""Word count of body with HTML tags and markdown punctuation stripped."""
clean = re.sub(r"<[^>]+>", " ", body)
clean = re.sub(r"[*_`#\[\]()>~]", " ", clean)
return len(clean.split())
def extract_h2s(body: str) -> list[tuple[str, str]]:
"""Return [(heading_text, anchor_slug)] for each ATX H2, skipping code fences."""
out: list[tuple[str, str]] = []
in_fence = False
for line in body.splitlines():
if line.lstrip().startswith("```"):
in_fence = not in_fence
continue
if in_fence:
continue
m = re.match(r"^## +(.+?)\s*#*\s*$", line)
if m:
heading = m.group(1).strip()
slug = slugify(heading)
if slug:
out.append((heading, slug))
return out
def toc_present(text: str) -> bool:
"""True if a TOC (this tool's marker or a common manual one) already exists."""
if TOC_BEGIN in text:
return True
lowered = text.lower()
return any(
marker in lowered
for marker in ("## table of contents", "## contents", "**in this article", "**table of contents")
)
def build_toc(h2s: list[tuple[str, str]], heading: str = DEFAULT_TOC_HEADING) -> str:
"""Build an idempotent, marker-wrapped markdown TOC block."""
lines = [TOC_BEGIN, f"**{heading}:**", ""]
lines += [f"- [{text}](#{slug})" for text, slug in h2s]
lines += ["", TOC_END, ""]
return "\n".join(lines)
def insert_toc(md: str, min_words: int = 2000, heading: str = DEFAULT_TOC_HEADING) -> tuple[str, bool]:
"""Insert a TOC before the first body H2 when long enough and none present."""
front, body = split_frontmatter(md)
if toc_present(body) or count_words(body) < min_words:
return md, False
h2s = extract_h2s(body)
if len(h2s) < 2:
return md, False
first = re.search(r"^## +", body, re.MULTILINE)
if not first:
return md, False
toc = build_toc(h2s, heading) + "\n"
new_body = body[: first.start()] + toc + body[first.start():]
return front + new_body, True
def _read_safely(path: Path) -> str:
if path.is_symlink():
raise OSError(f"refusing to read symlink: {path}")
if not path.is_file():
raise OSError(f"not a regular file: {path}")
fd = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
try:
fh = os.fdopen(fd, "r", encoding="utf-8")
except Exception:
os.close(fd)
raise
with fh:
return fh.read()
def _write_safely(path: Path, data: str) -> None:
if path.is_symlink():
raise OSError(f"refusing to write through symlink: {path}")
path.write_text(data, encoding="utf-8")
def main(argv: list[str] | None = None) -> int:
ap = argparse.ArgumentParser(description="Deterministic blog draft hygiene (optional; never blocks).")
ap.add_argument("--md", type=Path, help="Markdown draft (TOC insertion).")
ap.add_argument("--html", type=Path, help="Rendered HTML (lazy-loading + alt report).")
ap.add_argument("--apply", action="store_true", help="Write changes back (default: dry-run).")
ap.add_argument("--min-words", type=int, default=2000, help="TOC word threshold (default 2000).")
ap.add_argument("--toc-heading", default=DEFAULT_TOC_HEADING, help="TOC heading label.")
args = ap.parse_args(argv)
if not args.md and not args.html:
ap.error("provide at least one of --md or --html")
result: dict[str, object] = {
"lazy_fixed": 0, "alt_missing": [], "toc_inserted": False,
"applied": bool(args.apply), "changed_files": [], "warnings": [],
}
try:
if args.html:
html = _read_safely(args.html)
new_html, n = fix_html_lazy_loading(html)
result["lazy_fixed"] = n
result["alt_missing"] = find_missing_alt(new_html)
if args.apply and new_html != html:
_write_safely(args.html, new_html)
result["changed_files"].append(str(args.html))
if args.md:
md = _read_safely(args.md)
new_md, inserted = insert_toc(md, args.min_words, args.toc_heading)
result["toc_inserted"] = inserted
if args.apply and inserted:
_write_safely(args.md, new_md)
result["changed_files"].append(str(args.md))
except (OSError, UnicodeDecodeError) as exc:
print(json.dumps({"error": f"cannot process input: {exc}"}), file=sys.stdout)
return 2
if result["alt_missing"]:
result["warnings"].append(f"{len(result['alt_missing'])} <img> tag(s) missing alt text; add manually.")
print(json.dumps(result, indent=2))
return 0
if __name__ == "__main__":
sys.exit(main())