setup-parallax

name	setup-parallax
description	Scaffold a complete CSS 3D parallax hero for MkDocs Material from scratch — home.html, home.css, and mkdocs.yml.
version	0.1.0
triggers	["when the user wants to add a parallax hero to their MkDocs site","when the user asks to set up the parallax from scratch","when the user has AVIF layer files and wants them wired up"]
inputs	[{"name":"hero_headline","type":"string","required":true,"description":"The H1 text shown in the hero"},{"name":"hero_subtext","type":"string","required":false,"description":"The paragraph text below the headline"},{"name":"primary_button_label","type":"string","required":false,"description":"Label for the primary CTA button (default \"Get started\")"},{"name":"primary_button_href","type":"string","required":false,"description":"URL for the primary button (default \"getting-started/\")"},{"name":"layer_files","type":"list","required":false,"description":"List of AVIF filenames in docs/assets/hero/ (agent will detect if not provided)"}]
outputs	["docs/overrides/home.html with correct layer <picture> elements","docs/assets/stylesheets/home.css with full parallax CSS","mkdocs.yml updated with custom_dir and extra_css"]
constraints	["must not overwrite existing home.html without user confirmation","layer filenames must match actual files in docs/assets/hero/","must run mkdocs build after writing files and confirm no errors"]

setup-parallax

Scaffold the complete CSS 3D perspective parallax hero for a MkDocs Material site.

1. Purpose

Wire up layered AVIF images into a working parallax hero using the exact CSS 3D perspective approach from squidfunk/mkdocs-material (MIT). No JS required beyond what the Material theme already ships.

2. Instructions

1. Detect layer files — if layer_files was not provided, list docs/assets/hero/*.avif. Report what was found and ask the user to confirm before proceeding.

2. Assign depths — use the following defaults based on filename sort order (lowest number = furthest back):

   Position	Depth	--md-image-position
   First (far bg)	8	70%
   Second	5	25%
   Third	2	40%
   Fourth (fg)	1	50%

   If there are fewer or more than 4 layers, adjust the depth spread evenly.

3. Write docs/overrides/home.html — use the template:

   {% extends "base.html" %}
   {% block tabs %}
     {{ super() }}
     <style>
       .md-header{position:initial}
       .md-main__inner{margin:0}
       .md-content{display:none}
       @media screen and (min-width:60em){.md-sidebar--secondary{display:none}}
       @media screen and (min-width:){{:none}}
     
     
       
         
         
         
           
             
               
                 {{ hero_headline }}
                 {{ hero_subtext }}
                 {{ primary_button_label }}
                 Learn more
               
               
                 
               
             
           
         
       
       
         
           {{ page.content }}
         
       
     
   {% endblock %}
   {% block content %}{% endblock %}
   {% block footer %}{% endblock %}