stussy

A powerful and user-friendly static site generator that converts Markdown files into beautiful websites with advanced features.

✨ Features

Core Features

• 📝 Write content in Markdown (simple format)
• 📄 Static Pages support (About, Contact, etc.)
• 🏷️ Tags and Categories system
• 🎨 Customizable templates
• ⚡ Fast and lightweight
• 🚀 Easy to use, even for beginners
• 🔄 Built-in development server with auto-reload

Advanced Features

• 🔗 Social Links integration (GitHub, Twitter, LinkedIn, etc.)
• 📡 RSS Feed generation
• 🎯 SEO Optimized with Open Graph and Twitter Cards
• 🖼️ Featured Images support for posts and pages
• 📊 Blog Archive with organized post history
• 🏗️ Navigable Menu with custom pages
• 📱 Fully Responsive design
• 🌙 Dark Mode support

🍴 Fork this project

git clone https://github.com/scobru/stussy.git
cd stussy

📦 Installation

Step 1: Install Node.js

If you don't have Node.js installed, download it from nodejs.org

Step 2: Install dependencies

Open terminal in this folder and run:

npm install

or with yarn:

yarn install

🚀 How to Use

1. Create Blog Posts

Your blog posts go in the content/ folder. Create .md (Markdown) files:

Example: content/my-first-post.md

---
title: My First Post
date: 2025-01-21
author: Your Name
description: A brief description of the post
category: Tutorial
tags: [markdown, blog, tutorial]
image: /images/my-post.jpg
---

# Welcome!

This is my **first post** using STUSSY.

## What can I do?

- Write normal text
- Use **bold** and _italic_
- Create lists
- Add links: [Example](https://example.com)
- And much more!

2. Create Static Pages

Create static pages (like About, Contact) in the pages/ folder:

Example: pages/about.md

---
title: About
description: Learn more about us
---

# About Us

This is a static page that will be accessible at /about/

3. Configure Your Site

Edit config.json to customize your site:

{
  "siteName": "🍵 STUSSY",
  "siteUrl": "https://stussy.shogun-eco.xyz",
  "author": "Your Name",
  "description": "Official website description",
  "postsPerPage": 10,
  "language": "en",
  "dateFormat": "dd/MM/yyyy",
  "navigation": [
    { "title": "Home", "url": "/" },
    { "title": "About", "url": "/about/" },
    { "title": "Blog", "url": "/blog/" }
  ],
  "socialLinks": {
    "github": "https://github.com/yourusername",
    "twitter": "https://twitter.com/yourusername",
    "linkedin": "https://linkedin.com/in/yourusername",
    "email": "mailto:your@email.com"
  },
  "seo": {
    "enableOpenGraph": true,
    "enableTwitterCards": true,
    "defaultImage": "/og-image.jpg",
    "twitterHandle": "@yourusername"
  },
  "features": {
    "enableRSS": true,
    "enableTags": true,
    "enableCategories": true,
    "enableSearch": false,
    "enableSidebar": true,
    "enableComments": false
  },
  "footer": {
    "showSocialLinks": true,
    "customText": "Made with love using Shogun STUSSY"
  }
}

4. Build the site

Windows:

build.bat

Linux/Mac:

npm run build

The site will be created in the public/ folder

5. View the site

Windows:

serve.bat

Linux/Mac:

npm run serve

Open browser at http://localhost:3000

6. Development Mode (recommended)

Windows:

dev.bat

Linux/Mac:

npm run dev

This command:

• Builds the site
• Starts local server
• The site will update automatically when you modify files!

7. Create a new post quickly

Windows:

new-post.bat

Linux/Mac:

npm run new

Follow the instructions to create a new guided post.

📁 Project Structure

stussy/
├── content/              ← Your blog posts (Markdown files)
│   ├── post-1.md
│   └── post-2.md
├── pages/                ← Static pages (About, Contact, etc.)
│   ├── about.md
│   └── contact.md
├── templates/            ← HTML templates
│   ├── themes/           ← Theme templates
│   │   ├── default/      ← Default theme
│   │   ├── minimal/      ← Minimal theme
│   │   ├── dark/         ← Dark theme
│   │   └── colorful/     ← Colorful theme
│   ├── layout.html       ← Fallback layout
│   ├── post.html         ← Fallback post template
│   └── ...               ← Other fallback templates
├── static/               ← Static files (CSS, images, etc.)
│   ├── themes/           ← Theme CSS files
│   │   ├── default.css
│   │   ├── minimal.css
│   │   ├── dark.css
│   │   └── colorful.css
│   └── style.css         ← Fallback CSS
├── public/               ← Generated site (don't modify)
├── src/                  ← Generator code
│   ├── index.js          ← Main generator
│   ├── server.js         ← Development server
│   └── new-post.js       ← Post creation script
└── config.json           ← Site configuration

🎨 Themes

STUSSY comes with 4 beautiful themes ready to use:

Available Themes

1. default - Modern and clean design with soft colors

   • Clean typography
   • Responsive layout
   • Auto dark mode support
   • Professional look

2. minimal - Ultra-minimalist and elegant

   • Serif typography (Georgia)
   • Minimal colors and borders
   • Perfect for writers and bloggers
   • Maximum focus on content

3. dark - Modern dark theme with neon accents

   • JetBrains Mono font
   • Neon green accents
   • Perfect for tech blogs
   • Eye-friendly dark design

4. colorful - Vibrant and playful with gradients

   • Colorful gradients
   • Modern card design
   • Perfect for creative content
   • Energetic and fun

How to Change Theme

Edit config.json:

{
  "theme": {
    "name": "dark",        // Choose: default, minimal, dark, colorful
    "customCSS": ""        // Optional: path to additional CSS file
  }
}

Creating Custom Themes

You can create your own theme:

1. Create a new folder in templates/themes/your-theme/
2. Copy template files from an existing theme
3. Create static/themes/your-theme.css
4. Set "name": "your-theme" in config.json

Template files needed:

• layout.html - Main page layout
• index.html - Homepage template
• post.html - Blog post template
• page.html - Static page template
• archive.html - Archive page template
• tag.html - Tag page template
• category.html - Category page template

Customizing Existing Themes

You can customize any theme by adding a custom CSS file:

{
  "theme": {
    "name": "dark",
    "customCSS": "/custom-styles.css"
  }
}

Place your custom-styles.css in the static/ folder.

📝 Frontmatter Options

For Blog Posts (content/)

---
title: Post Title              # Required
date: 2025-01-21              # Required
author: Author Name           # Optional
description: Post description # Optional (used in SEO)
category: Category Name       # Optional
tags: [tag1, tag2, tag3]      # Optional
image: /images/post.jpg       # Optional (featured image)
---

For Static Pages (pages/)

---
title: Page Title             # Required
description: Page description # Optional
image: /images/page.jpg       # Optional
---

🌟 Advanced Features

Tags and Categories

Organize your content with tags and categories:

1. Add tags and categories in your post frontmatter
2. Tag pages are automatically generated at /tags/{tag-name}/
3. Category pages at /categories/{category-name}/
4. Tags and categories appear in post metadata

Social Links

Add your social media links in config.json:

"socialLinks": {
  "github": "https://github.com/yourusername",
  "twitter": "https://twitter.com/yourusername",
  "linkedin": "https://linkedin.com/in/yourusername",
  "email": "mailto:your@email.com",
  "facebook": "https://facebook.com/yourusername",
  "instagram": "https://instagram.com/yourusername",
  "youtube": "https://youtube.com/@yourusername"
}

RSS Feed

Automatically generated at /feed.xml when enableRSS: true.

Readers can subscribe to your blog using any RSS reader.

SEO Optimization

STUSSY includes built-in SEO features:

• Meta Tags: Automatic title and description tags
• Open Graph: For social media sharing (Facebook, LinkedIn)
• Twitter Cards: Enhanced Twitter previews
• Sitemap: Automatic generation (coming soon)
• Canonical URLs: Prevent duplicate content issues

Navigation Menu

Customize your navigation in config.json:

"navigation": [
  { "title": "Home", "url": "/" },
  { "title": "About", "url": "/about/" },
  { "title": "Blog Archive", "url": "/blog/" },
  { "title": "Contact", "url": "/contact/" }
]

Blog Archive

Access all your posts organized by date at /blog/

Featured Images

Add images to your posts and pages:

---
image: /images/my-image.jpg
---

Images are displayed:

• As thumbnails in post previews
• As featured images in full posts
• In social media previews (Open Graph, Twitter Cards)

📝 Markdown Syntax - Quick Guide

# Heading 1
## Heading 2
### Heading 3

**Bold**
_Italic_
~~Strikethrough~~

- Bullet point 1
- Bullet point 2

1. Numbered list 1
2. Numbered list 2

[Link text](https://example.com)

![Alt text for image](image.jpg)

> Quote

`inline code`

\`\`\`
Code block
\`\`\`

🚢 Publishing

After running npm run build, the public/ folder contains your ready-to-publish site.

You can publish it on:

• GitHub Pages (free) - Guide
• Netlify (free) - Guide
• Vercel (free) - Guide
• Cloudflare Pages (free) - Guide
• Any web hosting

Just upload the contents of the public/ folder.

Quick Deploy to Vercel

1. Install Vercel CLI: npm i -g vercel
2. Run: vercel --prod
3. Done! Your site is live.

Quick Deploy to Netlify

1. Install Netlify CLI: npm i -g netlify-cli
2. Run: netlify deploy --prod --dir=public
3. Done! Your site is live.

🆘 Common Issues

npm command doesn't work

Make sure you have Node.js installed from nodejs.org

Site doesn't update

1. Stop the server (Ctrl+C)
2. Run npm run build again
3. Restart the server with npm run serve

Styles don't show

Check that the static/style.css file exists and is being copied to public/

Pages not generating

Make sure:

• Your .md files have proper frontmatter (between ---)
• Frontmatter includes at least title field
• Files are in the correct folders (content/ for posts, pages/ for static pages)

Tags/Categories not working

Enable them in config.json:

"features": {
  "enableTags": true,
  "enableCategories": true
}

📚 Useful Resources

• Markdown Guide
• Node.js
• Marked Documentation
• GitHub Pages
• Netlify
• Vercel

💡 Tips

1. Organize content: Create subfolders in content/ by category
2. Use descriptive filenames: my-awesome-post.md is better than post1.md
3. Backup: Always backup your content/ and pages/ folders
4. Versioning: Use Git to track changes
5. Images: Store images in static/images/ and reference them as /images/image.jpg
6. SEO: Always add descriptions to your posts and pages
7. Social Sharing: Add featured images for better social media previews
8. Testing: Always preview your site locally before deploying
9. Themes: Try different themes to find the perfect look for your content
10. Custom CSS: Use the customCSS option to add small tweaks without creating a full theme

🎯 Roadmap

Future features we're planning:

• Full-text search
• Comments system integration
• Automatic sitemap generation
• Image optimization
• Custom theme system ✅
• Pagination for post lists
• Related posts feature
• Table of contents generation
• Code syntax highlighting themes
• Multi-language support
• More built-in themes
• Theme gallery/marketplace

🤝 Contributing

This project is open source. Feel free to improve it!

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

📄 License

MIT License - Free for personal and commercial use

🙏 Credits

Built with:

• Marked - Markdown parser
• Gray Matter - Frontmatter parser
• fs-extra - File system utilities
• Chokidar - File watcher

Inspired by:

• Beautiful Jekyll
• Hugo
• Jekyll

---

Built with love by the Shogun team | GitHub | Support

Happy writing! 📝