django-w-docs

Overview

django-w-docs is a reusable, production-ready documentation application built with Python, Django, Django REST Framework, and Wagtail CMS, styled with Tailwind CSS and daisyUI. It comes with sensible defaults, modern theming, and clean APIs—helping you launch structured, searchable documentation quickly and scale it with confidence.

Demo

Key features

• Full CMS: Wagtail-powered editorial interface with pages, media, search, and governance.
• Modern UI: Utility-first styling with Tailwind CSS for responsive, accessible layouts.
• Theming: All daisyUI themes included, with support for custom themes.
• API ready: Optional REST API endpoints for headless delivery and integrations.
• CI/CD: GitHub Actions pipelines for automated testing, linting, and deployment.
• Dependencies: Managed with Poetry for reproducibility and clarity.
• Formatting: Black for consistent, automatic code formatting.
• Linting: Ruff for fast, comprehensive linting.
• Testing: Django test runner for unit and integration tests.
• Starter configs: .gitignore, pyproject.toml, and other boilerplate included.

Use cases

• Product docs & API reference: Guides, FAQs, and endpoint documentation with search and tags.
• Knowledge base: Self‑serve help center to reduce support load.
• Internal handbook: Onboarding, SOPs, and runbooks with role‑based access.
• Release notes & policies: Publish updates, policies, and compliance docs.
• Multilingual content: Maintain parity across languages with Wagtail i18n.
• In‑product help: Surface contextual docs via the REST API.

Installation

pip install django-w-docs

Configuration

Add installed apps

# project/settings.py

INSTALLED_APPS = [
    "docs",
    "docs.api",              # Optional: REST API
    "docs.apps.home",        # Optional: if your project includes a Home model ('home.Home')
    "docs.apps.indexes",
    "docs.apps.pages",
    "docs.apps.sections",
    "docs.apps.tags",
    "docs.cms",
    "docs.ui",

    # Dependencies
    "rest_wind",             # Optional: REST API
    "rest_framework",        # Optional: REST API
    "wagtail_blocks",
    "wagtail.contrib.search_promotions",
    "wagtail.contrib.forms",
    "wagtail.contrib.redirects",
    "wagtail.embeds",
    "wagtail.sites",
    "wagtail.users",
    "wagtail.snippets",
    "wagtail.documents",
    "wagtail.images",
    "wagtail.search",
    "wagtail.admin",
    "wagtail",
    "modelcluster",
    "taggit",
    # ...
]

Run migrations

python manage.py migrate

Update URL configuration

# project/urls.py

from django.urls import include, path
from wagtail import urls as wagtail_urls
from wagtail.admin import urls as wagtailadmin_urls
from wagtail.documents import urls as wagtaildocs_urls

urlpatterns = [
    path("", include("docs.ui.urls")),
    path("api/", include("docs.api.urls")),           # Optional: REST API
    path("api/", include("rest_framework.urls")),     # Optional: REST API
    # ...
    path("documents/", include(wagtaildocs_urls)),
    path("dashboard/", include(wagtailadmin_urls)),
    path("", include(wagtail_urls)),                  # Keep this last
]

Theming and templates

All templates in django-w-docs extend docs/base.html. Create and customize this base template to match your brand.

Create the template directory

mkdir -p your_app/templates/docs

Create the base template

touch your_app/templates/docs/base.html

You can extend docs/base.html in your own templates or override any provided template for full control.

Available blocks and context

• docs/base.html

  • Blocks: theme, toggle_theme, head, title, styles, navbar, branding, navbar_center, navbar_end, content, footer, drawer_branding, drawer_content
  • Context: home (site root page)

• docs/index.html

  • Blocks: All from docs/base.html
  • Context: index (docs index page)

• docs/section.html

  • Blocks: All from docs/base.html
  • Context: section (DocsSection instance)

• docs/page.html

  • Blocks: All from docs/base.html
  • Context: page (DocsPage instance)

• docs/search.html

  • Blocks: All from docs/base.html
  • Context: search_results (PageQuerySet results)

Contributing

We welcome contributions from the community. Please review the CONTRIBUTING guide for setup, coding standards, and workflow. Opening an issue before major changes helps align on scope and direction.

Support

For questions, bug reports, or feature requests, open an issue or join the conversation in GitHub Discussions.

License

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