Skip to content

README.md

Latest commit

 

History

History
523 lines (407 loc) · 14.8 KB

README.md

File metadata and controls

523 lines (407 loc) · 14.8 KB
Raw

📚 MD Books Library

A full-featured web application for publishing, reading, and managing books written in Markdown format. Built with Django, it provides a complete platform for authors to publish their work and readers to discover, read, and review content.

🚀 Features

For Readers

  • 📖 Browse & Discover — Explore books by category, tags, popularity, or search
  • 📑 Markdown Rendering — Read chapters with beautifully rendered Markdown content
  • ⭐ Reviews & Ratings — Rate books (1–5 stars) and write detailed reviews
  • 🔍 Search & Filter — Find books by title, category, tag, or sort by popularity/rating
  • 👁️ View Tracking — See how popular each book is
  • 👤 Public Profiles — View author profiles with their published works

For Authors

  • ✍️ Book Publishing — Create books with cover images, descriptions, and tags
  • 📝 Chapter Management — Write chapters in Markdown with ordering support
  • 📊 Statistics — Track views, likes, ratings, and review counts
  • 📁 Category Requests — Propose new categories for your books
  • 🏷️ Flexible Tagging — Tag books with relevant keywords for discovery
  • 📋 Draft System — Save books and chapters as drafts before publishing

For Moderators

  • ✅ Category Approval — Review and approve/reject category requests
  • 🎛️ Django Admin — Full admin interface with custom actions and dashboards
  • 📊 Bulk Operations — Publish/unpublish books, approve categories in bulk

Platform Features

  • 🔐 Authentication — Login, logout, password reset, and profile management
  • 💳 Donation Tracking — Stripe and PayPal integration for supporter donations
  • 🔗 Social Profiles — GitHub, YouTube, Twitter, and website links
  • 📱 Responsive Design — Bootstrap 5 based responsive UI

🛠️ Tech Stack

Layer Technology
Backend Python 3.11+, Django 5.x
Database SQLite (dev) / PostgreSQL (prod)
Frontend HTML5, Bootstrap 5, JavaScript
Content Markdown (rendered to HTML)
Images Pillow, Django ImageField
Admin Django Admin (customized)
Auth Django built-in authentication
Payments Stripe, PayPal (integration ready)

📁 Project Structure

md-books-library/
├── manage.py
├── requirements.txt
├── README.md
│
├── config/                          # Project configuration
│   ├── __init__.py
│   ├── settings.py                  # Django settings
│   ├── urls.py                      # Root URL configuration
│   ├── asgi.py
│   └── wsgi.py
│
├── accounts/                        # User accounts & profiles
│   ├── __init__.py
│   ├── apps.py                      # AppConfig with signal registration
│   ├── models.py                    # Profile model
│   ├── forms.py                     # UserForm, ProfileForm
│   ├── views.py                     # ProfileView, PublicProfileView
│   ├── urls.py                      # Auth & profile URLs
│   ├── admin.py                     # ProfileAdmin
│   └── signals.py                   # Auto-create Profile on User creation
│
├── books/                           # Core library application
│   ├── __init__.py
│   ├── apps.py                      # AppConfig
│   ├── admin.py                     # Admin for all book models
│   ├── urls.py                      # All book-related URLs
│   │
│   ├── models/                      # Data models
│   │   ├── __init__.py
│   │   ├── category.py              # Category (with approval workflow)
│   │   ├── tag.py                   # Tag (keyword labels)
│   │   ├── book.py                  # Book (main entity)
│   │   ├── chapter.py               # Chapter (Markdown content)
│   │   └── review.py                # Review (ratings & comments)
│   │
│   ├── forms/                       # Form classes
│   │   ├── __init__.py
│   │   ├── book.py                  # BookForm
│   │   ├── category.py              # CategoryForm
│   │   ├── chapter.py               # ChapterForm
│   │   ├── review.py                # ReviewForm
│   │   └── tag.py                   # TagForm
│   │
│   ├── views/                       # View classes (CBV)
│   │   ├── __init__.py
│   │   ├── book.py                  # BookListView, DetailView, Create, Update
│   │   ├── category.py              # Category views with approval workflow
│   │   ├── chapter.py               # Chapter views with Markdown rendering
│   │   ├── review.py                # Review views with duplicate prevention
│   │   └── tag.py                   # Tag views with tag cloud
│   │
│   └── templates/books/             # HTML templates
│       ├── book/
│       ├── category/
│       ├── chapter/
│       ├── review/
│       └── tag/
│
├── core/                            # Core pages
│   ├── __init__.py
│   ├── apps.py
│   ├── views.py                     # HomeView (landing page)
│   ├── urls.py
│   └── templates/core/
│       └── home.html
│
├── templates/                       # Global templates
│   └── base.html                    # Base template with Bootstrap
│
├── static/                          # Static files
│   ├── css/
│   ├── js/
│   └── images/
│
└── media/                           # User-uploaded files
    ├── avatars/                     # Profile pictures
    └── books/                       # Book covers & category images

🏗️ Model Relationships

User (Django auth)
 │
 └──< Profile (OneToOne)
       │
       ├──< Book (author) ──────────────────┐
       │      │                             │
       │      ├──< Chapter (book)           │
       │      ├──< Review (book, author) ───┤
       │      ├──> Category (FK, nullable)  │
       │      └──<> Tag (M2M)              │
       │                                    │
       ├──< Category (request author) ──────┘
       └──< Category (reviewed_by)
Model Description Key Fields
Profile Extended user profile avatar, bio, social links, donations
Book A published work title, slug, description, views, likes
Chapter Book section with Markdown title, content, order, is_published
Category Book classification (with approval) title, status, author, reviewed_by
Tag Keyword label name, slug
Review User rating & feedback rating (1-5), comment

📦 Installation

Prerequisites

  • Python 3.11 or higher
  • pip (Python package manager)
  • Git

Step 1: Clone the Repository

git clone https://github.com/yourusername/md-books-library.git
cd md-books-library

Step 2: Create Virtual Environment

# Linux/Mac
python -m venv venv
source venv/bin/activate

# Windows (CMD)
python -m venv venv
venv\Scripts\activate

# Windows (PowerShell)
python -m venv venv
venv\Scripts\Activate.ps1

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Configure Environment Variables

Create a .env file in the project root:

DEBUG=True
SECRET_KEY=your-secret-key-here
DATABASE_URL=sqlite:///db.sqlite3
MEDIA_URL=/media/
MEDIA_ROOT=media/

Step 5: Run Migrations

python manage.py makemigrations
python manage.py migrate

Step 6: Create Superuser

python manage.py createsuperuser

Step 7: Collect Static Files

python manage.py collectstatic

Step 8: Run Development Server

python manage.py runserver

Visit http://127.0.0.1:8000/ to see the application.

🔗 URL Routes

Core

URL View Description
/ HomeView Landing page with featured content

Accounts (/accounts/)

URL View Access
/accounts/login/ LoginView Public
/accounts/logout/ LogoutView Authenticated
/accounts/profile/ ProfileView Authenticated
/accounts/profile/<username>/ PublicProfileView Authenticated
/accounts/password/change/ PasswordChangeView Authenticated
/accounts/password/reset/ PasswordResetView Public

Books (/books/)

URL View Access
/books/ BookListView Public
/books/book/<slug>/ BookDetailView Public
/books/book/create/ BookCreateView Authenticated
/books/book/<slug>/edit/ BookUpdateView Author only

Categories

URL View Access
/books/categories/ CategoryListView Public
/books/category/<slug>/ CategoryDetailView Public
/books/category/create/ CategoryCreateView Authenticated
/books/category/<slug>/edit/ CategoryUpdateView Author (pending only)

Chapters

URL View Access
/books/book/<book_slug>/chapters/ ChapterListView Public
/books/book/<book_slug>/chapter/<slug>/ ChapterDetailView Public
/books/book/<book_slug>/chapter/create/ ChapterCreateView Book author
/books/book/<book_slug>/chapter/<slug>/edit/ ChapterUpdateView Book author

Reviews

URL View Access
/books/reviews/ ReviewListView Public
/books/review/<pk>/ ReviewDetailView Public
/books/book/<book_slug>/review/create/ ReviewCreateView Authenticated
/books/review/<pk>/edit/ ReviewUpdateView Review author

Tags

URL View Access
/books/tags/ TagListView Public
/books/tag/<slug>/ TagDetailView Public
/books/tag/create/ TagCreateView Authenticated
/books/tag/<slug>/edit/ TagUpdateView Staff only

Admin

URL Access
/admin/ Staff/Superuser

⚙️ Configuration

Settings (config/settings.py)

Key settings to configure:

# Security
SECRET_KEY = os.environ.get('SECRET_KEY', 'your-secret-key')
DEBUG = os.environ.get('DEBUG', 'True') == 'True'
ALLOWED_HOSTS = ['localhost', '127.0.0.1']

# Database
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': BASE_DIR / 'db.sqlite3',
    }
}

# Installed Apps
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    
    # Local apps
    'accounts.apps.AccountsConfig',
    'books.apps.BooksConfig',
    'core.apps.CoreConfig',
]

# Media files (user uploads)
MEDIA_URL = '/media/'
MEDIA_ROOT = BASE_DIR / 'media'

# Static files
STATIC_URL = '/static/'
STATIC_ROOT = BASE_DIR / 'staticfiles'

Production Deployment

For production, update these settings:

DEBUG = False
ALLOWED_HOSTS = ['yourdomain.com']

# Use PostgreSQL
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'md_books_library',
        'USER': 'db_user',
        'PASSWORD': 'db_password',
        'HOST': 'localhost',
        'PORT': '5432',
    }
}

# Security settings
SECURE_SSL_REDIRECT = True
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True
SECURE_HSTS_SECONDS = 31536000

🎛️ Django Admin

The admin interface is fully customized with:

  • Avatar thumbnails and status badges
  • Inline editing for chapters and reviews within books
  • Custom actions for bulk publish/unpublish/approve/reject
  • Query optimization to prevent N+1 problems
  • Clickable links between related objects
  • Star ratings and formatted statistics

Access at: http://127.0.0.1:8000/admin/

📝 Development

Running Tests

python manage.py test

Code Formatting

pip install black isort
black .
isort .

Making Migrations

python manage.py makemigrations
python manage.py migrate

Creating a New Feature

  1. Create a new branch:

    git checkout -b feature/your-feature-name

  2. Make your changes

  3. Run tests:

    python manage.py test

  4. Commit and push:

    git add .
git commit -m "Add: your feature description"
git push origin feature/your-feature-name

  5. Open a Pull Request

📋 TODO / Roadmap

High Priority

  • Markdown rendering with syntax highlighting
  • Image optimization with django-imagekit
  • Full-text search with PostgreSQL SearchVector
  • Caching with Redis
  • Email notifications for category approval/rejection

Medium Priority

  • AJAX tag autocomplete
  • Live Markdown preview in chapter editor
  • User follow system
  • Reading progress tracking
  • Book bookmarks/favorites
  • Category moderation dashboard

Low Priority

  • REST API with Django REST Framework
  • Social authentication (Google, GitHub)
  • Two-factor authentication
  • Export books as PDF/EPUB
  • Collaborative editing
  • Analytics dashboard

🤝 Contributing

Contributions are welcome! Please follow these steps:

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

Code Style

  • Follow PEP 8 guidelines
  • Use Black for code formatting
  • Add docstrings to all classes and methods
  • Write tests for new features

📄 License

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

🙏 Acknowledgments

  • Django — The web framework for perfectionists with deadlines
  • Bootstrap — Frontend component library
  • Python-Markdown — Markdown to HTML conversion

📧 Contact

Made with ❤️ and Django

Since the project is being thrown together on a whim in spare time, an AI is writing the comments.)))