opentwig 1.0.5 → 1.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,312 @@
+# Contributing to OpenTwig 🌿
+
+Thank you for your interest in contributing to OpenTwig! This guide will help you get started as a contributor to our open source project.
+
+
+## 📋 Table of Contents
+
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [How to Contribute](#how-to-contribute)
+- [Project Structure](#project-structure)
+- [Code Style Guide](#code-style-guide)
+- [Testing](#testing)
+- [Pull Request Process](#pull-request-process)
+- [Reporting Bugs](#reporting-bugs)
+- [Suggesting Features](#suggesting-features)
+- [Community Guidelines](#community-guidelines)
+
+## 🚀 Getting Started
+
+1. **Fork the repository** on GitHub
+2. **Clone your fork** locally:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/opentwig.git
+   cd opentwig
+   ```
+3. **Add upstream remote**:
+   ```bash
+   git remote add upstream https://github.com/tufantunc/opentwig.git
+   ```
+
+## 🛠️ Development Setup
+
+### Prerequisites
+- Node.js (v14 or higher)
+- npm or yarn
+- Git
+
+### Installation
+1. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+2. Test the CLI tool:
+   ```bash
+   npm start -- --help
+   ```
+
+3. Create a test config and try building:
+   ```bash
+   npm start -- --init
+   npm start
+   ```
+
+## 🤝 How to Contribute
+
+### Types of Contributions
+
+We welcome various types of contributions:
+
+#### 🐛 **Bug Fixes**
+- Fix issues labeled `bug`
+- Improve error handling
+- Fix typos in documentation
+
+#### ✨ **New Features**
+- Add new themes
+- Implement new CLI commands
+- Add support for new image formats
+- Enhance existing functionality
+
+#### 📚 **Documentation**
+- Improve README sections
+- Add code comments
+- Create tutorials or guides
+- Translate documentation
+
+#### 🎨 **Themes & Styling**
+- Create new themes
+- Improve existing theme designs
+- Add responsive improvements
+- Fix accessibility issues
+
+#### 🔧 **Development Experience**
+- Add tests
+- Improve build process
+- Add linting/formatting
+- Update dependencies
+
+### Good First Issues
+
+Look for issues with these labels:
+- `good first issue` - Perfect for newcomers
+- `documentation` - Documentation improvements
+- `theme` - Theme-related work
+
+## 📁 Project Structure
+
+```
+opentwig/
+├── src/
+│   ├── index.js              # Main CLI entry point
+│   ├── constants.js          # App constants
+│   └── utils/                # Core utilities
+│       ├── buildPage.js      # Page building logic
+│       ├── generateHTML.js   # HTML generation
+│       ├── generateOGImage.js # Open Graph images
+│       ├── generateQR.js     # QR code generation
+│       ├── processCSS.js     # CSS processing
+│       └── ...
+├── theme/
+│   ├── default/              # Default theme
+│   │   ├── index.js         # Theme template
+│   │   ├── style.css        # Theme styles
+│   │   └── components/      # Reusable components
+│   ├── dark/                # Dark theme
+│   ├── minimal/             # Minimal theme
+│   ├── colorful/            # Colorful theme
+│   └── azure/               # Azure theme
+└── dist/                    # Generated output (gitignored)
+```
+
+### Key Files Explained
+
+- **`src/index.js`**: Main CLI entry point, handles argument parsing
+- **`src/utils/buildPage.js`**: Orchestrates the page building process
+- **`theme/*/index.js`**: Theme-specific HTML templates
+- **`theme/*/style.css`**: Theme-specific CSS styles
+- **`theme/*/components/`**: Reusable component templates
+
+## 💻 Code Style Guide
+
+### JavaScript
+- Use ES6+ features where appropriate
+- Follow camelCase for variables and functions
+- Use meaningful variable names
+- Add JSDoc comments for functions
+- Keep functions small and focused
+
+### CSS
+- Use consistent indentation (2 spaces)
+- Use semantic class names
+- Follow mobile-first responsive design
+- Use CSS custom properties for theming
+- Optimize for performance
+
+### File Organization
+- One function per file when possible
+- Keep utility files focused
+- Use clear, descriptive filenames
+
+### Example Code Style
+
+```javascript
+/**
+ * Generates QR code for the given URL
+ * @param {string} url - The URL to encode
+ * @returns {string} SVG QR code string
+ */
+function generateQRCode(url) {
+  const qrOptions = {
+    type: 'svg',
+    width: 200,
+    margin: 2
+  };
+  
+  return QrCode.generate(url, qrOptions);
+}
+```
+
+## 🧪 Testing
+
+Before submitting a pull request:
+
+1. **Test CLI functionality**:
+   ```bash
+   npm start -- --init
+   npm start
+   ```
+
+2. **Test different themes**:
+   ```bash
+   # Edit config.json to test different themes
+   npm start
+   ```
+
+3. **Check output files**:
+   - Verify HTML is valid
+   - Check CSS renders correctly
+   - Ensure images are processed properly
+
+4. **Test edge cases**:
+   - Empty config
+   - Missing avatar
+   - Long text content
+   - Various image formats
+
+## 📝 Pull Request Process
+
+1. **Create a branch** from main:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes** 
+
+3. **Test thoroughly**
+
+4. **Commit with clear messages**:
+   ```bash
+   git commit -m "feat: add new theme for better UX"
+   git commit -m "docs: improve setup instructions"
+   ```
+
+5. **Push to your fork**:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+6. **Open a Pull Request**
+
+### PR Guidelines
+
+- Use descriptive titles
+- Link related issues
+- Add screenshots for UI changes
+- Describe testing performed
+- Keep PRs focused and small when possible
+
+### PR Title Format
+- `feat:` New features
+- `fix:` Bug fixes  
+- `docs:` Documentation changes
+- `style:` Code style changes
+- `refactor:` Code refactoring
+- `test:` Adding or updating tests
+- `chore:` Maintenance tasks
+
+## 🐛 Reporting Bugs
+
+Found a bug? Help us fix it!
+
+### Before Reporting
+1. Check existing issues
+2. Test with latest version
+3. Try to reproduce consistently
+
+### Bug Report Template
+```markdown
+**Bug Description**
+Brief description of the bug
+
+**Steps to Reproduce**
+1. Run `npx opentwig --init`
+2. Edit config.json with...
+3. Run `npx opentwig`
+4. See error...
+
+**Expected Behavior**
+What should happen instead
+
+**Environment**
+- Node.js version:
+- Operating System:
+- npm version:
+
+**Additional Context**
+Screenshots, error messages, etc.
+```
+
+## 💡 Suggesting Features
+
+We love feature suggestions! 
+
+### Enhancement Guidelines
+1. Check existing issues first
+2. Describe the use case clearly
+3. Consider backward compatibility
+4. Think about implementation complexity
+
+## 🌍 Community Guidelines
+
+### Code of Conduct
+
+- Be respectful and inclusive
+- Welcome newcomers and different skill levels
+- Focus on constructive feedback
+- Respect different opinions and approaches
+
+### Getting Help
+
+- Use GitHub Discussions for questions
+- Check existing issues and PRs
+- Read documentation thoroughly
+- Be patient for responses
+
+## 🎉 Recognition
+
+Contributors will be:
+- Listed in the project README (if desired)
+- Mentioned in release notes for significant contributions
+- Given priority in code reviews and feedback
+
+## 📞 Contact
+
+Questions? Feel free to:
+- Open an issue
+- Start a discussion
+- Contact maintainers
+
+Thank you for contributing to OpenTwig! 🚀

package/README.md

@@ -1,5 +1,13 @@
 # OpenTwig 🌿
 
+[![npm version](https://img.shields.io/npm/v/opentwig.svg)](https://www.npmjs.com/package/opentwig)
+[![npm downloads](https://img.shields.io/npm/dm/opentwig.svg)](https://www.npmjs.com/package/opentwig)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/node/v/opentwig.svg)](https://nodejs.org/)
+[![GitHub stars](https://img.shields.io/github/stars/tufantunc/opentwig.svg)](https://github.com/tufantunc/opentwig/stargazers)
+[![GitHub issues](https://img.shields.io/github/issues/tufantunc/opentwig.svg)](https://github.com/tufantunc/opentwig/issues)
+[![Coverage](https://img.shields.io/badge/Coverage-60%25-yellow)]()
+
 OpenTwig is an open source personal link page generator that creates beautiful, customizable "link in bio" pages. Instead of relying on third-party services, users can define their configuration and instantly create a fully functional static site they own and control.
 
 ## ✨ Features
@@ -27,6 +35,9 @@ npx opentwig --init
 # Edit the generated config.json with your information
 # Then generate your page
 npx opentwig
+
+# Or use live preview with interactive editor
+npx opentwig --live
 ```
 
 ### Prerequisites
@@ -34,6 +45,38 @@ npx opentwig
 - Node.js (v14 or higher)
 - npm or yarn
 
+## 🔥 Live Preview Mode (NEW!)
+
+OpenTwig now includes a powerful live preview mode with an interactive configuration editor!
+
+```bash
+# Start live preview with config editor
+npx opentwig --live
+
+# Or using npm script
+npm run live
+```
+
+**Features:**
+- 🎨 **Interactive Sidebar Editor** - Edit all config options in a beautiful UI
+- 🔄 **Real-time Preview** - See changes instantly as you edit
+- 💾 **Auto-save** - Changes automatically save to config.json
+- 📱 **Responsive Layout** - Preview on the left, editor on the right
+- 🖼️ **Avatar Upload** - Upload and preview avatar images directly
+- 🎭 **Theme Switcher** - Switch between themes instantly
+- 🔗 **Drag & Drop Links** - Easily manage your links
+- 📊 **Status Indicator** - Connection status and auto-save status
+- 📥 **Export Config** - Download your config as JSON
+
+**How it works:**
+1. Run `npx opentwig --live` to start the development server
+2. The browser opens automatically showing your page preview
+3. Use the sidebar editor to modify configuration
+4. Changes are auto-saved to `config.json`
+5. Preview updates in real-time
+6. Press `Ctrl+C` to stop the server
+7. Your `dist/` folder is ready for deployment!
+
 ## 📖 Configuration
 
 OpenTwig uses a simple JSON configuration file (`config.json`) to define your page. Here's the complete configuration structure:
@@ -135,6 +178,7 @@ The avatar feature is completely optional. If you don't include the `avatar` obj
 - PNG
 - JPG/JPEG  
 - WebP
+- SVG
 
 **Avatar processing:**
 - Images are automatically optimized and resized
@@ -158,9 +202,9 @@ The avatar feature is completely optional. If you don't include the `avatar` obj
 OpenTwig includes 4 beautiful themes:
 
 - **Default**: Clean, modern design with subtle shadows and rounded corners
-- **Dark**: Dark mode variant of the default theme
-- **Minimal**: Simplified, minimalist design
-- **Colorful**: Vibrant color scheme
+- **Dark**: Dark mode variant of the default theme with gradient backgrounds and glassmorphism effects
+- **Minimal**: Simplified, minimalist design with flat styling
+- **Colorful**: Vibrant color scheme with animated gradients and shimmer effects
 
 All themes are mobile-responsive and include:
 - Optional custom avatar display
@@ -180,6 +224,12 @@ npx opentwig --init
 
 # Generate page from config.json
 npx opentwig
+
+# Start live preview with config editor
+npx opentwig --live
+
+# Validate config.json
+npx opentwig --validate-config
 ```
 
 ## 📁 Output Files
@@ -194,19 +244,53 @@ OpenTwig generates the following files in the `dist/` directory:
 
 ## 🔧 Development
 
+### Development Setup
+
+If you want to contribute to OpenTwig or customize it locally:
+
+```bash
+# Clone the repository
+git clone https://github.com/tufantunc/opentwig.git
+cd opentwig
+
+# Install dependencies
+npm install
+
+# Test the CLI
+npm start -- --help
+
+# Create a sample config for testing
+npm start -- --init
+
+# Test the build process
+npm start
+
+# Start live preview mode
+npm run live
+```
+
 ### Project Structure
 
 ```
 opentwig/
 ├── src/
-│   ├── index.js              # Main entry point
+│   ├── index.js              # Main CLI entry point
 │   ├── constants.js          # Application constants
-│   └── utils/                # Utility functions
+│   ├── live-ui/             # Live preview UI
+│   │   ├── index.html       # Live editor page
+│   │   ├── styles.css      # Live editor styles
+│   │   ├── preview.js      # Preview management
+│   │   ├── editor.js       # Config editor logic
+│   │   └── sidebar.js     # Sidebar components
+│   └── utils/                # Core utilities
 │       ├── buildPage.js      # Page building logic
 │       ├── generateHTML.js   # HTML generation
 │       ├── generateOGImage.js # Open Graph image creation
 │       ├── generateQR.js     # QR code generation
 │       ├── processCSS.js     # CSS processing and optimization
+│       ├── startLiveServer.js # Live preview server
+│       ├── websocketServer.js # WebSocket handling
+│       ├── setupWatcher.js   # Config file watcher
 │       └── ...
 ├── theme/
 │   ├── default/              # Default theme
@@ -216,7 +300,10 @@ opentwig/
 │   ├── dark/                # Dark theme
 │   ├── minimal/             # Minimal theme
 │   └── colorful/            # Colorful theme
-└── dist/                    # Generated output
+├── .github/                 # GitHub templates
+│   ├── ISSUE_TEMPLATE/      # Issue templates
+│   └── pull_request_template.md # PR template
+└── dist/                    # Generated output (gitignored)
 ```
 
 ### Key Features Implementation
@@ -237,15 +324,92 @@ Since OpenTwig generates static files, you can deploy to any static hosting serv
 - **AWS S3**: Upload files to an S3 bucket
 - **Any web server**: Upload the `dist/` folder to your server
 
+## 🌟 Showcase
+
+Check out these amazing websites created with OpenTwig! These examples showcase sites made with OpenTwig:
+
+### Featured Sites
+
+- **[Tufan Tunç - My Social Links](https://links.tufantunc.com)** - My social links, used default theme with avatar
+
+### Submit Your Site
+
+Have you created a website with OpenTwig? We'd love to showcase it! You can add your site to our showcase in two ways:
+
+1. **Create an Issue** - Use our [showcase submission template](.github/ISSUE_TEMPLATE/showcase_submission.md)
+2. **Submit a Pull Request** - Add your site directly to the showcase section in this README
+
+#### Guidelines for Showcase Submissions
+
+- ✅ Your site must be live and accessible
+- ✅ Use OpenTwig to generate the site
+- ✅ Keep descriptions concise (1-2 sentences max)
+
+#### What We Look For
+
+- Creative use of themes and customization
+- Different use cases (personal, business, portfolio, etc.)
+- Good examples of various configuration options
+- Sites that inspire other users
+
 ## 📝 License
 
 MIT License - see [LICENSE](LICENSE) file for details
 
 ## 🤝 Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+OpenTwig is open source and welcomes contributions from the community! 🎉
+
+### Ways to Contribute
+
+- 🐛 **Report bugs** using our [bug report template](.github/ISSUE_TEMPLATE/bug_report.md)
+- ✨ **Suggest features** through our [feature request template](.github/ISSUE_TEMPLATE/feature_request.md)
+- 📚 **Improve documentation** using our [documentation improvement template](.github/ISSUE_TEMPLATE/documentation_improvement.md)
+- 🌟 **Submit to showcase** using our [showcase submission template](.github/ISSUE_TEMPLATE/showcase_submission.md)
+- 🎨 **Create themes** - add new visual styles and layouts
+- 🔧 **Fix issues** - tackle open issues and improve the codebase
+- 🌍 **Translate** - help translate documentation and content
+
+### Getting Started
+
+1. **Read our [Contributing Guide](CONTRIBUTING.md)** - Complete guide for contributors
+2. **Check our [Code of Conduct](CODE_OF_CONDUCT.md)** - Community guidelines
+3. **Look for `good first issue` labels** - Perfect for newcomers
+4. **Fork, code, and submit a PR** - Standard open source workflow
+
+### Hacktoberfest 2025
+
+🎃 This repository participates in **Hacktoberfest 2025**! 
+
+- Look for issues with `hacktoberfest` and `good first issue` labels
+- Follow our issue and PR templates
+- Make meaningful contributions that benefit the project
+- Review our [Contributing Guide](CONTRIBUTING.md) before starting
+
+### Contributors
+
+We appreciate all contributors! Contributors will be:
+- Listed here (if desired)
+- Mentioned in release notes for significant contributions
+- Given priority for code reviews and feedback
 
 ## 🔗 Links
 
 - [GitHub Repository](https://github.com/tufantunc/opentwig)
 - [NPM Package](https://www.npmjs.com/package/opentwig)
+- [Issues](https://github.com/tufantunc/opentwig/issues)
+- [Discussions](https://github.com/tufantunc/opentwig/discussions)
+
+## 🔧 Config.json Validation
+
+You can validate your configuration file using the CLI option:
+```bash
+npx opentwig --validate-config
+```                                 
+### Available Commands               
+- `--help` - Show usage information  
+- `--init` - Create a sample config.json
+- `--validate-config` - Validate the config.json file
+- `build` - Compile the project files
+- `start` - Run the project
+- `test` - Execute the project tests

package/SECURITY.md

@@ -0,0 +1,56 @@
+# Security Policy
+
+## Supported Versions
+
+Use this section to tell people about which versions of your project are
+currently being supported with security updates.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.0.x   | :white_check_mark: |
+| < 1.0   | :x:                |
+
+## Reporting a Vulnerability
+
+We take the security of OpenTwig seriously. If you discover a security vulnerability, please report it to us responsibly.
+
+### How to Report
+
+Please **do not** create a public GitHub issue for security vulnerabilities. Instead:
+
+1. **Email us directly**: [tufan@tufantunc.com](mailto:tufan@tufantunc.com)
+2. **Subject line**: Include "SECURITY" in the subject
+3. **Include details**:
+   - Description of the vulnerability
+   - Steps to reproduce
+   - Potential impact
+   - Suggested fixes (if any)
+
+### What to Expect
+
+- **Acknowledgement**: We'll acknowledge your report within 48 hours
+- **Assessment**: We'll investigate and assess the vulnerability
+- **Resolution**: We'll work on a fix and keep you updated
+- **Disclosure**: After fixing, we'll coordinate disclosure timing with you
+
+### Security Best Practices
+
+When reporting security issues:
+
+1. **Don't exploit**: Don't attempt to exploit the vulnerability on production systems
+2. **Be responsible**: Give us reasonable time to fix before public disclosure
+3. **Be detailed**: Provide as much detail as possible about the issue
+4. **Be patient**: Complex security issues may take time to properly address
+
+## Security Considerations
+
+OpenTwig is a static site generator, which reduces many security risks. However, please note:
+
+- **Static files**: OpenTwig generates static HTML/CSS files with no server-side processing
+- **Dependencies**: Keep dependencies updated via regular updates
+- **Configuration**: Review configuration files for sensitive information
+- **Assets**: Ensure uploaded images and content don't contain malicious code
+
+## Thank You
+
+We appreciate security researchers helping keep OpenTwig secure. Contributors who report valid security vulnerabilities will be acknowledged in our security advisories (unless they prefer to remain anonymous).