whyml

Getting Started with WhyML

Overview

WhyML is a powerful Python package that transforms YAML manifests into multiple output formats including HTML, React, Vue, and PHP. This guide will help you get started quickly with WhyML.

Installation

From PyPI (Recommended)

pip install whyml

From Source

git clone https://github.com/dynapsys/whyml.git
cd whyml
pip install -e .

Development Installation

git clone https://github.com/dynapsys/whyml.git
cd whyml
pip install -e ".[dev]"

Quick Start

1. Basic YAML to HTML Conversion

Create a simple manifest file example.yaml:

metadata:
  title: "My First Page"
  description: "Learning WhyML basics"

styles:
  body:
    font-family: "Arial, sans-serif"
    margin: "0"
    padding: "20px"

structure:
  html:
    children:
      - head:
          children:
            - title:
                text: ""
      - body:
          children:
            - h1:
                text: "Welcome to "
            - p:
                text: ""

Convert to HTML:

whyml convert --from example.yaml --to example.html --as html

2. Web Scraping to YAML

Scrape an existing website and convert it to a YAML manifest:

whyml scrape https://example.com --output scraped.yaml --simplify-structure

3. Multi-format Conversion

Convert your YAML manifest to different formats:

# Convert to React component
whyml convert --from example.yaml --to Example.tsx --as react

# Convert to Vue component
whyml convert --from example.yaml --to Example.vue --as vue

# Convert to PHP component
whyml convert --from example.yaml --to Example.php --as php

🚀 Quick Start with Scripts

The easiest way to get started is using our provided scripts:

# Run the complete Example 1 workflow
./scripts/examples/run-example-1.sh

# Or run all examples at once
./scripts/run-all-examples.sh

These scripts will:

• ✅ Check your installation
• ✅ Use correct CLI syntax
• ✅ Generate all output formats
• ✅ Show you the results

Core Concepts

YAML Manifest Structure

A WhyML manifest consists of several key sections:

• metadata: Basic information about the component
• variables: Template variables for dynamic content
• styles: CSS styling definitions
• structure: HTML structure definition
• imports: External CSS/JS dependencies
• interactions: Event handlers and dynamic behavior

Template Variables

Use `` syntax to insert dynamic content:

variables:
  site_name: "My Website"
  primary_color: "#007bff"

structure:
  h1:
    text: "Welcome to "
    style: "color: "

Inheritance and Dependencies

WhyML supports template inheritance for reusable components:

extends: "base-template.yaml"

metadata:
  title: "Child Page"

# Override or extend parent template

Next Steps

• CLI Reference - Complete command-line interface documentation
• Advanced Scraping - Advanced web scraping features
• Manifest Reference - Complete YAML manifest specification
• Converters Guide - Detailed converter documentation
• API Reference - Python API documentation

Examples

Check out the examples directory for complete working examples:

• Basic Example - Complete scraping and regeneration workflow
• Advanced Scraping Examples - Complex scraping scenarios

Troubleshooting

For common issues and solutions, see our Troubleshooting Guide.

Contributing

See our Contributing Guide for information on how to contribute to WhyML.

This site is open source. Improve this page.