numbered equations and figures

[lheagy]

In a fair amount of academic writing, it is helpful to have numbered equations and figures so that they can be referenced in the text of the document. Is it possible to have "labeled" equations and figures so that they can be referenced and hyperlinked throughout Jupyterbook? On a related note, can captions be added to figures?

[choldgraf]

good question! I believe we could pretty-easily get the MathJax configuration to number equations:

http://docs.mathjax.org/en/latest/tex.html#automatic-equation-numbering

That'd require us making it possible for people to specify their own mathjax configuration in the config.yml file. I can see that taking two forms:

1. We let people somehow override the default mathjax configuration entirely.
2. We expose specific parameters that people can set themselves (e.g. number_equations: true)

what do you think?

re: your second point, that'd require us adding some new behavior to the markdown generation process, I believe!

[lheagy]

I am wondering if we can do something similar to the markdown extensions used by bookdown: https://bookdown.org/yihui/bookdown/markdown-extensions-by-bookdown.html#equations. Then all of the internal referencing is hooked up.

It looks like they have similar support for Figures with captions: https://bookdown.org/yihui/bookdown/figures.html

I haven't yet looked into how they are doing this under the hood - but worth checking out

[choldgraf]

Hmmm - I think bookdown uses RMarkdown for its markup...we could use pandoc and achieve something similar (see #94 for example), but I'm not sure that we'd have the development bandwidth to implement our own custom markdown syntax. What do you think?

re: captions I think the same applies here. You could use pandoc to include things like captions etc. That said, what's the way that a person would express the caption contents etc when using a jupyter notebook. Cell metadata maybe?

[lheagy]

Yeah, I agree that we don't want to develop and maintain our own language. Restructured text + sphinx has this capability (e.g. Page on Maxwell's equations). Do you think that supporting rst content has significant overhead?

[choldgraf]

nice! in that case, it's just a question of whether nbconvert can handle the conversion process. Have you tried using rST in a notebook w/ jupyter-book now? Does it not work?

[lheagy]

I haven't yet tried it, but I can create a minimal example and give it a go :)

[mathnathan]

I am interested in utilizing equation numbering as well. Please let us know your findings as they become available, @lheagy.

[dhruvbalwada]

Am I facing a related problem -
I just uploaded a jupyter-book, and the math is not rendering properly. Additionally, note the weird table appearing at the bottom of the page
https://dhruvbalwada.github.io/SFM_notes/files/inertial_ranges_Kolmogrov.html
, which is not part of my md files, as far as I can tell. It is coming from using something like $| asd |$.

[choldgraf]

@dhruvbalwada hmm - that actually looks different, I bet there is some uncommon notation in there (not uncommon in mathematics, but probably uncommon in people using markdown with mathjax).

Could you try updating to the master branch and trying it again, by any chance? On master we're now converting the notebooks directly into HTML instead of converting them to Jekyll Markdown and then to HTML, which means that we should (theoretically) get the exact same experience as one would get using nbconvert.

[dhruvbalwada]

@choldgraf - I am not sure I understand your suggestion to update to the master branch. I only have one branch, which is the master branch. So all changes are made directly to it. Should I delete the _sites folder before uploading? I have been using the docker method to see the changes locally before updating, which creates the _sites folder.

The repo is here - https://github.com/dhruvbalwada/SFM_notes
P.S. - I am not a pro githubber.

[dhruvbalwada]

I found my solution here -
for capital greek letters atom-community/markdown-preview-plus#336
for absolute sign yzhang-gh/vscode-markdown#318

@choldgraf Thanks for point out that it could be an issue with uncommon notation in markdown.

[choldgraf]

that's great to hear :-) Markdown + mathjax are notoriously finnicky especially for equation-heavy content like yours (which looks cool!)

[dhruvbalwada]

Would be nice to add links to some tutorials on using math with markdown, to the documentation of jupyter-book.

…

On Fri, Aug 2, 2019 at 9:38 PM Chris Holdgraf ***@***.***> wrote: that's great to hear :-) Markdown + mathjax are notoriously finnicky especially for equation-heavy content like yours (which looks cool!) — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#95>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AELEJQR4QNIL2EPB6YLNI63QCRLYJANCNFSM4GUOXWRQ> .

-- Dhruv Balwada Postdoc Courant Institute of Mathematical Sciences New York University

[gureckis]

Being able to referenced numbered equations, sub-sections of a book chapter, other chapters, or figures is a pretty important selling point for tool for book authors. It is very hard to write things when you have to keep going back to change the references (especially in the Jupyter cell based interface). I noticed that the Jupyter contributed extension "Table of Contents" appears to create dynamically updated section numbers in the authoring environment. Similarly, I wonder if there could be a "jupyter-book authoring tools" extension to jupyter that would handle these references and resolving the correct numbers, etc... all directly within in the jupyter interface. This would help authors a lot and would hybridize a wysiwg type authoring interface with one that is like latex.

[choldgraf]

I think this is an awesome idea - would love to see some tooling in Jupyter Lab to improve authoring

[leotrs]

I am interested in using jupyter-book to release interactive versions of my scientific papers, and without equation numbering I don't see how I would be able to do this.

[NatalieZelenka]

I'm thinking of trying to add the option figure captions as this would be useful for me. I'm trying to get a feel for where I might need to jump in to do this. Is the page_html() function used to convert markdown files as well as jupyter notebooks? If not, where are the .md files converted to html? Thank you!

EDIT: I've had a little bit more of a look now and it seems like it gets converted by jekyll. I'd really like it if it could work the same way as pandoc, ![Where this tag is the caption](url/of/image), but I'll see how much trouble that is...

[choldgraf]

Hey @NatalieThurlby I think that this is actually going to be easier to fix in a new backend for Jupyter Book that we are working on - you can check it out here: beta.jupyterbook.org and the repository where we're working on it is here: https://github.com/ExecutableBookProject/cli I think that equation numbering should now work already! (https://beta.jupyterbook.org/use/math.html)

[NatalieZelenka]

Hi @choldgraf Thanks, that looks interesting! I feel like I'm quite close to getting my solution to work, though. I am trying to use jekyll pandoc as the markdown converter for the jupyter book instead of kramdown.

I've tested jekyll-pandoc on a regular (non Jupyter Book) jekyll site and it's working as expected (it converts ![this bit](img.png) to something including`

this bit).

However, when I build + serve the jupyter book (jupyter-book build ., make serve), I can see that it's instead <img ... alt="this bit">. I am trying to figure out what's happening by looking at build.py and page.py - is it that regular markdown files (such as features/markdown.md in the demo/minimal book), are exported to html by nbconvert rather than Jekyll?

As an experiment, if I run jekyll build in the demo book directory, I get <figcaption> in the _site directory, but if I run jupyter-book build, I get alt= in the _build directory.

[choldgraf]

yep - that does sound like the reason you're running into this issue. Jekyll is actually not doing any markdown parsing - that is all being done by nbconvert -> html, and jekyll just stitches the pages together (the reason we did this was to ensure that markdown -> html would behave the same as it does with jupyter notebooks).

[choldgraf]

also, just to clarify what I mentioned above, most likely the current version of jupyter book will become a "legacy" version that doesn't get a ton of support. New features, bugfixes, etc will come to the new beta version that uses Sphinx. Just wanna give you a heads up about that

[choldgraf]

Closing as this should be superceded by beta.jupyterbook.org