Internal extension system

[mrdrogdrog]

Is your feature request related to a problem? Please describe. Right now every function of the frontend is coded and bundled in this repo. That means that every new feature bloats up the code. Also some plugins like plantuml aren't needed by everyone.

Describe the solution you'd like @DerMolly and I propose that we introduce a plugin system. A dev gets everything they need to add new features to the markdown rendering (and maybe other aspects of the software?).

[mrdrogdrog]

Notes from a brainstorming of myself and @DerMolly:

How can somebody create new plugins?

We offer typescript interfaces that must be implemented. If it should be activated, then the dev(or admin or activeAllThisPlugins.sh script) modifies a file "plugin.ts", imports the plugin and uses a function like pluginSystem.activate(importedPlugin). If you then compile and bundle the frontend the plugin will be processed and included, too.

How can an admin configure a plugin?

We add a new key to the backend config file (the actual file that is used to configure hedgedoc). Something like frontendPluginConfig. This object is divided into more objects, that are meant for the plugins. The frontendPluginConfig-Object will be included into the config api call, that the frontend uses to get the settings. The frontend takes this object, and passes the right sub sections to the plugins. Example: backend config file:

{
    [...]
    'frontendPluginConfig': {
        'plantuml': {
            'server': 'plantuml.lol'
        }
    }
    [...]
}

[ccoenen]

related to https://github.com/codimd/server/issues/20

[SISheogorath]

Please be very careful with plugin systems.

Obviously they enable people to throw in all code they like. :tada: But they also enable people to throw in all code they like. :skull: And usually that code is crappy code. If it wouldn't be, it would be upstream and properly integrated.

It also basically invalidates every bug report that uses external plugins because either you end up debugging other people's plugins or you end up hunting ghosts. It requires a strong API definition for our own code and compatibility becomes an issue again.

It also causes potential license issues as HedgeDoc is licensed under AGPL, means also all plugin's source code most be linked somewhere. The easiest way to ensure that this is the case and things are accessible is by having them within our repositories or people run a fork. Otherwise we might end up only with links to our repository that doesn't actually provide all source code for an instance and therefore violates AGPL.

I would recommend to work with feature flags and integration of all extension during build-time instead of allowing external plugins. This makes everyone's lives easier.

[mrdrogdrog]

You're missunderstanding our intentions. We want this plugin system to make our own code more modular. Our primary goal is to provide plugins that are maintained by US.

We're not gonna publish an api spec before this system is mature enough.

[DerMolly]

So what do we need to provide in this interface?

• [ ] interface ComponentReplacer
  • This replaces dom-elements like <codimd-youtube></codimd-youtube> to a YouTubeFrame component
• [ ] interface MarkdownIt.PluginSimple | MarkdownIt.PluginWithOptions<T>
  • This let's us specify the markdownit plugins

What else do we need?

[mrdrogdrog]

I think we need an interface for replacers and for markdown it plugins. We don't always use regex.

[DerMolly]

We could simply add an optional MarkdownItPlugin interface and use that if provided or use the also optional RegexOptions if not. This way we could avoid repetition of the RegexPlugin…

[mrdrogdrog]

RegexOptions is already an interface from markdown-it-regex. You use it only with this plugin. I think it would be enough if our extension api has a method "add markdown it plugin", where you can provide a plugin (and it's config), just like with "md.use".

[mrdrogdrog]

We should work on this issue after #261 was implemented.

[DerMolly]

This is already implemented.

[ccoenen]

Oh, interesting! Is there anything I could take a look at?

[ErikMichelson]

You probably want to look at the already implemented extensions to get a gist of the structure: https://github.com/hedgedoc/hedgedoc/tree/develop/frontend/src/extensions/extra-integrations