Improve styling of tables in docs

[bmispelon]

I noticed today that some pages in the documentation use tables:

I find the styling a bit hard to read:

1. The table headers are not visually separated (no border, no horizontal margin)
2. The table has no bottom margin

[blighj]

I'd agree. In a lot of cases, I find the tables easier to read in the original rst format, that's a bad sign.

List of tables in docs

• faq/install/#what-python-version-can-i-use-with-django

  
  faq/install/#what-python-version-can-i-use-with-django
• ref/contrib/admin/#django.contrib.admin.ModelAdmin.search_fields

  ref/contrib/admin/#django.contrib.admin.ModelAdmin.search_fields
  
• ref/contrib/admin/#reversing-admin-urls (3)

  ref/contrib/admin/#reversing-admin-urls
  

  ---

  

  ---

  
• ref/contrib/admin/admindocs/#documentation-helpers

  ref/contrib/admin/admindocs/#documentation-helpers
  
• ref/contrib/gis/db-api/#aggregate-functions

  ref/contrib/gis/db-api/#aggregate-functions
  
• ref/contrib/gis/db-api/#database-functions

  ref/contrib/gis/db-api/#database-functions
  
• ref/contrib/gis/db-api/#spatial-lookup-compatibility

  ref/contrib/gis/db-api/#spatial-lookup-compatibility
  
• ref/contrib/gis/functions/#asgeojson

  ref/contrib/gis/functions/#asgeojson
  
• ref/contrib/gis/functions/#asgml

  ref/contrib/gis/functions/#asgml
  
• ref/contrib/gis/functions/#askml

  ref/contrib/gis/functions/#askml
  
• ref/contrib/gis/functions/#assvg

  ref/contrib/gis/functions/#assvg
  
• ref/contrib/gis/functions/#snaptogrid

  ref/contrib/gis/functions/#snaptogrid
  
• ref/contrib/gis/gdal/#the-band-input-dictionary

  ref/contrib/gis/gdal/#the-band-input-dictionary
  
• ref/contrib/gis/gdal/#the-ds-input-dictionary (2)

  ref/contrib/gis/gdal/#the-ds-input-dictionary
  

  ---

  
• ref/contrib/gis/geoip2/#api-reference

  ref/contrib/gis/geoip2/#api-reference
  
• ref/contrib/gis/geoquerysets/#aggregate-functions

  ref/contrib/gis/geoquerysets/#aggregate-functions
  
• ref/contrib/gis/geoquerysets/#bbcontains

  ref/contrib/gis/geoquerysets/#bbcontains
  
• ref/contrib/gis/geoquerysets/#bboverlaps

  ref/contrib/gis/geoquerysets/#bboverlaps
  
• ref/contrib/gis/geoquerysets/#contained

  ref/contrib/gis/geoquerysets/#contained
  
• ref/contrib/gis/geoquerysets/#contains-properly

  ref/contrib/gis/geoquerysets/#contains-properly
  
• ref/contrib/gis/geoquerysets/#contains

  ref/contrib/gis/geoquerysets/#contains
  
• ref/contrib/gis/geoquerysets/#coveredby

  ref/contrib/gis/geoquerysets/#coveredby
  
• ref/contrib/gis/geoquerysets/#covers

  ref/contrib/gis/geoquerysets/#covers
  
• ref/contrib/gis/geoquerysets/#crosses

  ref/contrib/gis/geoquerysets/#crosses
  
• ref/contrib/gis/geoquerysets/#disjoint

  ref/contrib/gis/geoquerysets/#disjoint
  
• ref/contrib/gis/geoquerysets/#distance-gt

  ref/contrib/gis/geoquerysets/#distance-gt
  
• ref/contrib/gis/geoquerysets/#distance-gte

  ref/contrib/gis/geoquerysets/#distance-gte
  
• ref/contrib/gis/geoquerysets/#distance-lt

  ref/contrib/gis/geoquerysets/#distance-lt
  
• ref/contrib/gis/geoquerysets/#distance-lte

  ref/contrib/gis/geoquerysets/#distance-lte
  
• ref/contrib/gis/geoquerysets/#dwithin

  ref/contrib/gis/geoquerysets/#dwithin
  
• ref/contrib/gis/geoquerysets/#equals

  ref/contrib/gis/geoquerysets/#equals
  
• ref/contrib/gis/geoquerysets/#exact-same-as

  ref/contrib/gis/geoquerysets/#exact-same-as
  
• ref/contrib/gis/geoquerysets/#intersects

  ref/contrib/gis/geoquerysets/#intersects
  
• ref/contrib/gis/geoquerysets/#isvalid

  ref/contrib/gis/geoquerysets/#isvalid
  
• ref/contrib/gis/geoquerysets/#lookups-with-rasters

  ref/contrib/gis/geoquerysets/#lookups-with-rasters
  
• ref/contrib/gis/geoquerysets/#overlaps

  ref/contrib/gis/geoquerysets/#overlaps
  
• ref/contrib/gis/geoquerysets/#touches

  ref/contrib/gis/geoquerysets/#touches
  
• ref/contrib/gis/geoquerysets/#within

  ref/contrib/gis/geoquerysets/#within
  
• ref/contrib/gis/geos/#django.contrib.gis.geos.GEOSGeometry.geom_typeid

  ref/contrib/gis/geos/#django.contrib.gis.geos.GEOSGeometry.geom_typeid
  
• ref/contrib/gis/geos/#django.contrib.gis.geos.WKBWriter.byteorder

  ref/contrib/gis/geos/#django.contrib.gis.geos.WKBWriter.byteorder
  
• ref/contrib/gis/geos/#django.contrib.gis.geos.WKBWriter.outdim

  ref/contrib/gis/geos/#django.contrib.gis.geos.WKBWriter.outdim
  
• ref/contrib/gis/geos/#geometry-objects

  ref/contrib/gis/geos/#geometry-objects
  
• ref/contrib/gis/install/#spatial-database

  ref/contrib/gis/install/#spatial-database
  
• ref/contrib/gis/install/geolibs/#installing-geospatial-libraries

  ref/contrib/gis/install/geolibs/#installing-geospatial-libraries
  
• ref/contrib/gis/layermapping/#layermapping-api (2)

  ref/contrib/gis/layermapping/#layermapping-api
  

  ---

  
• ref/contrib/gis/layermapping/#save-keyword-arguments

  ref/contrib/gis/layermapping/#save-keyword-arguments
  
• ref/contrib/gis/measure/#supported-units (2)

  ref/contrib/gis/measure/#supported-units
  

  ---

  
• ref/contrib/messages/#creating-custom-message-levels

  ref/contrib/messages/#creating-custom-message-levels
  
• ref/contrib/messages/#message-levels

  ref/contrib/messages/#message-levels
  
• ref/contrib/messages/#message-tags

  ref/contrib/messages/#message-tags
  
• ref/databases/#row-locking-with-queryset-select-for-update

  ref/databases/#row-locking-with-queryset-select-for-update
  
• ref/models/database-functions/#django.db.models.functions.PercentRank

  ref/models/database-functions/#django.db.models.functions.PercentRank
  
• ref/models/fields/#django.db.models.FileField.upload_to

  ref/models/fields/#django.db.models.FileField.upload_to
  
• ref/signals/#m2m-changed (2)

  ref/signals/#m2m-changed
  

  ---

  
• ref/signals/#pre-init

  ref/signals/#pre-init
  
• ref/templates/builtins/#date

  ref/templates/builtins/#date
  
• ref/templates/builtins/#floatformat (6)

  ref/templates/builtins/#floatformat
  

  ---

  

  ---

  

  ---

  

  ---

  

  ---

  
• ref/templates/builtins/#for

  ref/templates/builtins/#for
  
• ref/templates/builtins/#lorem

  ref/templates/builtins/#lorem
  
• ref/templates/builtins/#templatetag

  ref/templates/builtins/#templatetag
  
• ref/templates/builtins/#yesno

  ref/templates/builtins/#yesno
  
• releases/1.0-porting-guide/#database-backend-functions

  releases/1.0-porting-guide/#database-backend-functions
  
• releases/1.0-porting-guide/#handle-uploaded-files-using-the-new-api

  releases/1.0-porting-guide/#handle-uploaded-files-using-the-new-api
  
• releases/1.0-porting-guide/#signals

  releases/1.0-porting-guide/#signals
  
• releases/1.0-porting-guide/#work-with-file-fields-using-the-new-api

  releases/1.0-porting-guide/#work-with-file-fields-using-the-new-api
  
• releases/1.2/#specifying-databases

  releases/1.2/#specifying-databases
  
• topics/forms/modelforms/#field-types

  topics/forms/modelforms/#field-types
  
• topics/serialization/#serialization-formats

  topics/serialization/#serialization-formats
  
• topics/testing/tools/#django.test.modify_settings

  topics/testing/tools/#django.test.modify_settings
  

[blighj]

What about something like below to:

• increase the padding, to make it a little less cramped
• add alteranate background to scan easier
• add a highlight on hover to make it easier to track across wide tables

  table.docutils {
    border-collapse: collapse;
    margin-bottom: 1.5em;
    box-shadow: 0 1px 3px rgba(0,0,0,0.1);
  }
  table.docutils td, table.docutils th {
    border-bottom: 1px solid #ccc;
    padding: 8px 12px;
    line-height: 1.4;
  }
  table.docutils thead th {
    background-color: var(--code-bg);
    border-bottom: 2px solid #999;
    font-weight: bold;
  }
  table.docutils tr:nth-child(even) {
    background-color: var(--code-bg);
  }
  table.docutils tr:hover {
    background-color: var(--selection);
  }

With a highlight on hover


And in dark mode

[WajahatKanju]

@blighj your suggestions seem good why you have not create a PR yet ?

[blighj]

Thanks for the positive feedback.
I'm waiting for a little more consesus, perhaps an opinion from someone on the website working group. The tables have been this way for a long time, probably close to the 20 years. I think no harm letting the idea perculate for a little bit.

There are also things I'm not as expert in like where to make these changes, styles in the djangoproject scss styles in the main django docs repo or a mixture of both.

[WajahatKanju]

@blighj , sounds good. I'm also working on this—my PR is nearly ready as well, just doing a final check to make sure everything is in order.

If you’d prefer to open the PR yourself, feel free to go ahead—just let me know so we don’t duplicate efforts.

20250716-0802-23.5769416.mp4

20250716-0831-05.0014901.mp4

Thanks!

[blighj]

Nice job, you work away.

[WajahatKanju]

Hi @blighj, if you need any help with the SCSS changes—or with anything else, whether in this repo or another Django project—feel free to reach out. I'd be happy to help.