Closed oyamauchi closed 1 year ago
Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
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! :tada:
cc @AakashGfude could you look into this one? I think we might have a bug in the sidenotes code
Thanks @oyamauchi for reporting this. Will have a look.
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: https://github.com/executablebooks/sphinx-book-theme/pull/546#issue-1186418914
EDIT: bold and italic are inline elements, so we can handle it inside span. Will try to fix it.
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
},
}}
Context
When
use_sidenotes
is true and footnotes are converted to sidenotes, inline elements within the footnote content are stripped. Whenuse_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