How to Transform Various Content Types into Polished HTML Articles with Garden Skills

The beautiful-article skill in the garden-skills repository provides a complete editorial pipeline that converts URLs, PDFs, DOCX files, Markdown, and images into self-contained, themed HTML articles using the reacticle component library.

The garden-skills repository by ConardLi offers a sophisticated solution for content transformation. This skill orchestrates a rigorous, checkpoint-driven workflow to transform various content types into polished HTML articles, ensuring visual consistency and high information retention throughout the conversion process.

The Editorial Pipeline Architecture

The beautiful-article skill operates as a harness that orchestrates content through eight distinct phases, supported by three hard checkpoints that enforce quality gates. The architecture separates concerns between the workflow engine (living in skills/beautiful-article/) and the presentation layer handled by the reacticle npm package.

Phase 0–2: Intake and Normalization

The workflow begins with Phase 0 (Intake), where the agent receives a source reference—whether a URL, file path, or raw text block. During Phase 1, the scripts/source-to-markdown.py script extracts and normalizes content into source.md (or source.<lang>.md for translations). This script leverages the MarkItDown Python library for high-fidelity PDF and DOCX extraction, falling back to lightweight handlers for plain Markdown or HTML.

Phase 2 (Editorial Planning) produces a plan.md file that specifies the article type, selected theme, content width, image policy, and cover options. Article types dictate default information retention ratios—for example, longform articles retain approximately 100% of source detail, while briefing formats retain roughly 50%.

Checkpoint-Driven Quality Control

The pipeline enforces three hard checkpoints where decisions are confirmed independently:

• Checkpoint 1: Validates the five decisions in plan.md (theme, width, image policy, cover, and retention ratio) before any drafting begins.
• Checkpoint 2: Reviews the First Spread (Phase 4)—a minimal draft containing the cover, hero section, and opening visual—using optional A/B dev mode for comparison.
• Checkpoint 3: Final validation before delivery, ensuring all editorial, visual, and technical standards are met.

Phase 5–8: Drafting and Delivery

Phase 5 (Full Article Build) compiles each section into individual tsx files under article/sections/, which the root Article.tsx component assembles into a cohesive document. During Phase 6 (Final Review), sub-agents verify the complete draft against the theme contract. Phase 7 (Repair) applies minimal-slice fixes only—wholesale rewrites are prohibited to preserve editorial integrity. Finally, Phase 8 produces the deliverable via npm run build, generating article/article.html as a single, self-contained file.

Bootstrapping Your First Project

All phases are orchestrated by the scaffold script, which initializes a Vite + React + TypeScript workspace pre-configured with the reacticle design system.

To create a new article project with the Tufte theme:

bash skills/beautiful-article/scripts/scaffold.sh ./my-article --theme=tufte

This command copies the template from assets/scaffold-template/ and installs the latest reacticle package. To view all available visual themes:

bash skills/beautiful-article/scripts/scaffold.sh --list-themes

The 11 theme profiles—including Tufte, Press, Bayer, and Freddie—are registered in theme-profiles/index.json.

Converting Source Materials

Transform PDFs, DOCX files, or HTML pages into the pipeline's native Markdown format using the extraction script:

python scripts/source-to-markdown.py /path/to/document.pdf

The script outputs to source/source.md, preserving semantic structure and metadata. If MarkItDown is unavailable, the fallback handler processes basic Markdown and simple HTML sources.

Building and Exporting Articles

Once your content is structured in the workspace, compile the final artifact:

cd my-article
npm install
npm run build

The build process generates article/article.html—a single file containing all CSS, JavaScript, and assets necessary for standalone distribution. Because the output adheres to the reacticle component contract (using semantic components like Hero, Section, Quote, and Image), you can also import the generated TSX files into existing React applications.

Generating PDF Outputs

For archival or print distribution, convert the HTML artifact to PDF without additional npm dependencies:

bash scripts/html-to-pdf.sh

This script executes a headless browser operation, producing article/article.pdf alongside the HTML source.

Theming and Visual Consistency

The beautiful-article skill enforces strict token-driven design through the reacticle library. Each theme profile consists of a CSS token bundle (defining --ra-* CSS variables) and an authoring contract (a .md file specifying how agents should write content for that visual language).

Raw Content Policies

All embedded HTML blocks must consume only the theme's defined tokens. The Raw policy (references/raw-policy.md) explicitly rejects stray colors, fonts, or inline styles. This constraint ensures that switching themes automatically rewires every raw block's appearance without manual refactoring.

Information Retention Controls

Users may override default retention ratios at Checkpoint 1 based on the article type selected in plan.md. This parameter directly influences how much detail the extraction phase preserves when converting source materials to Markdown, allowing precise control over content density versus brevity.

Summary

• The beautiful-article skill provides an eight-phase pipeline with three mandatory quality checkpoints to transform raw content into publication-ready HTML.
• Source materials—including PDFs, DOCX files, and URLs—are normalized to Markdown via scripts/source-to-markdown.py before entering the editorial workflow.
• The reacticle component library supplies semantic React components and 11 distinct theme profiles, ensuring consistent visual output through CSS token enforcement.
• Final artifacts are built as self-contained HTML files via npm run build, with optional PDF generation handled by scripts/html-to-pdf.sh.
• The scaffold script (scripts/scaffold.sh) initializes Vite + React + TypeScript workspaces pre-configured for the beautiful-article workflow.

Frequently Asked Questions

What content types can I convert using the beautiful-article skill?

The skill accepts URLs, PDF documents, Microsoft Word (DOCX) files, Markdown files, plain-text notes, and image screenshots. The source-to-markdown.py script handles extraction and normalization for each format, outputting a standardized Markdown file that feeds into the editorial pipeline.

How do I change the visual theme of my generated HTML article?

Themes are selected during the scaffolding phase using the --theme flag or defined in the plan.md during Checkpoint 1. The skill supports 11 predefined profiles (such as Tufte, Press, and Bayer) stored in theme-profiles/index.json. Each theme provides a CSS token bundle that automatically styles all reacticle components and raw HTML blocks according to the Raw policy constraints.

Is it possible to export articles to formats other than HTML?

Yes. While the primary output is a self-contained HTML file produced by npm run build, the repository includes scripts/html-to-pdf.sh for zero-dependency PDF generation. This script uses a headless browser to render the final HTML and save it as article/article.pdf, requiring no additional Node.js packages beyond the standard build toolchain.

What role does the reacticle package play in this workflow?

reacticle is the component protocol that supplies semantic React components—including Article, Hero, Section, Quote, and Image—used to construct the final document. It also provides the 11 theme profiles and CSS token system that enforce visual consistency. The beautiful-article skill generates TSX files that import these components, ensuring the output remains compatible with any React project that uses reacticle.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}