|
| 1 | +# AI-friendly Static Landing Page Generator & Styleguide |
| 2 | + |
| 3 | +[](https://github.com/dx-tooling/landingpages-ai-template/actions/workflows/tests.yml) |
| 4 | +[](https://github.com/dx-tooling/landingpages-ai-template/actions/workflows/code-quality.yml) |
| 5 | + |
| 6 | +This project provides a modern template and styleguide for building static marketing and product landing pages. It combines a pre-configured development environment with a set of reusable components, designed to be easily extended either manually or, ideally, through AI coding assistants like Cursor or Windsurf. |
| 7 | + |
| 8 | +Essentially, it's a *text-to-landingpage* starter kit. Just open the project in your AI coding assistant, provide the necessary context (like the styleguide), and instruct the AI to build your landing pages. |
| 9 | + |
| 10 | +**The Goal:** Bridge the gap between the ease of AI-driven development ("text-to-landingpage") and the need for full control over clean, static, zero-dependency HTML/CSS/JS output. |
| 11 | + |
| 12 | +**Who is this for?** |
| 13 | +* Developers, marketers, or designers who want to quickly generate landing pages using AI tools. |
| 14 | +* Users who value having complete control over the final static code output. |
| 15 | +* Individuals comfortable with basic command-line operations (Node.js, npm) but not necessarily deep web development experts. |
| 16 | + |
| 17 | +**What you get:** |
| 18 | +* A ready-to-use development environment. |
| 19 | +* Clean, static HTML/CSS/JS output suitable for any static hosting provider (Netlify, Vercel, GitHub Pages, S3, etc.). You manage your own hosting. |
| 20 | +* A workflow optimized for AI coding assistants. |
| 21 | + |
| 22 | +## Key Features |
| 23 | + |
| 24 | +* **Modern Tooling:** Built with TypeScript, Webpack 5, Tailwind CSS v4, and PostCSS. |
| 25 | +* **Living Styleguide:** (`src/styleguide/index.html`) Demonstrates available components and styles for easy reference (and for instructing AI). |
| 26 | +* **Example Landing Page:** (`src/example-page/index.html`) A practical example built using the styleguide components. |
| 27 | +* **Stimulus JS:** For lightweight JavaScript interactivity (e.g., modals, theme toggle). |
| 28 | +* **Dark/Light Mode:** Built-in theme toggling based on user preference and localStorage, with FOUC prevention. |
| 29 | +* **HTML Partials:** Uses `<include>` tags (`posthtml-include`) for reusable HTML snippets (like headers, footers, theme guard). |
| 30 | +* **Quality Control:** Pre-configured ESLint, Prettier, and TypeScript checking (`npm run quality`). |
| 31 | +* **Testing:** Jest setup for unit/integration tests (primarily for Stimulus controllers). |
| 32 | +* **Optimized Build:** Development (`npm run build`) and production (`npm run build:prod`) builds configured. |
| 33 | + |
| 34 | +## Getting Started |
| 35 | + |
| 36 | +1. **Clone the Repository:** |
| 37 | + ```bash |
| 38 | + git clone https://github.com/dx-tooling/landingpages-ai-template.git |
| 39 | + cd landingpages-ai-template |
| 40 | + ``` |
| 41 | +2. **Set Up Node.js:** This project uses a specific Node.js version defined in `.nvmrc`. Use Node Version Manager (`nvm`) to ensure compatibility: |
| 42 | + ```bash |
| 43 | + # Installs the correct Node.js version if you don't have it |
| 44 | + nvm install |
| 45 | + # Activates the correct Node.js version for your current shell session |
| 46 | + nvm use |
| 47 | + ``` |
| 48 | + *(You'll need to run `nvm use` in each new terminal session you open for this project).* |
| 49 | +3. **Install Dependencies:** Install the necessary development tools. We use `--no-save` because this is a template; you'll manage your own dependencies if you fork or customize significantly. |
| 50 | + ```bash |
| 51 | + npm install --no-save |
| 52 | + ``` |
| 53 | + |
| 54 | +## Development Workflows |
| 55 | + |
| 56 | +### 1. AI-Assisted Development (Recommended) |
| 57 | + |
| 58 | +This project is designed to work seamlessly with AI coding assistants like **Cursor** or **Windsurf** in their "Agent" or chat modes. |
| 59 | + |
| 60 | +1. **Open the Project:** Open the *entire project root folder* in your AI-powered IDE (e.g., Cursor). |
| 61 | +2. **Provide Context:** Make sure the AI has access to the relevant files, especially: |
| 62 | + * `src/styleguide/index.html` (to see available components) |
| 63 | + * `src/example-page/index.html` (as an example of composition) |
| 64 | + * `.cursorrules` or this `README.md` (for instructions) |
| 65 | + * Any specific controllers (`src/controllers/`) or CSS (`src/styles/`) if relevant. |
| 66 | +3. **Instruct the AI:** Ask the AI to create or modify landing pages. Be specific! |
| 67 | + * **Example Snippets:** *(Combine these ideas into a full prompt)* |
| 68 | + * *File Creation:* "Create a new landing page file at `src/my-new-page/index.html`." |
| 69 | + * *Using Components:* "Use the hero section component from the styleguide, but change the headline text to 'My Awesome Product'." |
| 70 | + * *Composition:* "Then, add the three-column feature section below it, using icons relevant to speed, security, and ease of use." |
| 71 | + * *Verification:* "After making the changes, run `nvm use && npm run quality` in the terminal to check for linting errors, type errors, and test failures. Fix any errors reported." |
| 72 | + * *Building:* "Run `nvm use && npm run build` to create a development build in the `dist/` folder." (Or use `npm run build:prod` for production). |
| 73 | + * *Inventing Components:* "Create a new two-column section with an image on the left and text on the right, following the styling patterns in the styleguide." |
| 74 | + |
| 75 | + **Complete Example Prompt #1 (High-Level):** |
| 76 | + |
| 77 | + ```text |
| 78 | + I need a new landing page for my 'Expert Project Management' workshops. |
| 79 | +
|
| 80 | + 1. **Create File:** Create the page at `src/expert-pm-workshop/index.html`. |
| 81 | + 2. **Content Goal:** The page should promote the workshops, highlighting these key advantages: [Explain Advantage X], [Explain Advantage Y], and [Explain Advantage Z]. Include a way for users to get in touch via email (you can model this after the email form/CTA in the example page). |
| 82 | + 3. **Design Inspiration:** Use the components and styling available in the Living Styleguide (`src/styleguide/index.html`). Feel free to draw inspiration from the structure and layout of the example page (`src/example-page/index.html`), but adapt it to fit the workshop content. |
| 83 | + 4. **Technical Setup:** Ensure the basic HTML structure is correct, including the theme FOUC guard partial in the head. |
| 84 | + 5. **Verify:** After creating the page, run `nvm use && npm run quality`. Fix any reported errors. |
| 85 | + 6. **Build:** Once verification passes, run `nvm use && npm run build`. |
| 86 | +
|
| 87 | + Let me know when it's ready or if you encounter issues. |
| 88 | + ``` |
| 89 | +
|
| 90 | + **Complete Example Prompt #2 (Specific Steps):** |
| 91 | +
|
| 92 | + ```text |
| 93 | + Okay, let's build a new landing page. Please follow these steps precisely: |
| 94 | +
|
| 95 | + 1. **Create File:** Create a new HTML file at `src/my-product-page/index.html`. |
| 96 | + 2. **Basic Structure:** Set up the basic HTML structure (<html>, <head>, <body>) like in `src/styleguide/index.html`, including the `<title>`, `<meta>` tags (adjust content appropriately), and the `<include src="partials/theme-fouc-guard.html"></include>` in the head. |
| 97 | + 3. **Add Header:** Include the theme toggle header component as seen in the styleguide. |
| 98 | + 4. **Add Hero Section:** Copy the "Hero Effects Example 1" section from `src/styleguide/index.html`. Change the main headline (`h1`) text to "Introducing Product X". Change the sub-headline (`h2`) text to "The Solution You Need". Update the paragraph text to describe Product X briefly. Change the CTA button text to "Get Early Access". |
| 99 | + 5. **Add Features Section:** Copy the three-column "Features Section Example (Grid)" from the styleguide below the hero section. Update the icons and text for the three features to be relevant to Product X (e.g., Feature 1: Blazing Speed, Feature 2: Rock-Solid Security, Feature 3: Unmatched Simplicity). |
| 100 | + 6. **Add CTA Section:** Copy the "Email Capture CTA Section" from the styleguide below the features section. |
| 101 | + 7. **Add Footer:** Add a simple footer with a copyright notice for "Product X". |
| 102 | + 8. **Verify:** After creating the file and adding the content, run the command `nvm use && npm run quality` in the terminal. Report any errors found and fix them. |
| 103 | + 9. **Build:** If verification passes, run `nvm use && npm run build` to generate the development build. |
| 104 | +
|
| 105 | + Ensure all copied components use the correct CSS classes as defined in the styleguide and the overall structure is valid HTML5. |
| 106 | + ``` |
| 107 | +
|
| 108 | +**Why `nvm use` before `npm` commands?** The project's build tools and linters might depend on the specific Node.js version defined in `.nvmrc`. Running `nvm use` ensures the correct version is active before executing `npm` scripts. |
| 109 | +
|
| 110 | +### 2. Manual Development |
| 111 | +
|
| 112 | +You can also work conventionally: |
| 113 | +
|
| 114 | +1. **Create/Edit HTML:** Add or modify `.html` files within the `src/` directory (but outside `src/partials/`). Webpack automatically finds and processes these. |
| 115 | +2. **Use Partials:** Use `<include src="partials/your-partial.html"></include>` within your HTML files to reuse common elements. |
| 116 | +3. **Add Styles:** Use Tailwind CSS utility classes directly in your HTML. Add custom CSS to `src/styles/main.css` if needed. |
| 117 | +4. **Add Interactivity:** Create new Stimulus controllers in `src/controllers/` following the naming convention (e.g., `src/controllers/signup_form_controller.ts` becomes `data-controller="signup-form"`). |
| 118 | +5. **Build:** Run `nvm use && npm run build` (for development) or `nvm use && npm run build:prod` (for production). The output goes to the `dist/` folder, mirroring the `src/` structure. |
| 119 | +
|
| 120 | +## Available `npm` Scripts |
| 121 | +
|
| 122 | +*(Always run `nvm use` in your terminal session before these commands)* |
| 123 | +
|
| 124 | +* `npm run build`: Creates a development build in `dist/` (includes source maps). |
| 125 | +* `npm run build:prod`: Creates an optimized production build in `dist/` (minified, no source maps, content hashes in filenames). |
| 126 | +* `npm run quality`: Runs Prettier formatting check, ESLint, TypeScript type checking, and Jest tests. |
| 127 | +* `npm test`: Runs Jest unit tests. |
| 128 | +* `npm run lint`: Runs ESLint and TypeScript type checking. |
| 129 | +* `npm run lint:eslint`: Runs ESLint only. |
| 130 | +* `npm run lint:types`: Runs TypeScript type checking (`tsc --noEmit`) only. |
| 131 | +* `npm run prettier:fix`: Formats code using Prettier. |
| 132 | +
|
| 133 | +## Project Structure |
| 134 | +
|
| 135 | +* `src/`: All source files. |
| 136 | + * `controllers/`: Stimulus JavaScript controllers (TypeScript). |
| 137 | + * `partials/`: Reusable HTML partials included via `<include>`. |
| 138 | + * `static/`: Static assets (like images) that are copied to the build output. |
| 139 | + * `styles/`: Source CSS files (e.g., `main.css` for Tailwind imports/directives). |
| 140 | + * `types/`: Custom TypeScript type definitions (e.g., `global.d.ts`). |
| 141 | + * `*.html`: Your landing page source files (processed by Webpack). |
| 142 | + * `index.ts`: Main JavaScript entry point (initializes Stimulus). |
| 143 | +* `dist/`: Compiled static output (generated by `npm run build`/`build:prod`). **Do not edit files here directly.** |
| 144 | +* `tests/`: Jest test files. |
| 145 | +* **Root:** Configuration files (`webpack.config.js`, `package.json`, `tailwind.config.js`, etc.). |
| 146 | +
|
| 147 | +## Technologies Used |
| 148 | +
|
| 149 | +* HTML |
| 150 | +* Tailwind CSS v4 |
| 151 | +* TypeScript |
| 152 | +* Stimulus.js |
| 153 | +* Webpack 5 |
| 154 | +* PostCSS |
| 155 | +* ESLint |
| 156 | +* Prettier |
| 157 | +* Jest |
| 158 | +
|
| 159 | +## License |
| 160 | +
|
| 161 | +This project is licensed under the MIT License. See the LICENSE.txt file for details. |
0 commit comments