Skill Instructions

Purpose

Create and update interactive examples on the tfplan2md website using the Eleventy authoring model.

When to Use This Skill

• Adding new feature examples to feature detail pages
• Creating examples for the main examples page
• Updating existing examples when output format changes
• Adding before/after comparisons for feature pages

Current Authoring Model

Interactive examples are not hand-authored inline as large HTML blocks on page files.

• Page entrypoints live under website/src/pages/
• Interactive example source-of-truth lives under website/src/examples/<example-id>/
• Each example directory contains:
  • meta.json for the example title and metadata
  • rendered.html for the rendered output pane
  • source.html for the source pane markup
• Pages render examples through the Eleventy exampleBlock shortcode defined in website/.eleventy.js
• Shared interactive behavior is initialized globally from website/src/site-assets/js/site.js, so page-local script tags are not needed

Hard Rules

Must

• Edit page entrypoints in website/src/pages/ and example fragments in website/src/examples/; do not hand-edit generated output in website/dist/.
• Keep example IDs stable and descriptive, following the existing <page-or-section>--example-<n> pattern.
• Source example content from real repository artifacts such as artifacts/, examples/, generated demo output, or other repository-backed material.
• Run scripts/website-verify.sh --all after adding or changing examples.

Must Not

• Do not reintroduce page-local JavaScript blobs or per-page script tags for interactive examples.
• Do not invent rendered output or source content that is not grounded in the repository.

Where to Get Example Content

Source 1: artifacts/ Directory (Primary)

The artifacts/ directory contains pre-generated markdown and HTML examples from the comprehensive demo:

Markdown Source:

• artifacts/comprehensive-demo.md - Full markdown output
• artifacts/comprehensive-demo-simple-diff.md - Simplified diff format

Rendered HTML:

• artifacts/comprehensive-demo.github.html - GitHub-rendered HTML
• artifacts/comprehensive-demo.azdo.html - Azure DevOps-rendered HTML

How to Extract:

1. Open the markdown file
2. Search for the resource type or feature (e.g., azurerm_firewall_network_rule_collection)
3. Copy the relevant section for the source view
4. Open the corresponding .github.html file
5. Find the matching section for the rendered view
6. Extract the HTML that should appear inside the rendered pane

Source 2: Generate New Examples

If the exact example doesn't exist in artifacts:

1. Run the demo generation script:

   scripts/generate-demo-artifacts.sh

   This regenerates all artifacts from the current codebase.

2. Create custom examples:

   # Create a custom Terraform plan
   cd examples/
   # Modify existing demo or create new scenario
   terraform plan -out=plan.tfplan
   terraform show -json plan.tfplan > plan.json
   
   # Generate markdown
   docker run -v $(pwd):/data oocx/tfplan2md:latest plan.json > output.md

3. Render to HTML: Use the HtmlRenderer tool:

   dotnet run --project src/tools/Oocx.TfPlan2Md.HtmlRenderer \
     --input artifacts/comprehensive-demo.md \
     --output artifacts/custom-example.github.html \
     --platform github

Step-by-Step: Add a New Example

1. Choose the page entrypoint

• Open the relevant page under website/src/pages/
• Existing examples page entrypoint: website/src/pages/examples.njk
• Existing feature detail pages live under website/src/pages/features/

2. Create or update the example directory

• Create or update website/src/examples/<example-id>/
• Add or update meta.json
• Add or update rendered.html
• Add or update source.html

3. Keep the example fragment responsibilities clear

• meta.json holds the example title and metadata used by the renderer
• rendered.html contains the rendered example pane content
• source.html contains the source-pane markup, typically a <pre><code>...</code></pre> block
• Keep the title specific, for example Firewall Network Rule Collection Output

4. Reference the example from the page

• Use the exampleBlock shortcode from the relevant .njk page:

{{ exampleBlock("features--firewall-rules--example-1") | safe }}

• Place it inside the existing page structure and surrounding content blocks
• Reuse existing macros and section patterns from website/src/_includes/components/

5. Verify the rendered result

• Run scripts/website-verify.sh --all
• Preview the relevant page in website/dist/
• Use browser tools to confirm toggle behavior, fullscreen behavior, and responsive layout

Step-by-Step: Update an Existing Example

1. Regenerate artifacts:

   scripts/generate-demo-artifacts.sh

2. Locate the example:
   • Find the exampleBlock("...") call in website/src/pages/
   • Open the matching directory under website/src/examples/
3. Update rendered view:
   • Extract new HTML from regenerated artifacts
   • Replace content in rendered.html
4. Update source view:
   • Extract new markdown from regenerated artifacts
   • Escape HTML characters when needed
   • Replace content in source.html
5. Test:
   • Open the page in a browser preview
   • Toggle between rendered and source views
   • Verify content renders correctly
   • Test fullscreen mode

Content Guidelines

Rendered View Content

• Use semantic HTML: headings, tables, code blocks, details/summary, lists, and other markup that matches the actual rendered output
• Preserve emoji and icons from real tfplan2md output when present
• Keep inline styles only when they are part of the real rendered output
• Do not replace the shared wrapper generated by the shortcode with custom page markup

Source View Content

• Show the exact source content that explains or generates the rendered output
• Escape HTML characters when source is rendered inside <code>
• Preserve whitespace and indentation
• Include markdown, HTML, or mixed source only when that matches the real source material
• This is what users would copy or inspect alongside the rendered result

Title Guidelines

• Be specific: "Firewall Network Rule Collection Output" not "Example Output"
• Describe the resource type or feature shown
• Keep under 60 characters for readability

Common Patterns

Table-Based Examples

Most features show tables. Rendered view has <table>, source view has pipe-separated markdown.

Diff Examples (Firewall/NSG Rules)

Use inline styles for before/after highlighting. Keep all styles in rendered view; show escaped HTML tags in source view.

Module Grouping

Show hierarchical structure with <details> in rendered view; show markdown <details> tags in source view.

Large Values

Show collapsed sections in rendered view; show the markdown collapsible syntax in source view.

Troubleshooting

Toggle buttons don't work

• Check website/src/site-assets/js/site.js and the interactive examples module wiring
• Check browser console for JavaScript errors
• Confirm the page is using the shared base layout and not bypassing the normal site bootstrap

Rendered view looks wrong

• Verify rendered.html is valid and complete
• Check that the page still uses the shared example wrapper emitted by the shortcode
• Ensure shared styles and client-side assets are loading in the rendered page

Source view doesn't highlight

• Verify source.html contains the expected code block structure
• Check that HTML is properly escaped
• Check shared syntax-highlighting behavior in the previewed page

Content overflows

• Use fullscreen mode for large examples
• Consider splitting very large examples into multiple smaller ones
• Ensure tables are not too wide (test on mobile)

Files Modified/Created

When adding examples, these files are typically involved:

• Page entrypoints: website/src/pages/*.njk, website/src/pages/features/*.njk
• Example fragments: website/src/examples/<example-id>/meta.json, rendered.html, source.html
• Shared JavaScript: website/src/site-assets/js/ (rarely modified)
• Source content: artifacts/*.md (regenerated via script)
• Rendered content: artifacts/*.html (regenerated via script)

Validation Checklist

Before committing changes:

• Interactive example has correct HTML structure
• Example is referenced from the correct .njk page using exampleBlock
• Rendered view shows proper HTML output
• Source view shows the correct escaped source when needed
• Title is descriptive and specific
• Toggle between views works
• Fullscreen mode works
• Content renders correctly in both light and dark themes
• Mobile responsive (test narrow viewport)
• No JavaScript console errors

Related Skills

• website-visual-assets - Generate screenshots and HTML exports
• generate-demo-artifacts - Regenerate the comprehensive demo
• website-quality-check - Verify overall website quality