Open mortenpi opened 1 year ago
shravanngoswamii
commented
1 year ago I would like to work on this issue and this also come under my expertise, Can I have some details like in which part of Julia Codebase should I do this? And I am really sorry to ask this newbie question as I am new to Julia and I am still trying to understand Julia Codebase and Documenter.jl!!
mortenpi
commented
1 year ago On the Julia side, the HTML for the footnotes is generated here:
In the rendering phase, Documenter essentially gets a big object representing the Markdown and then runs over that, generating the HTML. The entry point into HTMLWriter is here:
The Markdown elements are represented with MarkdownAST objects.
However, what could be a good first step is to take just the generated HTML, probably tidy it up, and then create a HTML/CSS/JS proof-of-concept directly in the HTML. Once we know what the HTML needs to look like, we can think about how to incorporate it into Julia.
shravanngoswamii
commented
1 year ago As you said, I created a HTML/CSS/JS proof-of-concept directly in HTML, Please let me know if i should change something or there is any mistake and if it is correct than what should be my next step in STEP. This is HTML code :- https://github.com/shravanngoswamii/Documenter-PR-Test Its Output :- https://shravanngoswamii.github.io/Documenter-PR-Test/
mortenpi
commented
1 year ago Yeah, that's a good start. I guess there is no good way to do this via pure CSS with a :hover? I guess it would be hard to control the positioning?
If we're going to do it via JS, I wonder if we can re-use the generated HTML for the footnote definitions (i.e. copy the DOM to the preview span as the JS triggers)? But we could also just duplicate the generated HTML, if that's easier.
For integration:
The CSS should live in the SCSS files here: https://github.com/JuliaDocs/Documenter.jl/tree/master/assets/html/scss
To update the generated CSS, you need to call the DocumenterTools package. You can re-use the docs/ Julia environment with something like this:
$ julia docs/instantiate.jl
$ julia --project=docs/
julia> using DocumenterTools
julia> DocumenterTools.Themes.compile_native_themes()This should then take your changes to the SCSS files and update the compiled CSS files.
goerz
commented
9 months ago I strongly feel that this feature should be primarily implemented via JS, primarily for usability and accessibility reasons. Ideally, a Documenter page should be useable in a browser without JS script (e.g., a terminal browser like w3m), or a screenreader. See also my comment at https://github.com/JuliaDocs/Documenter.jl/pull/2394#issue-2069583911
Showing footnotes on hover is exactly the kind of UI sugar you'd want in a full browser. At least arguably, though, you wouldn't want footnotes inserted into the basic non-JS rendering of the page, and then appear multiple times.
This applies even more so to https://github.com/JuliaDocs/DocumenterCitations.jl/issues/67
Since I'd be reluctant to add JS to DocumenterCitations (at least not until we implement a way for plugins to automatically inject CSS/JS), I'd want to reuse any implementation of this footnote-hover for the citation-hover.
mortenpi
commented
9 months ago It seems like we could just have a single hidden-by-default div that renders the footnote, and we copy the DOM from the real footnote into that div whenever we trigger a hover event over the footnote reference. This way we'd keep the original footnotes around on the bottom of the page.
shravanngoswamii
commented
4 months ago I added a span (hidden by default) for footnote preview and also added styling for its appropriate positioning but I am not able to get the footnote definitions in that span! Can you please just have a look at these changes and see if it's fine this way: https://github.com/JuliaDocs/Documenter.jl/compare/master...shravanngoswamii:Documenter.jl:footnote-preview
It's looking like this:
@mortenpi
mortenpi
commented
4 months ago Would have to test that on a live site, but HTML/CSS-wise I think it looks quite fine.
For getting the definitions, you'd have to modify HTMLWriter some more. Currently, I think we just gather them up as we go through the tree, since we only need them at the end:
It's a bit tricky, since for rendering them inline, we need to know the definitions when we encounter the reference. I'd be okay if we'd do another pre-pass through the tree before actually rendering, to gather up the definitions. That seems to be the simplest solution.
shravanngoswamii
commented
4 months ago For getting the definitions, you'd have to modify HTMLWriter some more. Currently, I think we just gather them up as we go through the tree, since we only need them at the end:
It's a bit tricky, since for rendering them inline, we need to know the definitions when we encounter the reference. I'd be okay if we'd do another pre-pass through the tree before actually rendering, to gather up the definitions. That seems to be the simplest solution.
I used JQuery instead for fetching footnote definitions from the end of page and its working fine! I opened a PR for it, let me know if any changes are required!
I.e. something like this
Example is from a Quarto document: https://mixtape.scunning.com/02-probability_and_regression#fnref1
Would be really handy, and a nice self-contained front-end feature for someone to take on.