Website Create Examples

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