Allow inline elements in sidenotes

[oyamauchi]

Context

When use_sidenotes is true and footnotes are converted to sidenotes, inline elements within the footnote content are stripped. When use_sidenotes is false, the inline elements show up as-is within the footnote. This means you can't even have bold or italics in sidenotes, which seems like a needless restriction.

Illustration:

Proposal

I'm not familiar with the details of Sphinx or Docutils, so I'm not sure how big of a task this is. As far as I can tell it's because of the call to astext() here:

https://github.com/executablebooks/sphinx-book-theme/blob/master/src/sphinx_book_theme/_transforms.py#L34

Tasks and updates

No response

[welcome]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.

If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).

Welcome to the EBP community! 🎉

[choldgraf]

cc @AakashGfude could you look into this one? I think we might have a bug in the sidenotes code

[AakashGfude]

Thanks @oyamauchi for reporting this. Will have a look.

[AakashGfude]

Hi @oyamauchi @choldgraf, actually it's not a bug. But a limitation on the sidenote elements. The sidenotes are an inline span tag, so it cannot have other markup like bold or italic inside it.
Details on why span tag was chosen: #546 (comment)

EDIT: bold and italic are inline elements, so we can handle it inside span. Will try to fix it.

[s-bear]

I was just trying to figure out why a link was disappearing from a sidenote and found this. I wanted to add that I had equations in footnotes that broke when I enabled sidenotes. While attempting to fix things I disabled dollarmath and configured MathJax directly, which works. After reading this issue, I think it's because MathJax processes everything after Sphinx, so the dollar-delimited math regions survive the astext() call. Since MathJax works in sidenotes, I assume that whatever it does is also considered an inline element and shouldn't be stripped out?

With dollarmath:

Without dollarmath:

Source (Markdown, with the deflist extension):

$\mat{\Gamma} \in \RR^{N\times N}$
: is the Tikhonov matrix. $\mat{\Gamma} = \alpha \mat{I}$ yields the standard ridge regression, which penalises solutions with large L-2 norm and selects lower "energy" solutions. Setting $\mat{\Gamma} = \mat{I}\ast h$, where $\ast$ is convolution and $h$ is a high-pass filter kernel[^note-convolution], penalises solutions with content above $h$'s frequency cut-off and thus selects lower-frequency, smooth solutions.

[^note-convolution]: Here, $h \in \RR^{1 \times n}$ is a row vector and $(\mat{I} \ast h)\_{i,j}$ $= h\_{i-j+\lceil n/2\rceil}$, or zero if the index is out of bounds.

For posterity, note that I also had to escape the underscores (e.g. $= h\_{ ... }$) for this to render correctly after disabling dollarmath but that's (probably?) unrelated to the issue at hand. I also manually set my mathjax3_config in conf.py so that I can add tex macros. I added the 'inlineMath' entry to it after disabling dollarmath to get things working again:

mathjax3_config = { 'tex': {
		'inlineMath': [['$','$'],['\\(','\\)']], # added after disabling 'dollarmath'
		'macros': {
			'RR': '\\mathbb{R}', # real numbers
			'mat': ['\\mathbf{#1}',1], #matrix: bold, upright
			'trans': '\\intercal', #transpose T
		},
	}}