README.md

metadata

title: Personal Blog
emoji: 📝
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
license: mit

📝 Personal Blog

A clean, minimalist blog platform for sharing articles, code snippets, and engaging with readers through comments.

✨ Features

• 📰 Article Publishing - Write and publish blog posts with Markdown support
• 💻 Code Snippets - Share code examples with syntax highlighting
• 💬 Comments System - Readers can leave comments on your articles
• 🌓 Dark/Light Mode - Toggle between themes with persistent preference
• 🎨 Minimalist Design - Clean, distraction-free reading experience
• 🏷️ Tag Organization - Organize content with tags
• ⚡ Fast & Lightweight - Built with FastAPI and vanilla JavaScript
• 📱 Responsive - Works beautifully on all devices

🚀 Live Demo

Visit the blog: [Click "App" tab above]

Access admin panel: Add /admin.html to the URL

🛠️ Tech Stack

• Backend: FastAPI
• Storage: JSON files (persistent)
• Frontend: Vanilla JavaScript, HTML5, CSS3
• Markdown: Marked.js
• Syntax Highlighting: Highlight.js

📖 How to Use

For Readers

1. Browse articles on the homepage
2. Click any article to read the full content
3. Leave comments at the bottom of articles
4. Toggle dark/light mode with the 🌙/☀️ button
5. View code snippets in the "Code Snippets" tab

For Authors (You!)

Option 1: Admin Panel (Easiest)

1. Navigate to /admin.html
2. Use the web interface to:
   • Create new articles
   • Add code snippets
   • Preview content before publishing
   • Manage existing articles

Option 2: API (Programmatic)

Create articles via API:

import requests

BLOG_URL = "YOUR_SPACE_URL"

article = {
    "title": "My First Post",
    "slug": "my-first-post",
    "content": "# Hello World\n\nThis is my first blog post!",
    "excerpt": "Introduction to my blog",
    "tags": ["introduction"],
    "published": True
}

requests.post(f"{BLOG_URL}/api/articles", json=article)

Or using curl:

curl -X POST YOUR_SPACE_URL/api/articles \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Post",
    "slug": "my-post",
    "content": "# Content here",
    "published": true
  }'

Option 3: Direct File Edit

Edit data/articles.json directly in the Files tab.

📚 API Documentation

Interactive API docs available at /docs

Main Endpoints

• GET /api/articles - List all published articles
• GET /api/articles/{slug} - Get single article
• POST /api/articles - Create new article
• PUT /api/articles/{id} - Update article
• DELETE /api/articles/{id} - Delete article
• GET /api/snippets - List code snippets
• POST /api/snippets - Create snippet
• GET /api/articles/{id}/comments - Get article comments
• POST /api/articles/{id}/comments - Add comment

✍️ Writing in Markdown

Articles support full Markdown syntax:

# Heading 1
## Heading 2

**Bold** and *italic* text

- Bullet points
- Another point

1. Numbered lists
2. Second item

[Links](https://example.com)

`inline code`

```python
# Code blocks with syntax highlighting
def hello():
    print("Hello World!")

Blockquotes

## 🎨 Customization

### Update Your Info

Edit `static/index.html`:

```html
<h1>Your Name Here</h1>
<p class="subtitle">Your Title/Description</p>

Change Colors

Modify CSS variables in static/index.html:

:root {
    --accent: #0066cc;  /* Change accent color */
    --bg-primary: #ffffff;
    --text-primary: #1a1a1a;
}

Popular color schemes:

• Blue: #0066cc (default)
• Red: #ff6b6b
• Green: #4ecdc4
• Purple: #9b59b6
• Orange: #f39c12

💾 Data Storage

All data is stored in JSON files in the data/ directory:

• articles.json - Blog posts
• snippets.json - Code snippets
• comments.json - Reader comments

Important: These files persist across Space restarts. Download them periodically for backup.

📁 Project Structure

.
├── app.py                 # FastAPI backend
├── requirements.txt       # Python dependencies
├── Dockerfile            # Container configuration
├── README.md             # This file
├── static/
│   ├── index.html        # Main blog interface
│   └── admin.html        # Admin panel
└── data/
    ├── articles.json     # Articles storage
    ├── snippets.json     # Snippets storage
    └── comments.json     # Comments storage

🔒 Security Notes

This is a simple blog without authentication:

✅ Anyone can:

• Read articles
• View snippets
• Post comments

⚠️ No protection for:

• Creating/editing articles via API
• Deleting content via API

For production: Consider adding:

• API key authentication
• Rate limiting
• Comment moderation
• CAPTCHA for comments

🚀 Deployment

This blog is deployed on HuggingFace Spaces using Docker.

To deploy your own:

1. Fork this Space or create a new one
2. Choose "Docker" as SDK
3. Upload all files
4. Wait for build to complete
5. Your blog is live!

🤝 Contributing

Feel free to:

• Report bugs via the Community tab
• Suggest features
• Share your customizations
• Fork and improve!

📝 Example Articles

Sample article JSON:

{
  "id": 1,
  "title": "Getting Started with Python",
  "slug": "getting-started-python",
  "content": "# Python Basics\n\nPython is easy to learn...",
  "excerpt": "Introduction to Python programming",
  "tags": ["python", "tutorial"],
  "published": true,
  "created_at": "2024-01-20T10:00:00",
  "updated_at": "2024-01-20T10:00:00"
}

🎯 Roadmap

Planned features:

• RSS feed generation
• Full-text search
• Article series/collections
• Social sharing buttons
• Reading time estimates
• View counters
• Email notifications for comments
• Markdown export/import

📄 License

MIT License - feel free to use this for your personal blog!

🙏 Credits

Built with:

• FastAPI
• Marked.js
• Highlight.js
• HuggingFace Spaces

📧 Support

If you have questions or need help:

• Check the /docs endpoint for API documentation
• Visit the Community tab
• Review the admin panel at /admin.html

---

Happy Blogging! ✨

Start writing your first post in the admin panel or via the API.

---

Quick Start Checklist

• Customize your name in static/index.html
• Write your first article via /admin.html
• Add a code snippet
• Test dark mode toggle
• Share your blog URL
• Backup your data/ folder
• Start writing regularly!

Your blog is ready to go! 🚀