I'd put preference on retaining the same styling as docutils 0.17, there is a lot of vertical space in the list now. Also, this would be a 3rd style implementation to footnotes as html4/html5 also have differing styles to footnotes.

I can try to match the styling from html5writer <dl> but will still be a 3rd implementation :)

Whenever I look at the SASS code and the setup I get a feeling that it's all gonna get refactored/rewritten anyways, so I automatically try to keep the effort minimal. I agree that the final result can improve visually (the current <dl> version also has a few glimpses btw).

FWIW, if you find a way to avoid having the additional vertical whitespace, I'd like to borrow that back to Furo. I know those issues are closed, but I've not had the bandwidth to investigate the footnotes changes in detail -- whether they fixed my needs. It definitely doesn't help that docutils is maintained on SourceForge which... I find fugly. :)

I believe docutils hasn't figured out a way to stylise this in the manner we want either: https://docutils.sourceforge.io/docs/user/rst/demo.html#footnotes

FWIW, two things have happened:

1. Furo has better CSS for footnotes.
2. I better understand CSS grids. :)

This also made me have to look at CSS grids 🥲 However, I did not find a way to create a grid, since the variable DOM structure with label, definition or label, backrefs, definition was too hard a nut to crack for me. @pradyunsg I was looking at pradyunsg/furo#576 and guess you also went with float: left finally?

I tried to make the floats work like this...

before (docutils 0.17):

after (docutils 0.18):

I think that the result is acceptable. If there are several long paragraphs for a single footnote, the wrapping will not align. But I think that will belong to an absolute edge case 🤷

Notice also that the : is gone.. I didn't think it was worth bringing back, not least because it was already weirdly rendered in docutils 0.17. We could use the :before declaration on something like > p:first-of-type, however first-of-type only works in CSS3.

Edited: Circle CI issues have occurred because of a new release of sphinxcontrib-httpdomain that broke in Sphinx 1.7.

This also made me have to look at CSS grids

CSS grid is the best way to solve this, and avoids making a third implementation of the citation list -- html5 writer current uses CSS grid and html4 doesn't need floating/grid as it's a table.

Notice also that the : is gone

There is a selector that we can use (:has()), but it's not supported on Firefox, so I'd say that's a no go. It's fine to drop these for now.

We could use the :before declaration on something like > p:first-of-type

This wouldn't quite work, it would be grouped with the p instead of the span.backrefs. CSS3 features are fine as long as they are implemented. first-of-type has good enough support it's usable otherwise.

https://caniuse.com/?search=first-of-type

On #1322 I mentioned I'd jump in to solve this and wanted an approach that uses CSS grid, similar to our current approach for the HTML5 writer in docutils < 0.18. I have a PR I'll put up with the fix but it could probably use some more back testing.

I'll close this PR and move the test fixes.

@agjohnson great work on the CSS grid!

Regarding :, I think that the footnotes lists look better without colons + the colon is unnecessary + the previous solution with : looked weird, especially with backrefs included.

Yeah the colon came from the html4 implementation, so was just added for parity. I agree that it looks unnecessary though, I'm also 👍 on dropping it

Superseded by #1383 and #1381

FWIW, if you find a way to avoid having the additional vertical whitespace, I'd like to borrow that back to Furo.

@pradyunsg sounds like you poked around with CSS grids a bit, but if you are still looking for an example:

I would really have preferred docutils output more wrapping elements to make styling this easier. There's only so much you can do with the existing output structure, even with grids.

@agjohnson in general, DOM changes in docutils without theme maintainer consultation is not nice. Once they have finished moving docutils to a more modern platform (work is ongoing to move docutils to git), perhaps it can be easier to be included in changes that affect the DOM.