Skip to content
Skills Library
Programming · Conversion & formats

html-artifact-builder

/html-artifact-builder

Turn a request or an existing Markdown document into ONE self-contained HTML file that opens offline with no external references. Two paths - compose a page with React + TypeScript + Vite + Tailwind + shadcn/ui (43 components) for interactive tabs, accordions, charts or rich layout; or render an existing .md with a sidebar table of contents, full-text search, syntax highlighting and copy buttons. Use when someone wants a shareable single-file page, a navigable HTML version of a document, or a deliverable with more layout control than Markdown gives.

Licence
Apache-2.0
Last repository change
12.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
68
Scripts
50
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What to check before installing
  • 50 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/bundle-artifact.sh, scripts/check-md-fences.py, scripts/init-artifact.sh, scripts/md-to-html.sh, templates/markdown-doc/MarkdownDocument.tsx, templates/shadcn/components/ui/accordion.tsx, templates/shadcn/components/ui/alert.tsx, templates/shadcn/components/ui/aspect-ratio.tsx

What it does and when to use it

Turn a request or an existing Markdown document into ONE self-contained HTML file that opens offline with no external references. Two paths - compose a page with React + TypeScript + Vite + Tailwind + shadcn/ui (43 components) for interactive tabs, accordions, charts or rich layout; or render an existing .md with a sidebar table of contents, full-text search, syntax highlighting and copy buttons. Use when someone wants a shareable single-file page, a navigable HTML version of a document, or a deliverable with more layout control than Markdown gives.

Original author description

Turn a request or an existing Markdown document into ONE self-contained HTML file that opens offline with no external references. Two paths - compose a page with React + TypeScript + Vite + Tailwind + shadcn/ui (43 components) for interactive tabs, accordions, charts or rich layout; or render an existing .md with a sidebar table of contents, full-text search, syntax highlighting and copy buttons. Use when someone wants a shareable single-file page, a navigable HTML version of a document, or a deliverable with more layout control than Markdown gives.

How it works

  1. Stack
  2. Platform
  3. Quick Start — the main path (React)
  4. Rendering an existing Markdown file
  5. Keeping the bundle self-contained
  6. Design Guidelines
  7. Reference
Original SKILL.md headings · 231 lines, 1,517 words
SKILL.md preview
---
name: html-artifact-builder
description: Turn a request or an existing Markdown document into ONE self-contained HTML file that opens offline with no external references. Two paths - compose a page with React + TypeScript + Vite + Tailwind + shadcn/ui (43 components) for interactive tabs, accordions, charts or rich layout; or render an existing .md with a sidebar table of contents, full-text search, syntax highlighting and copy buttons. Use when someone wants a shareable single-file page, a navigable HTML version of a document, or a deliverable with more layout control than Markdown gives.
license: Complete terms in LICENSE.txt
---

# HTML Artifacts Builder

Build a **single, self-contained HTML file** that far outclasses Markdown in
expressiveness. No server, no sharing required — just open the file.

Bundling uses **Vite + vite-plugin-singlefile**. Do not switch back to Parcel:
Parcel 2.16 cannot resolve `@radix-ui/primitive`'s nested `development` /
`production` export conditions, and every shadcn/ui component fails to build.
The full history of that decision, and the other ways this skill diverges from
Anthropic's `web-artifacts-builder`, is in `DECISIONS.md`.

## Stack

React 18 + TypeScript + Vite + Tailwind CSS 3.4.1 + shadcn/ui (43 components) + lucide-react

## Platform

The scripts are **bash**. Run them with `bash scripts/<name>.sh …` — never
paste them into PowerShell or `cmd`, where `bash` may not resolve.

| Host | How to run |
|---|---|
| macOS / Linux | Native shell |
| Windows | **Git for Windows → Git Bash**, or WSL. Not PowerShell, not `cmd` |
| Python | Resolved automatically: `python3` → `python` → `py` (Python 3 only) |

Never hardcode `python3` in a new script: on Windows a python.org install only
provides `python.exe` / `py.exe`, and the Microsoft Store alias leaves a
`python3.exe` stub that exists but fails. Probe with
`"$cmd" -c 'import sys; sys.exit(0 if sys.version_info[0] == 3 else 1)'`.


## Quick Start — the main path (React)

Compose the page in React, then bundle it to one file. Use the Markdown renderer
further down only when the content already exists as a `.md`.

### Step 1 — Initialize

```bash
bash scripts/init-artifact.sh <project-name>
cd <project-name>
```

Creates a configured project with:
- React + TypeScript via Vite, `@/` path aliases wired for both Vite and `tsc`
- Tailwind 3.4.1 with the full shadcn/ui CSS-variable theme (light + dark)
- 43 shadcn/ui components in `src/components/ui/`, all Radix deps installed
- `vite-plugin-singlefile` configured, `assetsInlineLimit` raised so assets inline
- A smoke build, so you know the scaffold works before writing any code

### Step 2 — Build

Edit `src/App.tsx`. Import components:

```tsx
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs'
import { Badge } from '@/components/ui/badge'
import { Progress } from '@/components/ui/progress'
import { Button } from '@/components/ui/button'
import { Copy, Check } from 'lucide-react'
```

**Keep the build timestamp at the top.** The scaffold's `src/components/BuildStamp.tsx`
renders `__BUILD_TIME__` — a `YYYY-MM-DD HH:MM:SS` local-time string that
`vite.config.ts` bakes in at build time (so it says when the file was produced,
not when it was scaffolded or opened). Leave `<BuildStamp />` as the first
element of the page, above the title. Only drop it if the user explicitly asks
for a page without a timestamp. On a non-English page pass the label, e.g.
`<BuildStamp label="生成时间" />`.

Optional live preview while developing:

```bash
pnpm dev
```

### Step 3 — Bundle to one file

```bash
bash scripts/bundle-artifact.sh
```

Produces `bundle.html` — one file, everything inlined. The script then runs a
self-containment check and reports:

```
✅ Self-contained: no root-relative refs, no import-maps.
```

If it prints ⚠️ instead, something leaked out as an external reference; fix it
before shipping the file.

### Step 4 — Open it

```bash
open bundle.html        # macOS
start bundle.html       # Windows (cmd / PowerShell)
xdg-open bundle.html    # Linux
```

No artifact renderer is needed — it is a plain file you can double-click.

## Rendering an existing Markdown file

When the content already exists as Markdown and you would rather not design a
page by hand, use the bundled renderer instead of building one in React:

```bash
bash scripts/md-to-html.sh path/to/doc.md [--title "Tab title"] [--lang zh-CN]
```

The document title in the page header is also a button: clicking it hides or
shows the left-hand contents sidebar, for when the text needs the full width.

### Set the browser-tab title deliberately

Markdown has **no title metadata** — the H1 is a document heading, not a tab
label. The scaffold directory name is a throwaway build detail and reads badly
in a browser tab (this skill previously shipped `<title>testdoc</title>` and
`<title>v1</title>`). So:

**Choose `--title` yourself.** Read the document, then write a short,
human-readable name — ideally "topic · specific focus" rather than the raw H1,
which is usually too long for a tab and carries dates/emoji.

| Document | Avoid (raw H1) | Prefer (`--title`) |
|---|---|---|
| `samples/sample-doc.md` | `冒烟样本 · 全特性覆盖` | `冒烟样本 · 全特性` |
| Release notes | `Release notes · bundler moved from Parcel to Vite, and what broke` | `Release notes · Parcel to Vite` |

Resolution order when `--title` is omitted: **first H1 → filename stem**.
`--lang` follows the same idea: pass it explicitly, or it auto-detects `zh-CN`
vs `en` from CJK character density. It drives **both** `<html lang>` and the UI
chrome (TOC label, search placeholder, copy button), so an English document does
not get a Chinese sidebar.

Ready-made regression fixtures live in `samples/`: `sample-doc.md` (Chinese)
and `sample-doc-en.md` (English), each with its rendered `.html` next to it. They
cover wide tables, tagged and untagged fences, `## ` inside a fence, all five
callout kinds, task lists and inline code. Render it and eyeball the result after any
change to the renderer:

```bash
bash scripts/md-to-html.sh samples/sample-doc.md --title "冒烟样本 · 全特性"
```

It writes `doc.html` next to the source and **never modifies the source**. You get:
- **generation timestamp at the very top** (`YYYY-MM-DD HH:MM:SS`, baked in at
  build time — the page states when it was produced)
- sticky sidebar TOC with scroll-spy, full-text search
- **light GitHub-style code blocks** with real syntax highlighting
  (highlight.js, registered per-language and bundled — no CDN)
- language chips + one-click copy on every code block
- callouts inferred from blockquote lead emoji (⚠️ warn / 🔴 danger / ✅ ok / 👉 tip / 📌 note)
- `## `-inside-fenced-code is ignored, so embedded README templates don't
  become phantom TOC entries — **provided the fences are written correctly**.
  CommonMark closes a fence at the first *bare* fence of the same character and
  at least the same length, so a ` ``` ` nested inside a ` ``` ` block closes
  the outer block early: the rest of the document renders as body text, and any
  `## ` left behind becomes a real heading. Write the outer block in **four**
  backticks (` ````markdown ` … ` ```` `) and keep the inner block at three.

### Fence preflight

That early-close shape renders correctly per CommonMark — GitHub (cmark-gfm) and
`marked` agree — so it is not a renderer bug and nothing in the pipeline used to
flag it. `scripts/check-md-fences.py` runs **before any install**, reports the
opening line, the nested line and the line that actually closes the block, and
lets the render continue:

```
⚠️  Fence  : doc.md 第 11 行 ```markdown 内有嵌套 fence(第 16 行 ```bash)
       →   实际闭合于第 18 行,其后的内容会被当成正文渲染
       →   修法:外层改用 4 个反引号(````markdown … ````),或把内部 fence 缩进 4 空格
ℹ️  渲染继续;加 --strict-fences 可让此情况直接失败
```

`--strict-fences` turns the warning into a non-zero exit — and because the
preflight sits before `pnpm`, a broken document fails in about 0.1 s instead of
after a two-minute install.

Implementation lives in `templates/markdown-doc/`:
`MarkdownDocument.tsx` (component), `doc-typo.css` (document typography),
`code-theme.css` (GitHub Light token palette).

**Code colouring is opt-in by design.** A plain shadcn `Card` full of `<pre>`
renders code on a dark background with no token colours. If you build a page by
hand and want the GitHub look, `@import`/append `code-theme.css` and run each
block through `highlight.js` — adding the CSS alone gives you an unstyled block,
because highlight.js is what emits the `<span class="hljs-*">` tokens.

## Keeping the bundle self-contained

The single biggest cause of breakage is **referencing a file by absolute path**.
Rules that actually matter:

| Do | Don't |
|---|---|
| Inline SVG (paste the markup or use `lucide-react` icons) | Import `.png` / `.jpg` / `.svg` from `src/assets` |
| Use CSS gradients, borders, and shapes for decoration | Reference `/images/foo.png` |
| Use system fonts or web-safe font stacks | Load Google Fonts via `<link>` |
| Keep data as inline TS objects | `fetch()` a local JSON file |

`lucide-react` icons compile into inline SVG, so they add zero external requests.
The scaffolded `<html>` carries **no** `class="dark"`: the light theme is the
default, which is what the Markdown renderer's GitHub-light code palette assumes.
Use theme tokens (`bg-background`, `text-foreground`, `text-muted-foreground`)
instead of hardcoded colours — `text-slate-100` on a light `bg-card` produces
invisible white-on-white text, and `bg-slate-950` fights the light document page.

**One gap on the Markdown path.** The source `.md` is embedded verbatim, so an
image written as `![alt](https://…)` stays a remote URL and the page fetches it
when opened. Nothing downloads or inlines it for you. If the file has to work
offline, either drop the image or replace it with a `data:` URI in the source —
those are inlined by definition and need no network.

## Design Guidelines

Avoid what reads as "AI slop": excessive centered layouts, purple gradients,
uniform rounded corners, and the Inter font. Prefer a deliberate palette, real
information density, and semantic use of color (e.g. green for pass, amber for
below target).

## Reference

- shadcn/ui components: https://ui.shadcn.com/docs/components
- Tailwind CSS: https://tailwindcss.com/docs
Files in this package (68)
  • .gitattributes 1 KB
  • .gitignore 1 KB
  • DECISIONS.md 6 KB
  • ISSUES.md 10 KB
  • LICENSE.txt 11 KB
  • NOTICE.md 6 KB
  • README.md 6 KB
  • README.zh-CN.md 6 KB
  • SKILL.md 10 KB
  • samples/nested-fence.md 1 KB
  • samples/preview-en.png 101 KB
  • samples/preview-zh.png 127 KB
  • samples/sample-doc-en.html 376 KB
  • samples/sample-doc-en.md 5 KB
  • samples/sample-doc.html 376 KB
  • samples/sample-doc.md 5 KB
  • scripts/bundle-artifact.sh 3 KB
  • scripts/check-md-fences.py 7 KB
  • scripts/init-artifact.sh 16 KB
  • scripts/md-to-html.sh 10 KB
  • templates/markdown-doc/MarkdownDocument.tsx 14 KB
  • templates/markdown-doc/code-theme.css 2 KB
  • templates/markdown-doc/doc-typo.css 4 KB
  • templates/shadcn/components/ui/accordion.tsx 2 KB
  • templates/shadcn/components/ui/alert.tsx 2 KB
  • templates/shadcn/components/ui/aspect-ratio.tsx 1 KB
  • templates/shadcn/components/ui/avatar.tsx 1 KB
  • templates/shadcn/components/ui/badge.tsx 1 KB
  • templates/shadcn/components/ui/breadcrumb.tsx 3 KB
  • templates/shadcn/components/ui/button.tsx 2 KB
  • templates/shadcn/components/ui/calendar.tsx 7 KB
  • templates/shadcn/components/ui/card.tsx 2 KB
  • templates/shadcn/components/ui/carousel.tsx 6 KB
  • templates/shadcn/components/ui/checkbox.tsx 1 KB
  • templates/shadcn/components/ui/collapsible.tsx 1 KB
  • templates/shadcn/components/ui/command.tsx 5 KB
  • templates/shadcn/components/ui/context-menu.tsx 7 KB
  • templates/shadcn/components/ui/dialog.tsx 4 KB
  • templates/shadcn/components/ui/drawer.tsx 3 KB
  • templates/shadcn/components/ui/dropdown-menu.tsx 8 KB
  • templates/shadcn/components/ui/form.tsx 4 KB
  • templates/shadcn/components/ui/hover-card.tsx 1 KB
  • templates/shadcn/components/ui/input.tsx 1 KB
  • templates/shadcn/components/ui/label.tsx 1 KB
  • templates/shadcn/components/ui/menubar.tsx 9 KB
  • templates/shadcn/components/ui/navigation-menu.tsx 5 KB
  • templates/shadcn/components/ui/popover.tsx 1 KB
  • templates/shadcn/components/ui/progress.tsx 1 KB
  • templates/shadcn/components/ui/radio-group.tsx 1 KB
  • templates/shadcn/components/ui/resizable.tsx 2 KB
  • templates/shadcn/components/ui/scroll-area.tsx 2 KB
  • templates/shadcn/components/ui/select.tsx 6 KB
  • templates/shadcn/components/ui/separator.tsx 1 KB
  • templates/shadcn/components/ui/sheet.tsx 4 KB
  • templates/shadcn/components/ui/skeleton.tsx 1 KB
  • templates/shadcn/components/ui/slider.tsx 1 KB
  • templates/shadcn/components/ui/sonner.tsx 1 KB
  • templates/shadcn/components/ui/switch.tsx 1 KB
  • templates/shadcn/components/ui/table.tsx 3 KB
  • templates/shadcn/components/ui/tabs.tsx 2 KB
  • templates/shadcn/components/ui/textarea.tsx 1 KB
  • templates/shadcn/components/ui/toast.tsx 5 KB
  • templates/shadcn/components/ui/toaster.tsx 1 KB
  • templates/shadcn/components/ui/toggle-group.tsx 2 KB
  • templates/shadcn/components/ui/toggle.tsx 2 KB
  • templates/shadcn/components/ui/tooltip.tsx 1 KB
  • templates/shadcn/hooks/use-toast.ts 4 KB
  • templates/shadcn/lib/utils.ts 1 KB

Versions

The database has no other skills named html-artifact-builder.

Database snapshot: 13.11.2026 · package version 467b85d6830a (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100web-artifacts-builder
    Builds multi-component web artifacts (React + TypeScript + Material UI + framer-motion, optional three.js) bundled into one self-contained HTML file shown beside the chat - scaffold, live preview, vite-plugin-singlefile bundle. Use when the user asks to "build an interactive…
  • 95artifacts-builder
    当用户需要创建复杂的多组件 HTML Artifacts(包含 React、Tailwind CSS、shadcn/ui)时使用。此 Skill 用于需要状态管理、路由或 shadcn/ui 组件的复杂 Artifacts,不适用于简单的单文件 HTML/JSX。
  • 100web-artifacts-builder
    Build claude.ai HTML artifacts from a React + Tailwind + shadcn template with a page kit, a theme design system, a themed diagram renderer and a one-call build+verify. Use for interactive or multi-section artifacts needing state, charts, diagrams or components — not a trivial single-file snippet.
  • 100web-artifacts-builder
    Suite of tools for creating elaborate, multi-component HTML applications using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - Bundles into a single HTML file for preview.
  • 100render-html
    Render an ARIS Markdown / JSON artifact (IDEA_REPORT, AUTO_REVIEW, KILL_ARGUMENT, PAPER_PLAN, research-wiki state, etc.) into a single-file HTML view designed for human reading. Use when the user says \"Render HTML\", \"Here's a copy. HTML Report\", \"render html\", \"make this…
  • 100artifacts-builder
    Suite of tools for creating elaborate, multi-component AI artifacts viewer HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.