Agent skills for useful HTML artifacts, wireframes, interactive prototypes, plans, and diagrams.
Add llms.txt and page Markdown exports
Michael Ramoscc8491aa9d1b
diff --git a/site/app/catalog.md/route.ts b/site/app/catalog.md/route.tsnew file mode 100644index 0000000..c36f0fd--- /dev/null+++ b/site/app/catalog.md/route.ts@@ -0,0 +1,7 @@+import { getCatalogMarkdown, markdownResponse } from "@/lib/llm-content";++export const revalidate = false;++export function GET() {+ return markdownResponse(getCatalogMarkdown());+}diff --git a/site/app/examples.md/route.ts b/site/app/examples.md/route.tsnew file mode 100644index 0000000..18bf3f8--- /dev/null+++ b/site/app/examples.md/route.ts@@ -0,0 +1,7 @@+import { getExamplesMarkdown, markdownResponse } from "@/lib/llm-content";++export const revalidate = false;++export function GET() {+ return markdownResponse(getExamplesMarkdown());+}diff --git a/site/app/index.md/route.ts b/site/app/index.md/route.tsnew file mode 100644index 0000000..798a007--- /dev/null+++ b/site/app/index.md/route.ts@@ -0,0 +1,7 @@+import { getHomeMarkdown, markdownResponse } from "@/lib/llm-content";++export const revalidate = false;++export function GET() {+ return markdownResponse(getHomeMarkdown());+}diff --git a/site/app/llms-full.txt/route.ts b/site/app/llms-full.txt/route.tsnew file mode 100644index 0000000..9658967--- /dev/null+++ b/site/app/llms-full.txt/route.ts@@ -0,0 +1,11 @@+import { getLlmsFull } from "@/lib/llm-content";++export const revalidate = false;++export async function GET() {+ return new Response((await getLlmsFull()).trimEnd() + "\n", {+ headers: {+ "Content-Type": "text/plain; charset=utf-8",+ },+ });+}diff --git a/site/app/llms.mdx/docs/[[...slug]]/route.ts b/site/app/llms.mdx/docs/[[...slug]]/route.tsindex 9334cfa..adc1919 100644--- a/site/app/llms.mdx/docs/[[...slug]]/route.ts+++ b/site/app/llms.mdx/docs/[[...slug]]/route.ts@@ -1,3 +1,4 @@+import { getGuideMarkdown, markdownResponse } from "@/lib/llm-content";import { source } from "@/lib/source";import { notFound } from "next/navigation";@@ -15,13 +16,7 @@ export async function GET(_request: Request, { params }: RouteProps) {if (!page) notFound();- const markdown = await page.data.getText("processed");-- return new Response(`# ${page.data.title}\n\n${markdown}`, {- headers: {- "Content-Type": "text/markdown; charset=utf-8",- },- });+ return markdownResponse(await getGuideMarkdown(page));}/** Return every guide slug for static generation. */diff --git a/site/app/llms.txt/route.ts b/site/app/llms.txt/route.tsnew file mode 100644index 0000000..045531b--- /dev/null+++ b/site/app/llms.txt/route.ts@@ -0,0 +1,11 @@+import { getLlmsIndex } from "@/lib/llm-content";++export const revalidate = false;++export function GET() {+ return new Response(getLlmsIndex().trimEnd() + "\n", {+ headers: {+ "Content-Type": "text/plain; charset=utf-8",+ },+ });+}diff --git a/site/lib/llm-content.ts b/site/lib/llm-content.tsnew file mode 100644index 0000000..a8ab240--- /dev/null+++ b/site/lib/llm-content.ts@@ -0,0 +1,255 @@+import {+ catalogArtifacts,+ catalogCategories,+ catalogSkills,+ featuredNativeArtifact,+ nativeExamples,+} from "@/lib/catalog-data";+import { source } from "@/lib/source";++const siteOrigin = "https://www.effectivehtml.com";+const guideOrder = [+ "/docs",+ "/docs/why-html",+ "/docs/designing-artifacts",+ "/docs/choosing-fidelity",+ "/docs/wireframes",+ "/docs/prototypes",+ "/docs/diagrams",+ "/docs/decks",+ "/docs/plans",+];++function absoluteUrl(path: string) {+ return new URL(path, siteOrigin).toString();+}++function markdownLink(label: string, href: string, description: string) {+ return `- [${label}](${absoluteUrl(href)}): ${description}`;+}++function getOrderedGuidePages() {+ return [...source.getPages()].sort((a, b) => {+ const aIndex = guideOrder.indexOf(a.url);+ const bIndex = guideOrder.indexOf(b.url);+ return (+ (aIndex === -1 ? guideOrder.length : aIndex) -+ (bIndex === -1 ? guideOrder.length : bIndex)+ );+ });+}++/** Return Markdown with headers that make the representation explicit to clients. */+export function markdownResponse(markdown: string) {+ return new Response(markdown.trimEnd() + "\n", {+ headers: {+ "Content-Type": "text/markdown; charset=utf-8",+ },+ });+}++/** Return the Markdown representation of a Fumadocs guide page. */+export async function getGuideMarkdown(+ page: (typeof source)["$inferPage"],+) {+ const processed = await page.data.getText("processed");++ return `# ${page.data.title}++> ${page.data.description ?? "Effective HTML guide page."}++Human-readable page: ${absoluteUrl(page.url)}++${processed}`;+}++/** Return the Markdown representation of the homepage. */+export function getHomeMarkdown() {+ return `# Effective HTML++> A reference site showcasing visual and interactive HTML artifacts you can create with agents.++Effective HTML is by [Plannotator](https://plannotator.ai).++Human-readable page: ${absoluteUrl("/")}++## What you can make with HTML++- [Wireframes](${absoluteUrl("/docs/wireframes")}): Compare hierarchy, content, navigation, and responsive structure.+- [Mockups](${absoluteUrl("/docs/choosing-fidelity")}): Show how a product could look with realistic content and visual design.+- [Prototypes](${absoluteUrl("/docs/prototypes")}): Try flows, state changes, validation, loading, errors, and success.+- [Diagrams](${absoluteUrl("/docs/diagrams")}): Explain architecture, sequences, state, hierarchy, and flow.+- [Decks](${absoluteUrl("/docs/decks")}): Build browser-native presentations with interaction and animation.+- [Plans](${absoluteUrl("/docs/plans")}): Add visual comparison, timelines, dependencies, or embedded examples when Markdown is not enough.++## Why HTML?++Markdown is often enough. Use HTML when you need to compare designs, change states, follow a flow, or try the thing yourself.++## Main links++- [Browse the catalog](${absoluteUrl("/catalog")}): Open the complete collection of HTML artifacts, SVGs, examples, and skills.+- [Read the guide](${absoluteUrl("/docs")}): Short overviews of the main artifact formats.+- [View the source](https://github.com/plannotator/effective-html): Repository, examples, and installable skills.`;+}++/** Return a complete Markdown catalog generated from the same data as the UI. */+export function getCatalogMarkdown() {+ const sections = catalogCategories.map((category) => {+ const references = catalogArtifacts.filter(+ (artifact) => artifact.category === category.id,+ );+ const examples = nativeExamples.filter(+ (example) => example.category === category.id,+ );+ const lines = [`## ${category.label}`, "", category.description];++ if (category.id === "diagrams") {+ lines.push(+ "",+ "### Featured interactive artifact",+ "",+ markdownLink(+ featuredNativeArtifact.title,+ featuredNativeArtifact.htmlUrl,+ featuredNativeArtifact.description,+ ),+ " - [Source](https://github.com/plannotator/effective-html/blob/main/site/public/catalog/featured/workspaces-architecture.html)",+ );+ }++ if (references.length > 0) {+ lines.push("", "### HTML and SVG references", "");+ for (const artifact of references) {+ lines.push(+ markdownLink(artifact.title, artifact.htmlUrl, artifact.description),+ ` - [Static SVG](${absoluteUrl(artifact.staticSvg)})`,+ ` - [Animated SVG](${absoluteUrl(artifact.animatedSvg)})`,+ ` - [Static SVG source](${artifact.staticSourceUrl})`,+ ` - [Animated SVG source](${artifact.animatedSourceUrl})`,+ );+ if (artifact.resourceUrl && artifact.resourceLabel) {+ lines.push(+ ` - [${artifact.resourceLabel}](${absoluteUrl(artifact.resourceUrl)})`,+ );+ }+ }+ }++ if (examples.length > 0) {+ lines.push("", "### Effective HTML examples", "");+ for (const example of examples) {+ lines.push(+ markdownLink(+ `${example.title} (${example.stage})`,+ example.liveUrl,+ example.description,+ ),+ ` - [Guide](${absoluteUrl(example.guideUrl)})`,+ ` - [Source](${example.sourceUrl})`,+ );+ }+ }++ return lines.join("\n");+ });++ const skills = catalogSkills.flatMap((skill) => [+ markdownLink(skill.title, skill.guideUrl, skill.description),+ ` - [Skill source](${skill.sourceUrl})`,+ ]);++ return `# Effective HTML catalog++> Visual and interactive HTML artifacts you can open, inspect, and use as references for agent work.++Human-readable page: ${absoluteUrl("/catalog")}++The catalog combines Thariq Shihipar's twenty HTML references, static and animated Effective SVG interpretations, examples made for Effective HTML, an interactive architecture diagram, and the repository's skills.++${sections.join("\n\n")}++## Skills++${skills.join("\n")}++## Original sources++- [The unreasonable effectiveness of HTML](https://claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html)+- [HTML effectiveness examples](https://thariqs.github.io/html-effectiveness/)+- [Effective SVG](https://github.com/plannotator/effective-svg)+- [Effective HTML repository](https://github.com/plannotator/effective-html)`;+}++/** Return the Markdown representation of the examples landing page. */+export function getExamplesMarkdown() {+ return `# Release-readiness examples++> A wireframe and working prototype built from the same release-readiness brief.++Human-readable page: ${absoluteUrl("/examples")}++## Release readiness wireframe++A deliberately unfinished artifact for comparing hierarchy, content, navigation, and responsive structure.++- [Open the wireframe](${absoluteUrl("/examples/release-readiness/wireframe.html")})+- [View the source](https://github.com/plannotator/effective-html/blob/main/examples/release-readiness/wireframe.html)+- [Read the wireframe guide](${absoluteUrl("/docs/wireframes")})++## Release readiness prototype++A working flow for testing blocked, ready, loading, failure, and recovery states, including the boundary between validation and release.++- [Open the prototype](${absoluteUrl("/examples/release-readiness/prototype.html")})+- [View the source](https://github.com/plannotator/effective-html/blob/main/examples/release-readiness/prototype.html)+- [Read the prototype guide](${absoluteUrl("/docs/prototypes")})`;+}++/** Return the llms.txt index following the llmstxt.org structure. */+export function getLlmsIndex() {+ const guideLinks = getOrderedGuidePages().map((page) => {+ const markdownPath = page.url === "/docs" ? "/docs.md" : `${page.url}.md`;+ return markdownLink(+ page.data.title,+ markdownPath,+ page.data.description ?? "Effective HTML guide page.",+ );+ });++ return `# Effective HTML++> Effective HTML is a reference site for wireframes, mockups, prototypes, diagrams, decks, plans, and other visual or interactive artifacts made with agents.++Use the Markdown pages below for concise, navigation-free content. The catalog is generated from the same data as the human-facing collection.++## Main pages++${markdownLink("Home", "/index.md", "Overview of Effective HTML and the main artifact formats.")}+${markdownLink("Catalog", "/catalog.md", "Complete catalog of HTML references, SVGs, examples, and skills.")}+${markdownLink("Examples", "/examples.md", "Release-readiness wireframe and prototype.")}+${markdownLink("Complete site context", "/llms-full.txt", "All first-party page content in one file.")}++## Guide++${guideLinks.join("\n")}++## Optional++- [Effective HTML repository](https://github.com/plannotator/effective-html): Source, examples, and installable skills.+- [The unreasonable effectiveness of HTML](https://claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html): Thariq Shihipar's original essay.+- [Understanding is the new bottleneck](https://www.geoffreylitt.com/2026/07/02/understanding-is-the-new-bottleneck): Geoffrey Litt's essay on visual explanations and software understanding.+- [Effective SVG](https://github.com/plannotator/effective-svg): Static and animated SVG interpretations of the reference artifacts.`;+}++/** Return all first-party page content as one Markdown document. */+export async function getLlmsFull() {+ const guides = await Promise.all(getOrderedGuidePages().map(getGuideMarkdown));++ return [+ getHomeMarkdown(),+ getCatalogMarkdown(),+ getExamplesMarkdown(),+ ...guides,+ ].join("\n\n---\n\n");+}diff --git a/site/next.config.mjs b/site/next.config.mjsindex 3127478..2f6c911 100644--- a/site/next.config.mjs+++ b/site/next.config.mjs@@ -5,6 +5,26 @@ const config = {reactStrictMode: true,async rewrites() {return [+ {+ source: "/index.html.md",+ destination: "/index.md",+ },+ {+ source: "/catalog/index.html.md",+ destination: "/catalog.md",+ },+ {+ source: "/catalog/folio.md",+ destination: "/catalog.md",+ },+ {+ source: "/examples/index.html.md",+ destination: "/examples.md",+ },+ {+ source: "/docs/index.html.md",+ destination: "/docs.md",+ },{source: "/docs.md",destination: "/llms.mdx/docs",