Skip to content

Fix: CSS static files folder structure to follow Django best practices #1870

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

07SUJITH
Copy link

@07SUJITH 07SUJITH commented Jun 5, 2025

Problem Statement

The current tutorial instructs users to place CSS files at blog/static/css/blog.css, which violates Django's static files namespacing conventions and causes deployment issues.

Impact:

  • python manage.py collectstatic fails during deployment
  • Namespace collisions between multiple apps
  • Tutorial doesn't follow Django's official best practices
  • Users experience deployment failures on PythonAnywhere and similar platforms
  • Inconsistent static file references across multiple tutorial sections

Solution

Updated the CSS section and all related tutorial sections to follow Django's recommended static file structure: app_name/static/app_name/.

Changes Made

  • Directory structure: blog/static/css/blog/static/blog/css/
  • Template references: {% static 'css/blog.css' %}{% static 'blog/css/blog.css' %} across all tutorial sections
  • Documentation: Updated all file path references and folder structure diagrams
  • Educational content: Added explanation of Django's static file namespacing convention
  • Consistency fix: Ensured all tutorial sections use the same correct static file pattern

Django Static Files Convention

Following Django's standard structure: app_name/static/app_name/[css|js|img|fonts]/

blog/
└── static/
    └── blog/
        ├── css/
        ├── js/
        ├── img/
        └── fonts/

This prevents namespace collisions when multiple apps have files with the same name.
This structure ensures that python manage.py collectstatic correctly gathers and organizes all static files into a central directory . This is especially important on platforms like PythonAnywhere, where the main project uses the collected static files.

Files Modified

  • css/README.md - Main CSS tutorial section (structure and explanation)
  • template_extending/README.md - Updated static CSS reference
  • django_forms/README.md - Updated static CSS reference
  • Any other tutorial sections with CSS static file references

References

Acceptance Criteria

  • CSS files follow app_name/static/app_name/ structure
  • Template static tags updated consistently across ALL tutorial sections
  • No remaining references to old static file structure

Deployment Impact

This change ensures:

  • collectstatic works correctly in production
  • ✅ No static file conflicts between apps
  • ✅ Compatibility with hosting platforms (PythonAnywhere, Heroku, etc.)
  • ✅ Alignment with Django community standards
  • ✅ Consistent experience across all tutorial chapters
  • ✅ No broken CSS loading in any part of the tutorial

Scope of Changes

This is a comprehensive fix that addresses the static file structure issue throughout the entire tutorial, ensuring:

  • Consistency: All sections now use the same correct pattern
  • Completeness: No section left with outdated references
  • Educational Value: Students learn the correct approach from the start

- Update blog/static/css/ to blog/static/blog/css/ structure
- Fix {% static 'css/blog.css' %} to {% static 'blog/css/blog.css' %}
- Update CSS tutorial section with correct folder structure
- Fix template extending section static reference
- Fix Django forms section static reference
- Add Django static files convention explanation
- Fixes collectstatic issues on deployment platforms
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant