release

docs/getting-started.md

@@ -0,0 +1,213 @@
+# Getting Started with Blueprint
+
+## Installation
+
+1. Clone the repository:
+```bash
+git clone https://github.com/yourusername/blueprint.git
+cd blueprint
+```
+
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. Create your first Blueprint file:
+```bash
+mkdir src
+touch src/index.bp
+```
+
+## Basic Usage
+
+Blueprint uses a declarative syntax to define UI components. Each file with a `.bp` extension will be compiled into HTML and CSS.
+
+### Basic Structure
+
+A Blueprint file consists of elements, which can have properties and children. Properties can be flags or key-value pairs:
+
+```blueprint
+element(flag1, key:value) {
+    child-element {
+        // Content
+    }
+}
+```
+
+### Property Types
+
+Blueprint supports several types of properties:
+
+1. **Flag Properties**
+   ```blueprint
+   button(bold, centered) { "Text" }
+   ```
+
+2. **Key-Value Properties**
+   ```blueprint
+   input(type:email, placeholder:"Enter email")
+   ```
+
+3. **Numeric Properties**
+   ```blueprint
+   section(width:80, padding:20)
+   ```
+
+4. **Color Properties**
+   ```blueprint
+   text(color:#ff0000) { "Red text" }
+   ```
+
+### Page Configuration
+
+Every Blueprint page can have metadata defined using the `page` element:
+
+```blueprint
+page {
+    title { "My Page Title" }
+    description { "Page description for SEO" }
+    keywords { "keyword1, keyword2, keyword3" }
+    author { "Author Name" }
+    meta-viewport { "width=device-width, initial-scale=1" }
+}
+```
+
+Available page metadata:
+- `title`: Page title (appears in browser tab)
+- `description`: Meta description for SEO
+- `keywords`: Meta keywords for SEO
+- `author`: Page author
+- `meta-*`: Custom meta tags (e.g., meta-viewport, meta-robots)
+
+### Basic Layout
+
+A typical page structure:
+
+```blueprint
+page {
+    title { "My First Page" }
+    description { "A simple Blueprint page" }
+    meta-viewport { "width=device-width, initial-scale=1" }
+}
+
+navbar {
+    horizontal(spaced) {
+        text(bold) { "My App" }
+        links {
+            link(href:/) { "Home" }
+            link(href:/about) { "About" }
+            link(href:/contact) { "Contact" }
+        }
+    }
+}
+
+section(wide, centered) {
+    vertical(gap:2) {
+        title(huge) { "Welcome to Blueprint" }
+        text(subtle) { "Start building beautiful UIs with Blueprint" }
+        
+        horizontal(centered, gap:2) {
+            button { "Get Started" }
+            button-light { "Learn More" }
+        }
+    }
+}
+
+section(wide) {
+    grid(columns:3) {
+        card {
+            title { "Feature 1" }
+            text { "Description of feature 1" }
+            button-secondary { "Learn More" }
+        }
+        card {
+            title { "Feature 2" }
+            text { "Description of feature 2" }
+            button-secondary { "Learn More" }
+        }
+        card {
+            title { "Feature 3" }
+            text { "Description of feature 3" }
+            button-secondary { "Learn More" }
+        }
+    }
+}
+```
+
+## Project Structure
+
+A typical Blueprint project has the following structure:
+
+```
+my-blueprint-project/
+├── src/                  # Source Blueprint files
+│   ├── index.bp         # Main page
+│   ├── about.bp         # About page
+│   └── contact.bp       # Contact page
+├── public/              # Static assets
+│   ├── images/          # Image files
+│   ├── fonts/           # Font files
+│   └── favicon.ico      # Favicon
+├── dist/                # Generated files (auto-generated)
+│   ├── index.html       # Compiled HTML
+│   ├── index.css        # Generated CSS
+│   └── ...
+└── package.json         # Project configuration
+```
+
+## Error Handling
+
+Blueprint provides helpful error messages when something goes wrong:
+
+```
+BlueprintError at line 5, column 10:
+Unknown element type: invalid-element
+```
+
+Common errors include:
+- Missing closing braces
+- Unknown element types
+- Invalid property values
+- Unterminated strings
+- Missing required properties
+- Invalid color values
+- Invalid numeric values
+
+## Best Practices
+
+1. **Organization**
+   - Group related elements logically
+   - Use consistent spacing and indentation
+   - Keep files focused on a single purpose
+   - Split large files into components
+
+2. **Naming**
+   - Use descriptive names for links and sections
+   - Follow a consistent naming convention
+   - Use semantic element names
+
+3. **Layout**
+   - Use semantic elements (`section`, `navbar`, etc.)
+   - Leverage the grid system for responsive layouts
+   - Use appropriate spacing with `gap` property
+   - Use `width` and `padding` for fine-tuned control
+
+4. **Styling**
+   - Use predefined style properties when possible
+   - Group related styles together
+   - Keep styling consistent across pages
+   - Use custom properties sparingly
+
+5. **Performance**
+   - Keep files small and focused
+   - Use appropriate image formats and sizes
+   - Minimize custom styles
+   - Leverage built-in responsive features
+
+## Next Steps
+
+- Explore available [components](components.md)
+- Learn about [styling](styling.md)
+- Check out [examples](examples.md)
+- Read about advanced features in the component documentation