Support third-party reveal.js plugins

salim-b commented 4 years ago

I'm maintaining a tiny little project named revealjs-tpl, a ready-to-go file compilation to create a reveal.js presentation using Pandoc.

Since reveal.js is quite popular, there exists a wide range of unofficial third-party plugins besides the built-in ones.

I've recently added support for the following third-party reveal.js plugins in my custom pandoc template:

These three plugins are quite general-purpose and probably useful to many if not most Pandoc users creating reveal.js presentations.

Therefore I'm thinking about upstreaming the relevant template changes into the default reveal.js template. To do so, I would introduce an additional template variable PLUGINNAME.url (e.g. elapsedtimebar.url) besides the other plugin-specific template variables to define the base path/URL to the relevant asset files (analogous how revealjs-url works).

Before I create a PR, I'd like to know what you (@jgm an others)

generally think about adding support for unofficial reveal.js plugins in the default template. Is that even desired?
particularly think about the proposed PLUGINNAME.url approach to define the base path/URL to the plugin files and possibly other technical details.

Thanks for your feedback!

jgm commented 4 years ago

on 2: since we'd have no way of knowing all the possible pluginnames when rendering the template, how would we iterate over the different pluginnames? Is the idea

custom-plugins:
  elapsedtimebar:
    url: foo?

salim-b commented 4 years ago

since we'd have no way of knowing all the possible pluginnames when rendering the template, how would we iterate over the different pluginnames?

I don't think it makes much sense to iterate over third-party plugin names since most of them need "special treatment":

Not all plugins are compatible with the plugin registering mechanism introduced in reveal.js 4 (Reveal.initialize({plugins: [...]})) and therefore need to be loaded differently.

Elapsed-Time-Bar is such an example: I could only get it to work by loading its JS file using <script defer> and not registering it in the plugins array.

On the other hand, Spotlight and Verticator do not work when their JS files are loaded using the defer option as recommended by the reveal.js documentation, so they have to be loaded without it.
Some plugins also bring their own CSS file besides their JS file. Verticator is such an example.
Many plugins introduce their own reveal.js config options which can/must be set inside Reveal.initialize({...}). This is the case for all of the three plugins listed above.

Even more complicating: The hierarchy of these additional options tends to vary across plugins. Compare for example the additional options introduced by Elapsed-Time-Bar on one hand and those from Verticator on the other hand:
```
Reveal.initialize({
  // Elapsed-Time-Bar options
  allottedTime: 15 * 60 * 1000,
  progressBarHeight: 3,
  barColor: 'rgb(200,0,0)',
  pausedBarColor: 'rgba(200,0,0,.6)',

  // Verticator options
  verticator: {
    darktheme: true,
    color: '',
    oppositecolor: ''
  }
})
```
For some plugins it makes a lot of sense to define additional keyboard shortcuts inside Reveal.initialize({keyboard: {...}}).

Toggling the presentation mode the Spotlight plugin introduces would be such an example.

Of course, when adding support for these plugins to Pandoc's default reveal.js template, I would ensure that non-users of these plugins wouldn't be affected by plugin-specific config additions (more or less how my current template works).

mb21 commented 4 years ago

Just an idea: if doctemplates had a toJSON: partial or similar, we wouldn't have to hard-code all those things, right?

jgm commented 4 years ago

I see. I think I'd rather not support third-party plugins in the default template, then, unless there's a very generic way of doing it that won't require ongoing maintenance as the plugins change, etc.

salim-b commented 4 years ago

I think I'd rather not support third-party plugins in the default template, then, unless there's a very generic way of doing it that won't require ongoing maintenance as the plugins change, etc.

Ok, I fully understand. I don't see any generic way to support the above mentioned three plugins, so I'll close this issue.

Of course, people can always use my custom template (and I plan on keeping it updated for the forseeable future).

Just an idea: if doctemplates had a toJSON: partial or similar, we wouldn't have to hard-code all those things, right?

Sorry, I can't follow (don't know much about Pandoc's internals). Feel free to re-open the issue, though.

finnito commented 3 years ago

Hi all, I'd like to re-open this issue. I am glad we are moving forward to Reveal.JS 4.x but the inability to add third-party plugins is quite frustrating. I use a few basic but crucial plugins to upgrade my slides for my teaching.

plugins: [
...
]

All I think is needed is the ability to add objects to the plugins array in the config. Everything else can be done within the plugin.

Is there a way forward here?

salim-b commented 3 years ago

All I think is needed is the ability to add objects to the plugins array in the config. Everything else can be done within the plugin.

For a lot of plugins, this unfortunately doesn't seem true as I outlined above.

Is there a way forward here?

You could simply adapt Pandoc's default reveal.js template to your needs. See this custom one for an example (I've wrapped all the modifications in $-- BEGIN custom section/$-- END custom section comments for clarity).

arrowd commented 3 years ago

According to revealjs documentation, code highlighting feature (which seems pretty basic for me) can be enabled by simply listing the plugin name in plugins. I don't quite get why not implement

plugins: [
...
]

thing, as it would enable at least some plugins when using through Pandoc.

jgm commented 3 years ago

You don't really need the code highlighting plugin, since pandoc has built-in highlighting.

arrowd commented 3 years ago

Yes, but built-in highlighting != revealjs highlighting. For instance, there is no way to highlight only specific lines of the code block. The set of available styles is different. Finally, the default revealjs black theme has different background color than pandoc styles (I tried only breezedark, though) - they are both black, but one is darker than another it looks ugly.

jgm commented 3 years ago

See @salim-b's May 28 comment above for the difficulties in this. Unless there's a way around these difficulties, I'm still inclined not to support plugins.

Note also that you can always use a custom template.

We could perhaps make an exception for highlighting, if the highlighting plugin isn't subject to any of the difficulties noted above. (Does it need special CSS? Does it need special config options?)

arrowd commented 3 years ago

@salim-b talks about "complex" plugins. The highlighting plugin is trivial. It does require custom CSS, but Pandoc already supports header-includes, which can be used for this.

Other than that, there are no other configurable options. The whole thing boils down to

<link rel="stylesheet" href="lib/css/monokai.css">
<script src="plugin/highlight/highlight.js"></script>
<script>
  Reveal.initialize({
    plugins: [ RevealHighlight ]
  });
</script>

jgm commented 3 years ago

I'll reopen this for further consideration.

Industry-Standard commented 2 years ago

New eyes looking at this - does the revealjs-url parameter not provide the ability for the user to choose their own plugins and provide a reveal.js folder with plugins / css / etc preconfigured? In my testing, it looks like some things are brought over from the reveal.js folder structure, but things like plugins and init javascript are not.

Based on the documentation, that's what my assumption is; if I'm passing in a specific location to the reveal.js content, then I'm providing the base configuration for reveal.js with whatever plugins / css / etc I've packaged together. Let the user build their template with the revealjs project files the way they want them, then just insert the pandoc'd slide output into that (as opposed to using the baked in template).

Right now, to accomplish something similar, I'm postprocessing to take content from the pandoc'd output and insert it into a local reveal.js directory.

Dabsunter commented 2 years ago

About the highlighting, we only need to add a couple lines to the template : https://github.com/Dabsunter/pandoc-userdata/blob/master/templates/default.revealjs#L94 https://github.com/Dabsunter/pandoc-userdata/blob/master/templates/default.revealjs#L318

Also, I know there is a lua plugin for that, but it seems there would be very little job to get the highlight animations work through the code block attributes natively https://revealjs.com/code/

jgm / pandoc

Support third-party reveal.js plugins #6401