DOCSEARCHbyAlgolia
Submit Docs

html-ppt

repository·main·Indexed 27 days ago

https://github.com/lewislulu/html-ppt-skill

An AgentSkill for producing professional HTML presentations using a library of 36 themes, 31 layouts, and 47 animations. It works as pure static HTML/CSS/JS without a build step and includes a dedicated Presenter Mode with synchronized speaker scripts and timers. Features include CSS entry animations, Canvas FX for continuous effects, and a headless Chrome script for rendering slides to PNG.

Tokens
7.6K
Snippets
11
Records
45
Agent score
92%

What's inside html-ppt-skill

  1. Understand the html-ppt file structure

    main

    The project is organized into the following directory structure:

    • assets/: Core logic and styling.
      • base.css: Tokens and primitives (do not edit per deck).
      • fonts.css: Webfont imports.
      • runtime.js: Handles keyboard navigation, presenter mode, overview, and theme cycling.
      • themes/*.css: 36 theme-specific token overrides.
      • animations/: Contains animations.css (27 CSS animations), fx-runtime.js (auto-initializes data-fx on slide entry), and fx/*.js (20 canvas FX modules like particles or fireworks).
    • templates/: Starter files and showcases.
      • deck.html: Minimal 6-slide starter.
      • full-decks/: 14 scoped multi-slide deck templates.
      • single-page/: 31 layout files with demo data.
    • scripts/: Utility scripts for scaffolding and rendering.
    • examples/demo-deck/: A complete working deck example.
    • references/: Detailed catalogs.

  2. Use the presenter-mode-reveal template

    main

    The fastest way to create a presentation with speaker notes is to use the pre-configured presenter-mode-reveal template. This template includes built-in support for the presenter view (triggered by the S key), theme switching (via the T key), and sample speaker notes for every slide.

    cp -r templates/full-decks/presenter-mode-reveal examples/my-talk

  3. Author and customize Full-Deck Templates

    main

    When building or modifying templates, follow these rules to maintain functionality:

    1. CSS Scoping: Always scope your CSS under the .tpl-<name> class prefix. This allows multiple templates to coexist on the same page without style collisions.
    2. Structural Integrity: You can swap demo content, but you must keep the structural classes. The template's identity is tied to these specific classes.
    3. JavaScript: Do not add your own navigation JS. All templates automatically use the shared assets/runtime.js for keyboard navigation, fullscreen, and theme cycling.
    4. Charts: Templates use hand-rolled SVG charts to avoid CDN dependencies. You can replace these with chart.js or echarts if you require interactivity.
    5. Presenter Notes: To add speaker notes to a template, include an <aside class="notes"> element for the corresponding slide.

  4. Authoring Rules and Best Practices

    main

    To ensure professional results and compatibility with the runtime:

    1. Use Templates: Always start by copying a layout from templates/single-page/ rather than writing raw HTML.
    2. Use Design Tokens: Never use literal colors (e.g., #111). Use CSS variables from assets/base.css (e.g., color: var(--text-1);).
    3. Include Runtime: Always include <script src="../assets/runtime.js"></script> to enable keyboard navigation and presenter mode.
    4. Slide Structure: Use exactly one <section class="slide"> per logical page. The runtime manages visibility via the .is-active class.
    5. Separation of Concerns: NEVER put presenter-only text (instructions, cues, or scripts) directly on the slide. Always place it inside <div class="notes">.

  5. Install html-ppt via npx

    main

    Install the html-ppt-skill to enable AI agents (like Claude Code, Cursor, or Codex) to generate professional HTML presentations. Use the following command to add the skill to your environment.

    npx skills add https://github.com/lewislulu/html-ppt-skill

  6. Apply a theme to your HTML PPT deck

    main
    You can apply a theme by updating the href attribute of the <link> element with id="theme-link". Alternatively, you can enable theme cycling by pressing the T key during presentation if you list the available themes on the <body> or <html> element using the data-themes attribute.

  7. Add presenter mode to an existing template

    main

    All full-deck templates automatically support the presenter view via the built-in runtime.js. To add speaker notes to an existing template, follow these two steps:

    1. Add an <aside class="notes"> (or <div class="notes">) element at the end of each <section class="slide"> containing your script.
    2. Ensure the HTML file includes the assets/runtime.js script.

    Note: The .notes class is set to display:none by default, so notes will only be visible in the presenter window.

  9. Configure themes and bilingual support

    main

    Theme Integration

    Wire a theme by adding a link tag to your HTML: `<link id="theme-link" href="../assets/themes/NAME.css">

    To allow users to cycle through themes using the T key, list alternative theme paths in the data-themes attribute on the <body> element.

    Bilingual (Chinese + English) Decks

    • Set <html lang="zh-CN"> on the root element.
    • Use <br> to stack bilingual titles. Use a <span class="dim"> for the English subtitle to maintain visual hierarchy.
    • Fonts like Noto Sans SC and Noto Serif SC are preloaded via fonts.css.

  10. Author slides using templates

    main

    Instead of writing slides from scratch, use existing single-page layouts.

    1. Locate a layout in templates/single-page/ (e.g., kpi-grid.html).
    2. Copy the <section class="slide">...</section> block.
    3. Paste it into your deck's index.html.
    4. Replace demo data while keeping the class structure intact.
    5. Set the data-title="..." attribute on the section for the Overview grid functionality.
    6. Add speaker notes inside a <div class="notes">...</div> block.

  11. Compose a new deck using single-page layouts

    main

    To build a presentation deck, use the standalone HTML files located in templates/single-page/<name>.html as building blocks.

    1. Open a layout file (e.g., templates/single-page/bullets.html) directly in Chrome to preview it.
    2. Copy the <section class="slide">...</section> block from that file.
    3. Paste the block into your main deck HTML file.
    4. Replace the demo data within the copied block with your own content.

    Note: Shared CSS (base, theme, and animations) is automatically handled by deck.html.