Add Tips about Registering reveal.js submodule for gh-pages slide hosting

[jaredmorgs]

I've put the call out on https://twitter.com/jaredmorgs/status/608570379586535424 about getting the reveal.js submodule working on my newly created Reveal deck from the Asciidoctor Presentation (damn, I love this slide tech!).

https://github.com/jaredmorgs/Asciidoctor_Presentation/tree/gh-pages

Reveal is such a cool slide technology, and it would be great to enable users with some tips about getting the submodule working correctly on gh-pages.

Also, as a self-serving requirement, I want to include this in my Asciidoctor Reveal JS presentation I'm working on, and it would be sweet to dogfood both the slides source and the hosted deck on GitHub.

[obilodeau]

Dan and I already have such setups. Check my slides repository and I think his is named decks.

I can document my workflow using git submodules. I think Dan's is using bower.

The cool thing with submodules is that you can point to your own fork of the asciidoc-reveal.js repo very easily which in useful right now since you often need to modify the back-end to implement currently unsupported features. More often than not these features will land in the repository it's just that you don't have time to submit them proper because the presentation is the next day 😋

[mojavelinux]

The cool thing with submodules is that you can point to your own fork of the asciidoc-reveal.js repo very easily

My understanding is that bower can do this as well since bower just grabs code from GitHub.

Either way, I think the documentation should be very clear about how we recommend managing reveal.js. Perhaps we can document both options, submodules and bower. For most mortals, submodules are absolutely horrible to use, so I think bower should be the main recommendation.

[mojavelinux]

Reveal is such a cool slide technology, and it would be great to enable users with some tips about getting the submodule working correctly on gh-pages.

:+1:

[jaredmorgs]

Hey @mojavelinux I've noticed you're broadcasting a fair bit about a new slide technology. Does this new slide tech work around some of the submodule issues revealed here?

If not, what recommendations should we offer regarding bower?

(and yes, I realise how stale this issue is - I'm only just getting back into community docs work)

[mojavelinux]

Does this new slide tech work around some of the submodule issues revealed here?

Yes, because unlike reveal.js, it actually uses a package manager (npm) to distribute add-ons and it isn't monolithic like reveal.js, so it actually has third-party plugins as a core part of how it works.

I still think Bower is the right way to go for reveal.js. Here's the command to install it:

bower install reveal.js

To get Bower, you use:

npm install -g bower

Here's an article on getting npm setup to user space (without sudo rights): https://topaxi.codes/use-npm-without-root-or-sudo-rights/

The path to reveal.js must then be set using an Asciidoctor attribute:

asciidoctor -a revealjsdir=bower_components/reveal.js \
  -T asciidoctor-reveal.js/templates/slim slides.adoc

If we setup Bower in the asciidoctor-reveal.js repository (and optionally register it with Bower), then we could use Bower to fetch the templates too.

[mojavelinux]

I filed #57 to get this repository setup to work with Bower.

[obilodeau]

Now that asciidoctor-reveal.js is packaged as a Gem and npm ;) and that Bower is officially recommending yarn, how should we approach this documentation?

I have a very specific concern about bower, yarn and such asset management things related to github pages: won't your repository grow insanely if you would have the habit to patch your theme from time to time between presentations?

With git submodules it stays external and you can point to the proper commit id presentation and git/github will take care of the rest.

I really dislike git submodules but I don't see anything else that is supported by gh-pages and that we could use right now.

[mojavelinux]

npm / yarn allows you to set a specific version, even a specific commit of a repository. So it's like a gitsubmodule without any pain.

See https://stackoverflow.com/questions/14187956/npm-install-from-git-in-a-specific-version

That's why bower is dead.

[obilodeau]

No matter the npm / yarn situation, isn't it the case that github pages doesn't support any of these assets manager meaning that you still need to copy everything in the tree which will blow up it's size linearly for everything presentation you do where you tweaked the theme?

Thinking about it, git is great at content tracking (and thus deduplication of redundancy in identical source files) so maybe the only concern is providing a good .gitignore to ignore all build requirements and make sure to only keep files useful for a proper browser render.