beautiful-html-templates: an agent picks from 34 folders, and you get three slides of proof

The interface is AGENTS.md, index.json, and a clone

There is no command to run and no package to import. The README puts the whole usage path in one sentence meant to be pasted into a coding agent:

Clone https://github.com/zarazhangrui/beautiful-html-templates and follow the instructions in AGENTS.md to build me a beautiful HTML slide deck.

`AGENTS.md` is called the operating manual, and the README names its four jobs: read `index.json`, match the user's brief to a template, clone it, and adapt the content. That is the entire interface. Selection is a judgment made by a model reading descriptions, not a query you can code against, so there is no deterministic call that returns the template with a property you care about.

The consequence shows up in reproducibility. Two runs with the same brief can land on different folders, because what gets picked depends on how a model reads a set of one-line descriptions. The only record of what you actually got is the folder that was cloned, which means you find out what you have by looking at what exists on disk after the fact.

index.json is the only machine-readable thing in the root

The root is small and worth knowing by heart: `.gitignore`, `AGENTS.md`, `LICENSE`, `README.md`, `index.json`, plus `runtime/`, `screenshots/`, `scripts/` and `templates/`. Of those, the README tells agents to read `AGENTS.md`, which covers how to read `index.json`, and the README shows none of the contents of `index.json`. No field name, no schema, no example record. The README also does not describe what is in `runtime/` or `scripts/`, so treat those as opaque until you open them.

What a human reads instead is the gallery: a heading, a link to the template's folder, and one line of description. The README says clicking a name opens the folder on GitHub, where the HTML, the metadata and any sibling assets are. Note the split. The metadata an agent matches against is whatever `index.json` holds; the description you judge by is a sentence in the README. Nothing in the page says the two agree.

So the practical order for an engineer is index first, gallery second. Read `index.json` to know what the selection step actually sees, and treat the README descriptions as marketing copy about a folder rather than as documentation of it.

Three slides per template, and none of them is a dense slide

The gallery shows all 34 templates with three slides each: a cover, a mid-deck slide, and a later slide, offered to give a sense of how each visual system handles different layouts. The folder links all follow the same shape:

./templates/soft-editorial/
./templates/editorial-forest/
./templates/pin-and-paper/

Three slides is a reasonable budget for judging a look and a poor budget for judging a system. What three slides cannot cover is every case that might break a layout: a table with eight columns, a code block longer than the slide is wide, a bullet list with twenty items, a chart, a two-column comparison. Those are exactly the slides that decide whether a template survives real content, and the gallery is structurally incapable of showing them.

There is also a separation worth noticing between the two directories. `screenshots/` and `templates/` are separate directories at the root. If you need to know whether a template can hold a dense slide, the answer is in the folder, and you have to open it.

Thirty-four names cover about six visual systems

The names do not cluster the way the designs do, and that matters when a model is choosing by reading. Three entries are neo-brutalist: Neo-Grid Bold, a single neon yellow accent on off-white paper; BlockFrame, pastel-neon colour blocks with chunky black borders; and Raw Grid, thick borders, offset shadows, and a pink, sage and ink palette. A dark canvas with one accent appears repeatedly as well: Vellum is deep navy with warm-yellow italic Cormorant, Signal is deep navy with bone paper and muted gold, Studio is a black canvas with electric-yellow type, and Coral is cream and coral on near-black in oversized Bebas Neue.

Two entries lean on Playfair serifs over a quiet warm palette, Cartesian and Grove. Four lean on handwriting or poster display faces: Pin & Paper with ink-blue Caveat on yellow paper, Scatterbrain with Caveat, Shrikhand and Zilla Slab on pastel sticky notes, Retro Zine with Bebas Neue and Caveat, and Bold Poster with massive Shrikhand and one fire-engine red accent.

The lesson for a brief is blunt. If your instruction to the agent is dark and premium, four or five folders are a reasonable answer and one of them will be right by luck. If it is neo-brutalist with a bright accent, three are. Counting templates tells you nothing about how many distinct results you can get.

Two cobalt templates that have nothing in common

Blue Professional is described as a cream paper background with electric cobalt blue accents, clean and modern professional. Cobalt Grid is electric cobalt italic serifs on a graph-paper canvas, anchored by stair-stepped pixel-glitch decorations and slim hairline rules. The same colour word, opposite jobs: one uses cobalt as an accent against light paper, the other uses it as the display face on a technical grid.

Monochrome is the third case worth knowing. It is ivory ledger paper with all-black type, Lora serif headlines, Jost body, and no colour at all, which means it is invisible to any filter that assumes a palette.

This matters the moment your brief mentions a colour. A word like cobalt in a template name tells you nothing about whether the colour will be a background, a headline, a rule, or absent. If brand colour is part of the requirement, the descriptions have to be read one by one, and the agent will not do that reliably on your behalf, because it is selecting rather than auditing.

One entry names a CJK type stack, the rest assume Latin

Broadside is described as a dark editorial canvas with a single fire orange accent and a bilingual Latin/Chinese type stack. Sakura Chroma is the only other entry with a non-Latin reference, a vintage Japanese cassette-package aesthetic with cream paper, diagonal rainbow ribbons, condensed bold type and JIS-style spec checkboxes.

The other descriptions that name a typeface name Latin ones, from Cormorant Garamond on warm paper through Archivo Black display type to MS Sans Serif pixel typography in Retro Windows. Taken together, the descriptions name well over a dozen distinct typefaces, which tells you each template brings its own font requests along with its layout.

For a deck in Chinese, Japanese or Korean, that leaves you with one template that names the problem and 33 whose descriptions do not mention CJK. Any of them will need font and line-height work on top before it is usable in those scripts, and the gallery will not warn you which layouts survive that work, because the gallery does not show your text.

MIT and free, with no tag to pin

The licence line reads MIT, free to use, modify, and distribute, with `LICENSE` at the root. That settles what you may do with a template. It does not settle which version you got.

There are no GitHub releases, and the last push was on 2026-06-09. So there is no tag, no version string in the README, and no changelog. The count of 34 is a number in prose that a commit can change without anything announcing it, and an agent that clones on demand takes whatever the default branch holds that day.

There is one stable artifact, and it is the useful part. Each template is a folder holding its HTML, its metadata and any sibling assets. If you copy that folder into your own repository and stop depending on the upstream, you own it completely and the missing releases stop mattering. That is the cheapest way to use this library, and it is the opposite of the clone-on-demand workflow the README is written for.

Editorial conclusion

Use this library when a deck is a byproduct of other work and the visual decision should not cost you an afternoon, and when an agent in your loop is the thing doing the assembling. Do not use it when the template has to survive content you have not written yet, a CJK script, or a layout with dense tables, because the gallery only shows a cover, a mid-deck slide and a later slide. Before you rely on it, verify three things yourself: that the folder your agent cloned is the one you wanted, that `index.json` agrees with the README's one-line descriptions, and that you have pinned a commit, since 34 is a number in prose and there is no tagged release to hold it still.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. zarazhangrui/beautiful-html-templates on GitHub