mirror of
https://github.com/alirezarezvani/claude-skills.git
synced 2026-09-06 08:15:58 +00:00
8818bee8be
Adds the third skill to the markdown-html/ domain. The 90%-case converter that Shihipar's essay calls for: any markdown spec / plan / RFC / report / explainer becomes a single-file, lightly-interactive HTML document with the user's onboarded brand applied. Three stdlib tools pipeline together: 1. markdown_parser.py — CommonMark subset → section AST. Stdlib regex + state machine, no `markdown` dependency. Handles headings 1-6 (with slug anchors), paragraphs with inline bold/italic/code/links/images, fenced code with language tag, GFM tables with per-column alignment, GFM callouts (NOTE/TIP/IMPORTANT/WARNING/CAUTION), blockquotes, ordered + unordered lists (single-level), horizontal rules. 2. html_renderer.py — section AST + design-system config → single-file HTML. Inlines the 12 derived CSS custom properties from ~/.config/markdown-html/design-system.json. Applies the user's design_style (editorial/technical/minimal/playful) via body-class CSS overrides — editorial uses 720px max-width and 1.75 line-height, playful rounds callouts with shadows, technical is dense with 0.875rem code. Emits sticky-sidebar/collapsible-top/inline/none TOC per toc.behavior. Google Fonts CDN link + Prism.js theme link per code_theme (light/dark/auto = prefers-color-scheme). 3. interactivity_injector.py — vanilla-JS payload injected before </body>. Search filter on H2 sections (Esc clears, sticky bar), code-copy buttons (navigator.clipboard + execCommand fallback), smooth-scroll on TOC links, scrollspy via IntersectionObserver (sets aria-current="location" on the matching TOC entry; rootMargin tuned to NN/g F-shape reading pattern). Idempotent (marker check). Feature subset selectable via --features search,copycode,smoothscroll,scrollspy. Plus 3 reference docs (each citing 5-7 sources): information_density _patterns.md (Shihipar + Tufte + Wattenberger + Appleton + Ciechanowski + Bret Victor + Nielsen), toc_and_nav_ux.md (NN/g + WCAG 2.2 + ARIA APG + Vitepress/Docusaurus/mdBook convergence + GOV.UK + MDN), single_file _html_discipline.md (Shihipar + Tom MacWright's Big + Google Fonts API + Prism.js + Anil Dash). 1 template asset documenting the canonical output shape. /cs:md-document slash command with the pre-flight gates + pipeline + output digest. Repo-level updates: - markdown-html/.claude-plugin/plugin.json: skills array adds ./skills/md-document; version 2.10.0 → 2.10.1; description updated. - .claude-plugin/marketplace.json: markdown-html-skills entry version 2.10.0 → 2.10.1, description updated; ALSO cleans up stale top-level counters left over from foundation PR #780 — 338 → 341 skills, 16 → 17 domains, 63 → 64 plugins, 2.9.0 → 2.10.1 metadata.version. - Root CLAUDE.md: v2.10.1 release-notes block above v2.10.0. Validation: - check_plugin_json.py → OK - sync-codex-skills.py --dry-run → 1 new symlink, documentation: 3 skills - skill_description_validator.py → PASS (action verb, third person, trigger phrase, length within limit) - skill_review_checklist_runner.py → 5/6 PASS (under-100-lines warns at 105 — same as research-ops orchestrator; advisory not blocking) - All 3 tools pass --help and --sample - Full pipeline on markdown-html/CLAUDE.md (470 lines) produces 22.8 KB single-file HTML with all 7 expected components present (doctype, injected JS, scrollspy, IntersectionObserver, clipboard API, palette tokens, TOC) - Design-style switch round-trip: --set design_style=editorial → output has 720px max-width and 1.75 line-height; --set design_style=playful → output has rounded callouts with shadow. Customization changes behavior, not decoration (design-system rule §3 honored). - Empirical footprint: ~150-line markdown → 11 KB HTML / 15 KB with JS; ~470-line markdown → 17 KB / 23 KB with JS. Coming in v2.10.2: md-review (2-col diff + severity-tagged margin annotations + jump-nav) and md-slides (arrow-key nav + presenter mode + print-to-PDF). Both will reuse md-document's renderer scaffolding and design-system/scripts/config_loader.py. https://claude.ai/code/session_01BK2KoQot1U7J5oSosrCQdc
108 lines
4.2 KiB
HTML
108 lines
4.2 KiB
HTML
<!DOCTYPE html>
|
|
<!--
|
|
md_document_template.html — Reference shape for html_renderer.py output.
|
|
|
|
This file documents the canonical output structure. The renderer generates
|
|
this same shape dynamically from a section AST + design-system config.
|
|
|
|
Token slots ({{TITLE}}, {{PALETTE}}, etc.) are illustrative — the actual
|
|
renderer interpolates Python values directly into the HTML string.
|
|
|
|
See: html_renderer.py for the live implementation.
|
|
-->
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<title>{{TITLE}}</title>
|
|
|
|
<!-- Google Fonts CDN — the user's heading + body Google Fonts -->
|
|
<link rel="preconnect" href="https://fonts.googleapis.com" crossorigin>
|
|
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family={{HEADING_FONT}}:wght@400;600&family={{BODY_FONT}}:wght@400;600&display=swap">
|
|
|
|
<!-- Prism.js CDN — auto-loads per-language plugins on demand -->
|
|
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism.min.css">
|
|
|
|
<style>
|
|
:root {
|
|
/* 12 CSS custom properties derived from the user's brand by
|
|
brand_palette_validator.derive_palette() */
|
|
--md-bg: {{BG}};
|
|
--md-surface: {{SURFACE}};
|
|
--md-border: {{BORDER}};
|
|
--md-text: {{TEXT}};
|
|
--md-text-muted: {{TEXT_MUTED}};
|
|
--md-accent: {{ACCENT}};
|
|
--md-accent-soft: {{ACCENT_SOFT}};
|
|
--md-code-bg: {{CODE_BG}};
|
|
--md-link: {{LINK}};
|
|
--md-link-hover: {{LINK_HOVER}};
|
|
--md-success: {{SUCCESS}};
|
|
--md-warn: {{WARN}};
|
|
--md-scale: {{SCALE}}; /* e.g. 1.25 */
|
|
--md-font-heading: '{{HEADING_FONT}}', system-ui, sans-serif;
|
|
--md-font-body: '{{BODY_FONT}}', system-ui, sans-serif;
|
|
}
|
|
/* ... BASE_CSS ... STYLE_CSS_OVERRIDES[design_style] ... */
|
|
</style>
|
|
</head>
|
|
|
|
<!-- Body class: style-{editorial|technical|minimal|playful} and toc-{behavior} -->
|
|
<body class="style-{{DESIGN_STYLE}} toc-{{TOC_BEHAVIOR}}">
|
|
|
|
<!-- TOC (variants: sidebar / collapsible-top / inline / none) -->
|
|
<nav class="toc" aria-label="Table of contents">
|
|
<ol>
|
|
<li><a href="#first-section">First Section</a></li>
|
|
<!-- ... -->
|
|
</ol>
|
|
</nav>
|
|
|
|
<main>
|
|
<!-- Search bar (sticky; hidden when search feature is not injected) -->
|
|
<div class="md-search">
|
|
<input type="search" id="md-search-input"
|
|
placeholder="Filter sections… (Esc to clear)"
|
|
aria-label="Filter document sections">
|
|
</div>
|
|
|
|
<!-- Rendered blocks from the section AST -->
|
|
<h1>{{TITLE}}</h1>
|
|
|
|
<h2 id="first-section">First Section</h2>
|
|
<p>Paragraph with <strong>bold</strong>, <em>italic</em>, <code>inline code</code>, and <a href="#">link</a>.</p>
|
|
|
|
<aside class="callout callout-note" role="note">
|
|
<div class="callout-label"><span class="callout-icon" aria-hidden="true">i</span>NOTE</div>
|
|
<div class="callout-body">Important contextual information.</div>
|
|
</aside>
|
|
|
|
<pre><button class="code-copy" type="button" aria-label="Copy code">Copy</button><code class="language-python">def hello():
|
|
return "world"</code></pre>
|
|
|
|
<table>
|
|
<thead><tr><th>Header A</th><th>Header B</th></tr></thead>
|
|
<tbody><tr><td>Cell 1</td><td>Cell 2</td></tr></tbody>
|
|
</table>
|
|
|
|
<!-- Footer with company_name + logo (base64-embedded) -->
|
|
<footer class="md-footer">
|
|
<img src="data:image/png;base64,...{{LOGO_BASE64}}" alt="{{COMPANY_NAME}}">
|
|
<span>{{COMPANY_NAME}}</span>
|
|
<span style="margin-left:auto">Generated by markdown-html</span>
|
|
</footer>
|
|
</main>
|
|
|
|
<!-- Prism.js (deferred; doesn't block first paint) -->
|
|
<script defer src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-core.min.js"></script>
|
|
<script defer src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/plugins/autoloader/prism-autoloader.min.js"></script>
|
|
|
|
<!-- Interactivity script injected by interactivity_injector.py
|
|
when features are enabled. Marked with id="md-document-interactivity-v1"
|
|
for idempotency. Contains:
|
|
- search filter on H2 sections
|
|
- code-copy button handlers (navigator.clipboard + execCommand fallback)
|
|
- smooth-scroll for TOC anchors
|
|
- scrollspy via IntersectionObserver (sets aria-current on TOC links) -->
|
|
</body>
|
|
</html>
|