Skip to content

README-en.md

Latest commit

 

History

History
201 lines (146 loc) · 8.75 KB

README-en.md

File metadata and controls

201 lines (146 loc) · 8.75 KB

DjangoBlog

Django CI Frontend CI CodeQL codecov license

A powerful, elegant, and modern blog system.
English • 简体中文

DjangoBlog is a high-performance blog platform built with Python 3.10+ and Django 5.2. It not only provides all the core functionalities of a traditional blog but also features a flexible plugin system, allowing you to easily extend and customize your website. Whether you are a personal blogger, a tech enthusiast, or a content creator, DjangoBlog aims to provide a stable, efficient, and easy-to-maintain environment for writing and publishing.

✨ Features

  • Powerful Content Management: Full support for managing articles, standalone pages, categories, and tags. Comes with a powerful built-in Markdown editor with syntax highlighting.
  • Full-Text Search: Integrated Elasticsearch/Whoosh search engine for fast and accurate content searching, with keyword highlighting support.
  • Interactive Comment System: Supports replies, email notifications, and Markdown formatting in comments. Modern comment interface with infinite nested replies.
  • Flexible Sidebar: Customizable modules for displaying recent articles, most viewed posts, tag cloud, and more.
  • Social Login: Built-in OAuth support, with integrations for Google, GitHub, Facebook, Weibo, QQ, and other major platforms.
  • Dark Mode Support: Toggle between light and dark themes with system preference support for comfortable reading experience. Anti-FOUC (Flash of Unstyled Content) implementation.
  • Modern Frontend: Built with Alpine.js + Tailwind CSS + HTMX, providing SPA-like navigation experience with HTML-over-the-wire architecture.
  • High-Performance Caching: Native support for Redis caching with an automatic refresh mechanism to ensure high-speed website responses.
  • SEO Friendly: Basic SEO features are included, with automatic notifications to Google and Baidu upon new content publication.
  • Extensible Plugin System: Extend blog functionalities by creating standalone plugins, ensuring decoupled and maintainable code. 8 built-in plugins including view counting, SEO optimization, article recommendations, lazy image loading, and more!
  • Integrated Image Hosting: A simple, built-in image hosting feature for easy uploads and management.
  • Automated Build: Uses Vite to build frontend assets with hot reload and automatic optimization.
  • Robust Operations: Built-in email notifications for website exceptions and management capabilities through a WeChat Official Account.

🛠️ Tech Stack

  • Backend: Python 3.10+, Django 5.2
  • Database: MySQL, SQLite (configurable)
  • Cache: Redis, LocalMem (configurable)
  • Frontend: Alpine.js 3.13, Tailwind CSS 3.4, HTMX 2.0, Vite 5.4
  • Search: Whoosh, Elasticsearch (configurable)
  • Editor: Markdown (mdeditor)

🚀 Getting Started

1. Prerequisites

Ensure you have Python 3.10+ and MySQL/MariaDB installed on your system.

2. Clone & Installation

# Clone the project to your local machine
git clone https://github.com/liangliangyy/DjangoBlog.git
cd DjangoBlog

# Install dependencies
pip install -r requirements.txt

3. Project Configuration

  • Database: Open djangoblog/settings.py, locate the DATABASES section, and update it with your MySQL connection details.

    DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'djangoblog',
        'USER': 'root',
        'PASSWORD': 'your_password',
        'HOST': '127.0.0.1',
        'PORT': 3306,
    }
}

    Create the database in MySQL:

    CREATE DATABASE `djangoblog` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

  • More Configurations: For advanced settings such as email, OAuth, caching, and more, please refer to our Detailed Configuration Guide.

4. Database Initialization

python manage.py makemigrations
python manage.py migrate

# Create a superuser account
python manage.py createsuperuser

5. Build Frontend Assets

# Navigate to frontend directory
cd frontend

# Install dependencies (required for first run)
npm install

# Build production assets
npm run build

# Return to project root
cd ..

6. Running the Project

# (Optional) Generate some test data
python manage.py create_testdata

# Collect static files
python manage.py collectstatic --noinput

# (Optional) Compress static files
python manage.py compress --force

# Start the development server
python manage.py runserver

Now, open your browser and navigate to http://127.0.0.1:8000/. You should see the DjangoBlog homepage!

Development Mode

If you need to develop frontend code, you can use Vite's hot reload feature:

# Start development server in frontend directory
cd frontend
npm run dev

This will start the Vite development server, and frontend code changes will be automatically rebuilt.

Deployment

  • Traditional Deployment: A detailed guide for server deployment is available here: Deployment Tutorial (in Chinese).
  • Docker Deployment: This project fully supports Docker. If you are familiar with containerization, please refer to the Docker Deployment Guide for a quick start.
  • Kubernetes Deployment: We also provide a complete Kubernetes Deployment Guide to help you go cloud-native easily.

🧩 Plugin System

The plugin system is a core feature of DjangoBlog. It allows you to add new functionalities to your blog without modifying the core codebase by writing standalone plugins.

  • How it Works: Plugins operate by registering callback functions to predefined "hooks". For instance, when an article is rendered, the after_article_body_get hook is triggered, and all functions registered to this hook are executed.

  • Built-in Plugins: The project includes the following useful plugins

    • view_count - Article view counter
    • seo_optimizer - SEO optimization enhancements
    • article_copyright - Article copyright notices (modern style)
    • article_recommendation - Smart article recommendations (responsive card layout)
    • external_links - External link handling (automatic icon addition)
    • image_lazy_loading - Image lazy loading optimization (fade-in animation)
    • reading_time - Article reading time estimation
    • cloudflare_cache - Cloudflare cache management

  • Develop Your Own Plugin: Simply create a new folder under the plugins directory and write your plugin.py. We welcome you to explore and contribute your creative ideas to the DjangoBlog community!

🤝 Contributing

We warmly welcome contributions of any kind! If you have great ideas or have found a bug, please feel free to open an issue or submit a pull request.

📄 License

This project is open-sourced under the MIT License.

❤️ Support & Sponsorship

If you find this project helpful and wish to support its continued maintenance and development, please consider buying me a coffee! Your support is my greatest motivation.

Alipay Sponsorship WeChat Sponsorship

(Left) Alipay / (Right) WeChat

🙏 Acknowledgements

A special thanks to JetBrains for providing a free open-source license for this project.

JetBrains Logo

If this project has helped you, please leave your website URL here to let more people see it. Your feedback is the driving force for my continued updates and maintenance.