sphinx-doc / sphinx-doc/sphinx

The HTML5 writer should render hlist nodes with CSS columns

Open
#10,754 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

builder:html type:enhancement
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Currently, Sphinx includes the hlist directive which produces a bulleted list split into multiple columns. Internally, it splits the list up into as many equal-sized pieces as there are columns. The HTML5 writer renders this by constructing a one-row table with a list in each column:

https://github.com/sphinx-doc/sphinx/blob/f45dc5e1398f7850e23003cac200ad3433da2a78/sphinx/writers/html5.py#L637-L647

The problem with this approach is that it only checks that each column has the same number of items. If some items are a little long and get wrapped across two lines at some zoom levels (or with some fonts, or on some platforms) the whole list can look quite messy. In addition, there's probably accessibility issues (screen readers, etc.) when one list is presented as four separate lists.

But browsers already have a solution to this problem, in the form of the column-count CSS property. Instead of a complex structure of table and lists, Sphinx could just change the typical bulleted-list output from <ul> to <ul style="column-count: 3"> (or whatever the value of the :columns: option is). The Sphinx code would be simpler since it doesn't have to slice up the list, it would be more accessible since a single list in the source would be a single list in the HTML, and it would be robust in the face of runtime layout because the runtime layout engine is doing the work.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the hlist handling in sphinx/directives/other.py and the HTML5 writer code in sphinx/writers/html5.py. Trace how the :columns: option reaches the writer, then verify that hlist output uses one list with the requested CSS column count rather than a table of separate lists. Confirm the generated HTML remains valid and accessible.

Written by the indexing model from the issue text.

Assessment

Tech stack
css, python
Domain
documentation
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.