Skip to content

Agent skills for useful HTML artifacts, wireframes, interactive prototypes, plans, and diagrams.

9.4 KB
Raw Blame
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/big-pics-little-words",
  "/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");
}