Ship remarkjs JavaScript dependencies for offline use

[gadenbuie]

Related to #245 and inspired by a recent cross-country flight, I propose that we include the remarkjs JavaScript dependencies in the package for offline use.

Maybe we should because:

• It's common practice in and expected by users of other R Markdown packages
• Slides without other external dependencies can be presented or worked on offline easily
• It helps decouple xaringan from upstream changes
• 90% of slides presented at conferences by speakers who are traveling are edited mid-flight^**

Maybe we shouldn't because:

• Local (offline) MathJax isn't enabled in xaringan (source)
• Using GitHub or online fonts will cause issues if fonts aren't available locally

Any other reasons for/against?

And if it's agreeable, I'll be happy to take on the PR.

---

^{** I made this statistic up, but I think we all know it's true.}

[cderv]

Hi @gadenbuie ,

just to be sure, do you consider here that xaringan::summon_remark() that allows you to download a version of remark.js for your slide is not enough to insure a proper offline usage when needed ?

Usually I use that when I want to be sure that it works offline and also to block the remark version in time.

I guess offline mode is currently opt-in for user and not default, and one should not forget to summon its remark version 😄

I think one version included could be a way to help that, but one reason against I see is it would also means some more maintenance as the evolution of remark;js would need to be follow closely to decide when it should be updated. Currently, not being decoupled, offer the latests feature of remark.js, with the cost of fixing as needed when someone reports it 😅

[gadenbuie]

do you consider here that xaringan::summon_remark() that allows you to download a version of remark.js for your slide is not enough?

I think that this is helpful for advanced users. On the other hand, I think the most user-friendly approach is to make the defaults easy and to allow advanced users to be the ones to opt-in to a different approach. This is the common across R Markdown packages — for example, pagedown ships its major dependencies.

This is the argument I feel most strongly about. I think that shipping the dependency is best for xaringan users.

I think one version included could be a way to help that, but one reason against I see is it would also means some more maintenance as the evolution of remark;js would need to be follow closely to decide when it should be updated

We've already pinned the default to remarkjs version 0.14 in #247. Given that remarkjs has been "stable" (as in, not changing) for so long, there are a lot of expectations around how xaringan works. Upstream changes are almost certainly not going to take into account our user base unless we start participating in the remarkjs repo more carefully.

Overall, I see this point as being a positive: decoupling from the latest version of remarkjs gives xaringan time to react to upstream changes without having to worry about constantly needing to plug holes.

[cderv]

This is the argument I feel most strongly about. I think that shipping the dependency is best for xaringan users. (...) We've already pinned the default to remarkjs version 0.14

It is the case also for revealjs in its package. I can see the advantage having a default fixed version, while advanced user can always easily summon a newer.

@yihui, was there a specific reason you did not include a version of the library inside the 📦 ? What do you think on this one ? Thank you.

[yihui]

Yes, it is common for R packages to bundle JS libraries. I guess xaringan is the only exception. The reasons why I didn't do it were:

1. It started as a personal and fun package. I didn't imagine it to be used so widely. Personally I don't worry if my slides work offline, since most of my slides have to be viewed online. Occasionally I also work on slides on flights, but I have downloaded a copy of remark.js locally. Pretty much all my slides are in the same folder, using the same remark.js file (https://slides.yihui.org/remark/0.14.1.min.js).

2. Bundling a copy of remark.js in xaringan means more maintenance work. If anything is broken, I either have to fix it by myself, or try to upgrade remark.js if it is a bug fixed upstream, and the latter could introduce more problems.

3. Without pointing to the latest version of remark.js, I doubt if anyone would test newer versions of remark.js at all, and it is quite likely that we will be stuck in a certain old version for years, which means it will be harder and harder to try new versions of remark.js. There are certain things that I want from newer versions, such as https://github.com/gnab/remark/commit/29515556 (so I can get rid of my hack 8a13af555ec41f4003686988e7cbad637b4e6415).

4. The size of xaringan package is about 55K, and remark.js 0.14.1 is 665K (0.15.0 is 960K).

Reasons 1 and 4 are minor. 2 and 3 are selfish: the work is hard for me (I don't even know how to write tests for newer versions of remark.js), but the workaround is relatively easy for users.

I have added a note in the documentation to remind users of downloading a copy of remark.js via 96793965cdd04f4635ede7e18c3b1ca56b000cb8, but I doubt if any user would notice it on the help page. Perhaps we can emit a message (once per session) as a reminder?...

[tcgriffith]

3. Without pointing to the latest version of remark.js, I doubt if anyone would test newer versions of remark.js at all, and it is quite likely that we will be stuck in a certain old version for years, which means it will be harder and harder to try new versions of remark.js

I use xaringan for all my slides and I expect it to be reliable and stable. I welcome new features only if they don't break my existing slides. As xaringan gains popularity. I suspect people will demand more stability from xaringan.

[yihui]

@tcgriffith I agree.

[pat-s]

Without pointing to the latest version of remark.js, I doubt if anyone would test newer versions of remark.js at all, and it is quite likely that we will be stuck in a certain old version for years, which means it will be harder and harder to try new versions of remark.js. There are certain things that I want from newer versions, such as gnab/remark@2951555 (so I can get rid of my hack 8a13af5).

I'm sure there would be people who would try this. Also in the end this is a task for maintainers (multiple people, not you alone) to move forward. Currently the releases of remark are a bit messed up (the Github release is tagged v0.15.0 but is in fact 0.14.1 and remark-latest.js points to v0.14.1). Development does not really look professional right now.

If we keep pointing to remark-latest.js the next issue related to a remark release happening over night is just a matter of time. I'd highly prefer to point to a release version.

[yihui]

I think they will be much more careful next time. I can pin the the version of remark.js to 0.14.1 again if anything breaks in remark-latest.js in future.

[pat-s]

Your choice in the end 😄 Just pointing out my concerns which only and always aim to make things better (for everyone hopefully) :)

[yihui]

Thanks! Those are totally valid concerns. I promise I'll pin the version next time :) I just want to give the new remark.js maintainers one more chance. I believe they will become more professional.

[Charango-Chile]

Hi guys,

The pain is real, effectively working on planes or presenting as a guest in a place where you don´t have internet connection is more common than you think and a problem if you decide to incorporate equations... That really leads me to use LaTeX's prosper as I usually use maths on my presentations, but on the other hand I really like the simplicity of Xaringan...

So... Any plan to add offline support for features that otherwise require an internet connection?

Cheers, Jose

[yihui]

@Charango-Chile https://bookdown.org/yihui/rmarkdown/some-tips.html#working-offline

[BastienFR]

I just want to add that this problem is not limited to people on a plane. I work within a corporate secure environment with no access to internet. Apart from downloading the package, I don't have access to internet, not even to use the function xaringan::summon_remark(). When I try to compile the xaringan slide, I get a small box with plain text on the left and an error about google font.

I would have loved to use xaringan to document my R analysis like I did before in an online environment. However, it's either impossible or too complicated. I just wanted to add my 2 cents here in case this discussion comes back up again. Thanks.