|
| 1 | +## Using Markdown-it with plugins |
1 | 2 |
|
2 | | -## Markdown plus Mathjax readme |
3 | | - |
4 | | -Most of the packages are in there to try to match what the OSF wiki is doing. The two exceptions being markdown-it-highlightjs.js and markdown-it-mathjax.js. The highlighter matches the functionality of what is on the osf however, and the markdown-it-mathjax.js increases functionality with mathjax. |
5 | | - |
6 | | -to get all the libraries needed: |
7 | | -Note: You do not need to use npm, you can easily get them off of github. |
| 3 | +If we had `npm`, here were the would-be configuration. |
8 | 4 |
|
9 | 5 | ```bash |
10 | 6 | |
|
15 | 11 | |
16 | 12 | ``` |
17 | 13 |
|
18 | | -github: |
19 | | - |
20 | | -https://github.com/cos-forks/markdown-it-toc |
21 | | -https://github.com/valeriangalliat/markdown-it-highlightjs |
22 | | -https://github.com/brianjgeiger/markdown-it-ins-del |
23 | | -https://github.com/svbergerem/markdown-it-sanitizer |
24 | | -https://github.com/classeur/markdown-it-mathjax |
25 | | - |
26 | | -To add a new library, you need to make sure its loadable in md.js somehow, either through exporting via `root.<name>` or some other means. Some of the markdown plugins added have custom code in them to load them into `root`. |
27 | | - |
28 | | -Libraries should try to use the same version as the ones used on the OSF. The plugins do not matter as much, but `markdown-it` and `Mathjax` you should try to match exactly because styling can change between versions. |
29 | | - |
30 | | -To add a new library that is not already set up to export to `root` can be a bit tricky but the gist of it is, wrap the plugin in this code: |
31 | | - |
32 | | -```javascript |
33 | | -;(function (root, factory) { |
34 | | - if (typeof exports === 'object') { |
35 | | - module.exports = factory() |
36 | | - } else { |
37 | | - root.<PLUGIN_NAME> = factory() |
38 | | - } |
39 | | -})(this, function () { |
40 | | - |
41 | | - |
42 | | - return function(md){ |
43 | | - |
44 | | - ..... |
45 | | - } |
46 | | - |
47 | | -}) |
48 | | -``` |
49 | | - |
50 | | -And then modify it to work in this context. See other plugins for examples. |
51 | | - |
52 | | -Then in md.js, you can add a plugin to the markdown renderer by adding a `.use(window.<PLUGIN_NAME>)` after loading the file into `viewer.mako`. |
| 14 | +For MFR, a customized local copy of each script is stored in the extension's static folder. There are a few issues: |
| 15 | + |
| 16 | +* ES5 compatibility: use [Babel](https://babeljs.io/repl/) to convert ES6 `markdown-it-highlightjs` to ES5. |
| 17 | + |
| 18 | +* `require` is NOT available. For `md.js` to be able to load these libraries, customization is necessary to export via `root.<PLUGIN_NAME>`. |
| 19 | + * `markdown-it` and `markdown-it-sanitizer` are already set up to be exported code. We load the `min` version directly. |
| 20 | + * `markdown-it-toc`, `markdown-it-highlightjs`, `markdown-it-ins-del` and `markdown-it-mathjax` are not. Here is the wrapper: |
| 21 | + ```javascript |
| 22 | + (function (root, factory) { |
| 23 | + if (typeof exports === "object") { |
| 24 | + module.exports = factory(); |
| 25 | + } else { |
| 26 | + root.<PLUGIN_NAME> = factory(); |
| 27 | + } |
| 28 | + }) (this, function () { |
| 29 | + return function(md/*, optional arguments*/) { |
| 30 | + /* library code */ |
| 31 | + } |
| 32 | + }); |
| 33 | + ``` |
| 34 | + |
| 35 | +Here is a list of original copy of the scripts we use: |
| 36 | + |
| 37 | +* [markdown-it@08.4.0](https://github.com/markdown-it/markdown-it/blob/8.4.0/bin/markdown-it.js) |
| 38 | +* [markdown-it-sanitizer@0.4.3](https://github.com/svbergerem/markdown-it-sanitizer/blob/v0.4.3/dist/markdown-it-sanitizer.min.js) |
| 39 | +* [markdown-it-mathjax@2.0.0](https://github.com/classeur/markdown-it-mathjax/blob/v2.0.0/markdown-it-mathjax.js) |
| 40 | +* [markdown-it-toc@1.1.1](https://github.com/cos-forks/markdown-it-toc/blob/1.1.1/index.js) |
| 41 | +* [markdown-it-ins-del@1.0.0](https://github.com/brianjgeiger/markdown-it-ins-del/blob/1.0.0/index.js) |
| 42 | +* [markdown-it-higlightjs@3.0.0](https://github.com/cslzchen/markdown-it-highlightjs/blob/release/3.0.0/index.es5.js) |
0 commit comments