Merge pull request #217 from marp-team/plugin-interface

Make public generating method of Marpit plugin

.eslintignore

@@ -4,3 +4,4 @@ docs/
 lib/
 node_modules
 jsdoc/
+plugin.js

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Added
+
+- `@marp-team/marpit/plugin` for creating Marpit plugin ([#214](https://github.com/marp-team/marpit/issues/214), [#217](https://github.com/marp-team/marpit/pull/217))
+
 ### Changed
 
 - Upgrade dependent packages to the latest version ([#211](https://github.com/marp-team/marpit/pull/211), [#213](https://github.com/marp-team/marpit/pull/213), [#216](https://github.com/marp-team/marpit/pull/216))
@@ -11,6 +15,7 @@
 ### Removed
 
 - CI test against EOL Node 8 ([#216](https://github.com/marp-team/marpit/pull/216))
+- `Marpit` prefixes in the name of some type definitions for TypeScript ([#217](https://github.com/marp-team/marpit/pull/217))
 
 ## v1.4.2 - 2019-11-06
 

api.md

@@ -1,27 +1,53 @@
 # [Marpit API](https://marpit-api.marp.app/)
 
-The documentation of Marpit API on `master` branch has been published at **[https://marpit-api.marp.app/](https://marpit-api.marp.app/)**.
+The documentation of Marpit API (on `master` branch) has been published at **[https://marpit-api.marp.app/](https://marpit-api.marp.app/)**.
 
-Please run `yarn jsdoc` if you want to build documentation at local. It would build docs in `jsdoc` directory.
+> Please run `yarn jsdoc` if you want to build documentation at local. It would build docs in `jsdoc` directory.
 
-## Classes
+## Documentations
+
+### Classes
 
 **Classes** section is documented about public classes.
 
-We are provide **[`Marpit`](Marpit.html)** class by default export.
+We provide **[`Marpit`](Marpit.html)** class by default export.
 
 ```javascript
 import Marpit from '@marp-team/marpit'
 ```
 
-And the all classes can use with named export.
+And all classes can use with named export. (Recommend if you are using TypeScript)
 
 ```javascript
 import { Element, Marpit, Theme, ThemeSet } from '@marp-team/marpit'
 ```
 
-### For development
+### Modules _(for internal)_
 
 **Modules** section is documented about internal modules, that is includes plugins of markdown-it and PostCSS.
 
-Basically, _Marpit user should not use module directly._
+Basically _Marpit user should not use internal module directly._
+
+---
+
+## Create plugin
+
+Are you interested to develop third-party plugin for Marpit?
+
+### [markdown-it](https://github.com/markdown-it/markdown-it) plugin
+
+Marpit's plugin interface has compatible with [markdown-it](https://github.com/markdown-it/markdown-it). [Please refer to the documentation of markdown-it](https://github.com/markdown-it/markdown-it/blob/master/docs/architecture.md) if you want to manipulate the result of Markdown rendering in plugin.
+
+### Marpit plugin
+
+When plugin was used through [`Marpit.use()`](Marpit.html#use), it can access to current Marpit instance via `marpit` member of the passed markdown-it instance.
+
+`@marp-team/marpit/plugin` provides a helper for creating Marpit plugin. A generated plugin promises an existance of `marpit` member.
+
+```javascript
+const plugin = require('@marp-team/marpit/plugin')
+
+module.exports = plugin(({ marpit }) => {
+  // Plugin code (Add theme, define custom directives, etc...)
+})
+```

index.d.ts

@@ -1,29 +1,42 @@
-declare module '@marp-team/marpit' {
-  interface MarpitOptions {
+declare namespace MarpitEnv {
+  interface HTMLAsArray {
+    htmlAsArray: true
+    [key: string]: any
+  }
+}
+
+declare namespace Marpit {
+  interface Options {
     container?: false | Element | Element[]
-    headingDivider?: false | MarpitHeadingDivider | MarpitHeadingDivider[]
+    headingDivider?: false | HeadingDivider | HeadingDivider[]
     looseYAML?: boolean
     markdown?: any
     printable?: boolean
     slideContainer?: false | Element | Element[]
     inlineSVG?: boolean
   }
 
-  type MarpitHeadingDivider = 1 | 2 | 3 | 4 | 5 | 6
+  type HeadingDivider = 1 | 2 | 3 | 4 | 5 | 6
 
-  type MarpitRenderResult<T = string> = {
+  type RenderResult<T = string> = {
     html: T
     css: string
     comments: string[][]
   }
 
-  type MarpitDirectiveDefinitions = {
+  type DirectiveDefinitions = {
     [directive: string]: (
       value: string | object | (string | object)[],
       marpit?: Marpit
     ) => { [meta: string]: any }
   }
 
+  type Plugin<P extends any[], T extends {} = {}> = (
+    this: Marpit['markdown'] & T,
+    md: Marpit['markdown'] & T,
+    ...params: P
+  ) => void
+
   type ThemeReservedMeta = {
     theme: string
   }
@@ -44,47 +57,34 @@ declare module '@marp-team/marpit' {
     inlineSVG?: boolean
   }
 
-  namespace MarpitEnv {
-    export interface HTMLAsArray {
-      htmlAsArray: true
-      [key: string]: any
-    }
-  }
+  type PluginFactory = <P extends any[]>(
+    plugin: Plugin<P, { marpit: Marpit }>
+  ) => Plugin<P, { marpit: Marpit }>
 
   export class Marpit {
-    constructor(opts?: MarpitOptions)
+    constructor(opts?: Options)
 
     markdown: any
     themeSet: ThemeSet
 
     readonly customDirectives: {
-      global: MarpitDirectiveDefinitions
-      local: MarpitDirectiveDefinitions
+      global: DirectiveDefinitions
+      local: DirectiveDefinitions
     }
-    readonly options: MarpitOptions
+    readonly options: Options
 
     /** @deprecated A plugin interface for markdown-it is deprecated and will remove in future version. Instead, wrap markdown-it instance when creating Marpit by `new Marpit({ markdown: markdownItInstance })`. */
     readonly markdownItPlugins: (md: any) => void
 
-    protected lastComments: MarpitRenderResult['comments'] | undefined
+    protected lastComments: RenderResult['comments'] | undefined
     protected lastGlobalDirectives: { [directive: string]: any } | undefined
     protected lastSlideTokens: any[] | undefined
     protected lastStyles: string[] | undefined
 
-    render(
-      markdown: string,
-      env: MarpitEnv.HTMLAsArray
-    ): MarpitRenderResult<string[]>
-    render(markdown: string, env?: any): MarpitRenderResult
-
-    use<P extends any[]>(
-      plugin: (
-        this: Marpit['markdown'],
-        md: Marpit['markdown'],
-        ...params: P
-      ) => void,
-      ...params: P
-    ): this
+    render(markdown: string, env: MarpitEnv.HTMLAsArray): RenderResult<string[]>
+    render(markdown: string, env?: any): RenderResult
+
+    use<P extends any[]>(plugin: Plugin<P>, ...params: P): this
 
     protected applyMarkdownItPlugins(md: any): void
     protected renderMarkdown(markdown: string, env?: any): string
@@ -142,3 +142,12 @@ declare module '@marp-team/marpit' {
     themes(): IterableIterator<Theme>
   }
 }
+
+declare module '@marp-team/marpit' {
+  export = Marpit
+}
+
+declare module '@marp-team/marpit/plugin' {
+  const pluginFactory: Marpit.PluginFactory
+  export default pluginFactory
+}

package.json

@@ -33,7 +33,8 @@
   "types": "index.d.ts",
   "files": [
     "lib/",
-    "index.d.ts"
+    "index.d.ts",
+    "plugin.js"
   ],
   "scripts": {
     "build": "yarn -s clean && babel src --out-dir lib",

plugin.js

@@ -0,0 +1 @@
+module.exports = require('./lib/plugin')

src/markdown/background_image.js

@@ -1,5 +1,5 @@
 /** @module */
-import marpitPlugin from './marpit_plugin'
+import marpitPlugin from '../plugin'
 import advanced from './background_image/advanced'
 import apply from './background_image/apply'
 import parse from './background_image/parse'

src/markdown/background_image/advanced.js

@@ -1,5 +1,5 @@
 /** @module */
-import marpitPlugin from '../marpit_plugin'
+import marpitPlugin from '../../plugin'
 import InlineStyle from '../../helpers/inline_style'
 import wrapTokens from '../../helpers/wrap_tokens'
 

src/markdown/background_image/apply.js

@@ -1,5 +1,5 @@
 /** @module */
-import marpitPlugin from '../marpit_plugin'
+import marpitPlugin from '../../plugin'
 
 /**
  * Marpit background image apply plugin.

src/markdown/background_image/parse.js

@@ -1,5 +1,5 @@
 /** @module */
-import marpitPlugin from '../marpit_plugin'
+import marpitPlugin from '../../plugin'
 
 const bgSizeKeywords = {
   auto: 'auto',

src/markdown/collect.js

@@ -1,5 +1,5 @@
 /** @module */
-import marpitPlugin from './marpit_plugin'
+import marpitPlugin from '../plugin'
 
 /**
  * Marpit collect plugin.

src/markdown/comment.js

@@ -1,6 +1,6 @@
 /** @module */
 import yaml from './directives/yaml'
-import marpitPlugin from './marpit_plugin'
+import marpitPlugin from '../plugin'
 
 const commentMatcher = /<!--+\s*([\s\S]*?)\s*--+>/
 const commentMatcherOpening = /^<!--/

src/markdown/container.js

@@ -1,5 +1,5 @@
 /** @module */
-import marpitPlugin from './marpit_plugin'
+import marpitPlugin from '../plugin'
 import wrapArray from '../helpers/wrap_array'
 import wrapTokens from '../helpers/wrap_tokens'
 

src/markdown/directives/apply.js

@@ -1,7 +1,7 @@
 /** @module */
 import kebabCase from 'lodash.kebabcase'
 import builtInDirectives from './directives'
-import marpitPlugin from '../marpit_plugin'
+import marpitPlugin from '../../plugin'
 import InlineStyle from '../../helpers/inline_style'
 
 /**

src/markdown/directives/parse.js

@@ -3,7 +3,7 @@ import MarkdownItFrontMatter from 'markdown-it-front-matter'
 import yaml from './yaml'
 import * as directives from './directives'
 import { markAsParsed } from '../comment'
-import marpitPlugin from '../marpit_plugin'
+import marpitPlugin from '../../plugin'
 
 const isDirectiveComment = token =>
   token.type === 'marpit_comment' && token.meta.marpitParsedDirectives

src/markdown/fragment.js

@@ -1,5 +1,5 @@
 /** @module */
-import marpitPlugin from './marpit_plugin'
+import marpitPlugin from '../plugin'
 
 const fragmentedListMarkups = ['*', ')']
 

src/markdown/header_and_footer.js

@@ -1,5 +1,5 @@
 /** @module */
-import marpitPlugin from './marpit_plugin'
+import marpitPlugin from '../plugin'
 import wrapTokens from '../helpers/wrap_tokens'
 
 /**

src/markdown/heading_divider.js

@@ -1,5 +1,5 @@
 /** @module */
-import marpitPlugin from './marpit_plugin'
+import marpitPlugin from '../plugin'
 import split from '../helpers/split'
 
 /**

src/markdown/image.js

@@ -1,5 +1,5 @@
 /** @module */
-import marpitPlugin from './marpit_plugin'
+import marpitPlugin from '../plugin'
 import apply from './image/apply'
 import parse from './image/parse'
 

src/markdown/image/apply.js

@@ -1,5 +1,5 @@
 /** @module */
-import marpitPlugin from '../marpit_plugin'
+import marpitPlugin from '../../plugin'
 import InlineStyle from '../../helpers/inline_style'
 
 /**

src/markdown/image/parse.js

@@ -1,6 +1,6 @@
 /** @module */
 import colorString from 'color-string'
-import marpitPlugin from '../marpit_plugin'
+import marpitPlugin from '../../plugin'
 
 const escape = target =>
   target.replace(

src/markdown/inline_svg.js

@@ -1,5 +1,5 @@
 /** @module */
-import marpitPlugin from './marpit_plugin'
+import marpitPlugin from '../plugin'
 import split from '../helpers/split'
 import wrapTokens from '../helpers/wrap_tokens'
 

src/markdown/slide.js

@@ -1,5 +1,5 @@
 /** @module */
-import marpitPlugin from './marpit_plugin'
+import marpitPlugin from '../plugin'
 import split from '../helpers/split'
 import wrapTokens from '../helpers/wrap_tokens'
 

src/markdown/slide_container.js

@@ -1,5 +1,5 @@
 /** @module */
-import marpitPlugin from './marpit_plugin'
+import marpitPlugin from '../plugin'
 import split from '../helpers/split'
 import wrapArray from '../helpers/wrap_array'
 import wrapTokens from '../helpers/wrap_tokens'

src/markdown/style/assign.js

@@ -1,6 +1,6 @@
 /** @module */
 import postcss from 'postcss'
-import marpitPlugin from '../marpit_plugin'
+import marpitPlugin from '../../plugin'
 
 const uniqKeyChars =
   'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'

src/markdown/style/parse.js

@@ -1,5 +1,5 @@
 /** @module */
-import marpitPlugin from '../marpit_plugin'
+import marpitPlugin from '../../plugin'
 
 const styleMatcher = /<style([\s\S]*?)>([\s\S]*?)<\/style>/i
 const styleMatcherOpening = /^<style(?=(\s|>|$))/i

src/markdown/sweep.js

@@ -1,5 +1,5 @@
 /** @module */
-import marpitPlugin from './marpit_plugin'
+import marpitPlugin from '../plugin'
 
 /**
  * Marpit sweep plugin.