zyros

v2.1.4

Published

a year ago

A developer-friendly static site generator built with Next.js and Tailwind CSS. Transform a simple JSON file into a beautiful, fast static website.

🚀 zyros

⚫ Name changed from Zyros-ssg to Zyros.

A developer-friendly static site generator built with Next.js and Tailwind CSS. Transform a simple JSON file into a beautiful, fast static website with powerful features that developers and content creators love.

npm License

🎉 Recent Improvements (v2.1.4)

Based on valuable community feedback, we've made significant improvements:

✅ Fixed dark theme text visibility - Intelligent color contrast for all themes
✅ Scalable content management - Multi-file markdown support with frontmatter
✅ Enhanced documentation - Clear analytics dashboard access and security guidelines
✅ Backward compatibility - Existing projects continue to work seamlessly
🔄 CLI optimization - Deprecated redundant commands (use npm run dev/build instead)

📋 Coming in v2.1.5: Dependency-based architecture for easy updates and maintenance

DEMO

https://zyros.vercel.app/ Demo

✨ Features

🎯 Core Features

📄 JSON-based content management - Define your entire site in a single JSON file
🎨 13 Beautiful themes - Choose from light, dark, minimal, ocean, sunset, forest, midnight, neon, aurora, autumn, cyberpunk, and sakura themes
📝 Enhanced Markdown support - Write content in Markdown with beautiful rendering and syntax highlighting
⚡ Static generation - Lightning-fast sites with Next.js static export
📱 Responsive design - Mobile-first, beautiful on all devices with smooth animations
🎯 Zero configuration - Works out of the box

🤖 AI-Powered Features

🧠 AI Content Generator - Generate blog posts, landing pages, and content blocks with AI assistance
📊 SEO Analyzer - Real-time SEO analysis with optimization suggestions and scoring
⚡ Performance Dashboard - Monitor Core Web Vitals, Lighthouse scores, and user metrics
🎨 Visual Page Builder - Drag-and-drop page builder for creating pages without code

🔍 Advanced Search & Discovery

🔍 Smart search - Built-in fuzzy search with keyboard shortcuts (⌘+K)
🏷️ Advanced filtering - Filter by categories, tags, and publication date
📊 Search analytics - Track popular search queries and optimize content

🎨 User Experience

🌈 Dynamic theme switcher - Real-time theme switching with local storage persistence
📖 Reading progress - Visual progress bar and reading time estimation
📑 Table of contents - Auto-generated navigation for long articles
📋 Copy code blocks - One-click copying with visual feedback
⌨️ Keyboard navigation - Full keyboard accessibility support
🎭 Smooth animations - Beautiful transitions and micro-interactions

📊 Analytics & Insights

📈 Built-in analytics - Track page views, reading time, and user engagement
🔍 Search analytics - Monitor what users are searching for
🎨 Theme preferences - Understand which themes are most popular
📊 Performance metrics - Monitor scroll depth and content engagement
💾 Privacy-first - All analytics stored locally, no external tracking

Accessing the Analytics Dashboard

Your Zyros site includes a powerful analytics dashboard at /analytics:

Development Mode:

npm run dev
# Visit http://localhost:3000/analytics

Production Mode:

npm run build
npm run start
# Visit http://yoursite.com/analytics

🔒 Security Note: The analytics dashboard is publicly accessible by default. For production sites, consider implementing authentication or restricting access via your hosting provider's settings.

Features include:

Real-time page performance metrics
Search query analytics
Theme preference tracking
Content engagement insights
Data export functionality

🚀 Social & Engagement

📤 Social sharing - Share articles on Twitter, Facebook, LinkedIn with native support
📧 Newsletter subscription - Built-in email collection with local storage
🔗 Copy link sharing - Easy link copying with visual feedback
📱 Mobile sharing - Native mobile sharing API support

🛠️ Developer Tools

🖥️ CLI content management - Create, edit, and manage content from the command line
📊 Content statistics - View detailed stats about your content
🔧 TypeScript support - Full type safety and better developer experience
📦 Plugin-ready architecture - Extensible design for future enhancements
🎨 Template system - Multiple starter templates for different use cases
🔍 Content validation - Validate your content structure and catch errors
🖼️ Image optimization - Automatic image compression and WebP generation
🚀 One-click deployment - Deploy to Vercel, Netlify, GitHub Pages, and more

📊 SEO & Performance

📊 SEO optimized - Automatic meta tags, Open Graph, and structured data
🚀 Performance optimized - Lighthouse scores of 100/100
📱 Mobile-first - Responsive design that works on all devices
🔍 Search engine friendly - Optimized for discoverability
📡 RSS feed generation - Automatic RSS feed for your content
🗺️ Sitemap generation - SEO-friendly sitemaps

🚀 Quick Start

⚡ Recommended: Using npx (No Installation Required)

The easiest and recommended way to get started:

# Create a new project (recommended)
npx zyros@latest init my-blog or zyros init after npm install -g zyros

# Navigate to your project
cd my-blog

# Install dependencies
npm install

# Start development server
npm run dev

Your site will be available at http://localhost:3000!

💡 Why npx? Using npx zyros@latest init ensures you always get the latest version without installing zyros globally.

🌍 Alternative: Global Installation

If you prefer to install zyros globally:

# Install globally
npm install -g zyros

# Create projects anywhere
zyros init my-blog
cd my-blog
npm install
npm run dev

⚠️ Important: Don't Install as Project Dependency

❌ Don't do this:

npm install zyros  # This installs zyros as a dependency, not what you want!

✅ Do this instead:

npx zyros@latest init my-project  # Creates a new project
# OR
npm install -g zyros              # Installs CLI globally

Note: zyros is a CLI tool for creating projects, not a library dependency. If you accidentally run npm install zyros in a project directory, you can safely delete the created package.json and node_modules.

What You Get

When you run npx zyros init, you get a complete copy of the entire zyros project including:

✅ All components - Advanced search, content blocks, forms, layouts (including Layout.tsx)
✅ All themes - 8 beautiful themes ready to use
✅ Demo content - Rich example content to learn from
✅ Full functionality - Analytics, social sharing, newsletter, etc.
✅ Development tools - TypeScript, ESLint, Tailwind CSS configured
✅ Deployment ready - Build scripts and deployment configurations
✅ Production tested - Thoroughly validated and error-free

🛠️ For Contributors & Advanced Users

# Clone for contributing or customization
git clone https://github.com/zyrasoftware/zyros.git
cd zyros
npm install
npm run dev

📁 Project Structure

When you run npx zyros init my-blog, you get the complete project structure:

my-blog/
├── components/            # React components
│   ├── Layout.tsx        # Main layout component
│   ├── ContentBlocks.tsx # Advanced content blocks
│   ├── AdvancedSearch.tsx # Search functionality
│   └── ...               # All other components
├── pages/                # Next.js pages
│   ├── index.tsx         # Homepage
│   ├── [slug].tsx        # Dynamic pages
│   └── analytics.tsx     # Analytics dashboard
├── styles/               # Styling
│   ├── globals.css       # Global styles
│   └── themes.ts         # Theme definitions
├── lib/                  # Utilities
│   ├── contentLoader.ts  # Content loading logic
│   └── analytics.ts      # Analytics functions
├── public/               # Static assets
│   ├── site.json         # Your content and configuration
│   ├── favicon.svg       # Site favicon
│   └── ...               # Other assets
├── types/                # TypeScript definitions
├── scripts/              # Build and utility scripts
├── next.config.ts        # Next.js configuration
├── tailwind.config.js    # Tailwind CSS configuration
├── tsconfig.json         # TypeScript configuration
└── package.json          # Dependencies and scripts

🎨 Themes

Choose from thirteen stunning themes, each with unique color palettes and visual styles:

Available Themes

Light - Clean and bright with excellent readability
Dark - Easy on the eyes with modern dark aesthetics
Minimal - Simple and elegant stone-inspired design
Ocean - Cool and refreshing cyan-blue gradients
Sunset - Warm and vibrant orange-pink tones
Forest - Natural and calming emerald-green palette
Midnight - Deep and mysterious purple-slate combination
Neon - Bold and electric green-on-black cyberpunk style
Aurora - Mystical northern lights with purple-pink gradients
Autumn - Warm amber and orange fall-inspired palette
Cyberpunk - High-contrast cyan and magenta futuristic design
Sakura - Delicate pink cherry blossom aesthetic

Usage

{
  "site": {
    "theme": "ocean"
  }
}

Dynamic Theme Switching

Users can switch themes in real-time using the theme switcher in the header. Theme preferences are automatically saved to local storage.

📝 Content Format

Site Configuration

{
  "site": {
    "title": "Your Site Title",
    "theme": "light",
    "description": "Your site description",
    "author": "Your Name",
    "url": "https://yoursite.com"
  },
  "pages": [
    {
      "title": "Page Title",
      "slug": "url-slug",
      "content": "# Your Markdown Content\n\nWrite your content here...",
      "description": "Page description for SEO",
      "category": "blog",
      "tags": ["tag1", "tag2"],
      "publishedAt": "2024-01-15",
      "readingTime": 5
    }
  ]
}

Markdown Support

zyros supports full Markdown syntax:

Headers (# ## ###)
Bold and italic text
Links
Lists (ordered and unordered)
Code blocks and syntax highlighting
Blockquotes
Tables
Images
And more!

🛠️ CLI Commands

Content Management

# Create a new post
zyros content create

# List all posts
zyros content list

# Delete a post
zyros content delete

# Show content statistics
zyros content stats

Project Management

# Initialize new project
zyros init my-site

# Build for production
zyros build

# Start development server
zyros dev

# Validate content and structure
zyros validate

# Optimize images and assets
zyros optimize

Template Management

# List available templates
zyros template list

# Apply a template
zyros template apply minimal

# Create custom template
zyros template create my-template

Deployment

# Deploy to Vercel
zyros deploy vercel

# Deploy to Netlify
zyros deploy netlify

# Deploy to GitHub Pages
zyros deploy github

# Deploy to AWS S3
zyros deploy s3 my-bucket

Configuration

# Show all configuration
zyros config --list

# Get specific value
zyros config --get site.title

# Set configuration value
zyros config --set site.theme=dark

🎨 Templates

zyros comes with multiple templates for different use cases:

Default - Clean blog template
Portfolio - Showcase your work
Documentation - Technical docs
Business - Professional website
Minimal - Ultra-clean design

# Use a specific template
zyros init my-site --template portfolio

🔧 Advanced Configuration

Custom Themes

Create your own theme by extending the theme system:

{
  "site": {
    "theme": "custom",
    "customTheme": {
      "name": "custom",
      "background": "bg-purple-900",
      "text": "text-white",
      "accent": "text-yellow-400"
    }
  }
}

SEO Configuration

{
  "site": {
    "seo": {
      "keywords": ["blog", "tech", "programming"],
      "ogImage": "/og-image.jpg",
      "twitterCard": "summary_large_image"
    }
  }
}

Analytics Integration

{
  "site": {
    "analytics": {
      "googleAnalytics": "GA_MEASUREMENT_ID",
      "plausible": "domain.com"
    }
  }
}

📊 Scripts

| Command | Description | |---------|-------------| | zyros init <name> | Initialize new project | | zyros dev | Start development server | | zyros build | Build for production | | zyros content create | Create new post | | zyros content list | List all posts | | zyros validate | Validate project | | zyros optimize | Optimize assets | | zyros deploy <platform> | Deploy to platform |

🚀 Deployment

Vercel (Recommended)

npm install -g vercel
zyros deploy vercel --prod

Netlify

npm install -g netlify-cli
zyros deploy netlify --prod

GitHub Pages

zyros deploy github

Manual Deployment

Run zyros build
Upload the dist/ folder to your hosting provider
Configure your server to serve index.html for all routes

🔍 Validation & Optimization

Content Validation

# Validate your content structure
zyros validate

# Check for common issues
# - Missing required fields
# - Duplicate slugs
# - Invalid markdown syntax
# - SEO recommendations

Image Optimization

# Optimize all images
zyros optimize

# Optimize images only
zyros optimize --images

# Generate WebP versions
zyros optimize --webp

📊 Analytics Dashboard

Access your site's analytics to understand your audience:

Page Performance - Views, reading time, engagement
Search Insights - Popular queries and trends
User Behavior - Theme preferences, navigation patterns
Content Analytics - Most popular posts and categories

All analytics are privacy-first and stored locally.

🗺️ Roadmap

✅ Recently Added (v2.1.4)

[x] NPM Package - Install globally or use with npx
[x] CLI Tool - Complete command-line interface with proper termination
[x] Template System - 5 complete starter templates (Default, Portfolio, Documentation, Business, Minimal)
[x] Content Validation - Validate structure and content
[x] Image Optimization - Automatic image processing
[x] One-click Deployment - Deploy to multiple platforms
[x] TypeScript Support - Full type definitions
[x] Enhanced Reliability - Fixed critical file filtering issues
[x] Windows Compatibility - Improved cross-platform support
[x] Command Termination - All CLI commands now properly exit
[x] Complete Template System - All templates working with proper configurations

🚧 Coming Soon (v2.1)

[ ] Plugin System - Extensible architecture
[ ] CMS Integration - Headless CMS support
[ ] Multi-language Support - i18n capabilities
[ ] Advanced SEO - Schema markup, meta optimization
[ ] Performance Monitoring - Real-time metrics
[ ] Comment System - GitHub Issues integration

🔮 Future Plans (v3.0+)

[ ] Visual Editor - WYSIWYG content editing
[ ] Collaboration Tools - Multi-author support
[ ] E-commerce Integration - Product pages
[ ] Advanced Analytics - Detailed insights
[ ] Mobile App - Content management on the go

🤝 Contributing

We welcome contributions! Here's how you can help:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/zyrasoftware/zyros.git
cd zyros

# Install dependencies
npm install

# Start development
npm run dev

# Run tests
npm test

# Build package
npm run build

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with Next.js
Styled with Tailwind CSS
Markdown rendering by react-markdown
CLI powered by Commander.js
Beautiful terminal output with Chalk

📞 Support

#SOON

Made with ❤️ by Zyra Software

Transform your ideas into beautiful static sites with zyros