Make core middlewares configurable (for e.g. custom Markdown tags)

[mik01aj]

Originally suggested in webuniverseio/sourcejs-react#5 (comment)

I'm not sure whether there would be any more use cases for that, aside the Markdown custom tags... Or maybe we could even narrow this to only handling the code in example in some special way.

[robhrt7]

From Gitter:

How do you think, If I'll add another type of plugin entry file that will be executed during markdown processing, will it be enough for you? I can do same as with middleware plugins, including plugins in specified step of the page rendering.

In plugins we have special convention for that:

core
    middleware/index.js - loaded in process of page rendering flow
    markdown/index.js - could follow the same logic, and be required during MD processing

If you feel that's enough, I can make a demo of this approach in the branch. This should cover previously mentioned scheme:

@szarouski, how do you think?

[webuniverseio]

@operatino 👍

[robhrt7]

I made markdown processing more configurable so it's now possible to define custom language renderers or re-define some parts of the (or whole) renderer. I decided that this is the safest way, which also will allow to do only small changes, instead of overriding whole markdown renderer.

Check this example plugin and it's install instructions https://github.com/sourcejs/sourcejs-example-md-extension.

Latest changes are available in 0.5.4-dev branch. @szarouski, @mik01aj, could you verify it?

[mik01aj]

@operatino I just downloaded and installed your example plugin and it works! :) I will now work on extending it.

[mik01aj]

I just published a new plugin for React. It is based on your example.

https://github.com/mik01aj/sourcejs-md-react

[robhrt7]

@mik01aj Great thing! Do you have plans to merge it with @szarouski plugin?

I will close this issue, since it's solved and working.

[webuniverseio]

@operatino I think our plugins should be kept separate. They are different - one allows to run specs as jsx, another to process jsx from md specs. I think both solutions are good and will find their users.

[mik01aj]

@operatino I think that this API could be refined. I had to put 4 declarations in options.js, and every user of the library will have to do it too... Furthermore, my solution is not perfect, as I keep the init code in some global vars, and it means that if you omit the jsx-init-server or any other init section, the SourceJS server will use whatever was used in the last displayed page. I thought that maybe I'd use a languageRenderer to reset these variables each time a new Markdown file is loaded, but didn't implement it yet.

I think that adding the custom parsers for MD code blocks should be the plugin's job, not the user's, just like adding new menu items.

[robhrt7]

@mik01aj I agree that it's not perfect, but I didn't found any other clean and simple solutions. It may become a mess if I'll have many includes around the codebase, that will require some convention-driven plugin files.

Another way was to allow plugins changing the options during app init, but it may be very dangerous, since could lead to unpredictable behaviour.

I wanted to keep clean customisation flow, when user knows what is overridden and could have control over that. Since you configure and install plugin only once (for the current instance, which is commonly used by whole team), it supposed to be not a big problem.

You can also do this kind of configuration, to minimize options:

module.exports = {
    core: {
        processMd: {
            languageRenderers: (require('sourcejs-md-react')). languageRenderers()
        }
        // ...
    }
    // ...
};

languageRenderers are then extended (not rewritten) in the core module, so you don't override other renderers with different names.

[mik01aj]

There is a problem with this middleware. When I put a block like this in my spec:

```jsx-component-init-common
```

The middleware receives triple ``` instead of an empty string.

[robhrt7]

Most likely this is an issue with marked https://github.com/chjj/marked, the original dependency that renders Markdown into HTML. Could you please do a synthetic test with it?

[mik01aj]

Ok, just reported.

But actually having a look at marked's code raises another question: what happens if I configure come language parsers, and then some other plugin overrides the renderer.code method? Or What happens if multiple plugins implement the same renderer method (e.g. header)? Which one is used then?