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

> Transform URLs, PDFs, DOCX, Markdown, and images into polished HTML articles with the beautiful article skill in garden skills. Create themed content easily.

- Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills)
- Tags: how-to-guide
- Published: 2026-08-31

---

**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`](https://github.com/ConardLi/garden-skills/blob/main/scripts/source-to-markdown.py) script extracts and normalizes content into [`source.md`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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
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
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`](https://github.com/ConardLi/garden-skills/blob/main/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:

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

```

The script outputs to [`source/source.md`](https://github.com/ConardLi/garden-skills/blob/main/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:

```bash
cd my-article
npm install
npm run build

```

The build process generates [`article/article.html`](https://github.com/ConardLi/garden-skills/blob/main/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
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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/scripts/html-to-pdf.sh).
- The scaffold script ([`scripts/scaffold.sh`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/plan.md) during Checkpoint 1. The skill supports 11 predefined profiles (such as Tufte, Press, and Bayer) stored in [`theme-profiles/index.json`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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.