Merge pull request #386 from marp-team/expose-marp-to-functional-engine

Expose Marp Core instance to functional engine

Author: yhatt

CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Added
 
 - Experimental transitions for bespoke template ([#382](https://github.com/marp-team/marp-cli/issues/382), [#381](https://github.com/marp-team/marp-cli/pull/381))
+- Expose Marp Core instance to functional engine via `marp` getter ([#386](https://github.com/marp-team/marp-cli/pull/386)))
 
 ### Changed
 

README.md

@@ -372,29 +372,44 @@ Notice that Marpit has not provided theme. It would be good to include inline st
 
 ### Functional engine
 
-When you specify the path to JavaScript file in `--engine` option, you may use more customized engine by JS.
+When you specified the path to JavaScript file in `--engine` option, you may use more customized engine by a JavaScript function.
 
-It would be useful to convert with a customized engine for supporting the additional syntax that is out of Marp Markdown specification.
+#### Spec
+
+The functional engine should export a function with one parameter, which is a constructor option of Marpit. The function must return an instance of Marpit-based engine made by the passed parameter.
+
+```javascript
+module.exports = function (constructorOption) {
+  return new MarpitBasedEngine(constructorOption)
+}
+```
+
+Marp CLI also exposes `marp` getter property to the parameter. It returns a prepared instance of the built-in Marp Core engine, so you can apply several customizations to Marp engine with simple declarations.
+
+```javascript
+module.exports = ({ marp }) => marp.use(marpPlugin).use(andMorePlugin)
+```
+
+It allows converting Markdown with additional syntaxes that were provided by Marp (or compatible markdown-it) plugins.
 
 #### Example: [markdown-it-mark](https://github.com/markdown-it/markdown-it-mark)
 
 ```javascript
 // engine.js
-const { Marp } = require('@marp-team/marp-core')
 const markdownItMark = require('markdown-it-mark')
 
-module.exports = (opts) => new Marp(opts).use(markdownItMark)
+module.exports = ({ marp }) => marp.use(markdownItMark)
 ```
 
 ```bash
-# Install Marp Core and markdown-it-mark
-npm install @marp-team/marp-core markdown-it-mark --save-dev
+# Install markdown-it-mark
+npm install markdown-it-mark --save
 
 # Specify the path to functional engine
 marp --engine ./engine.js slide-deck.md
 ```
 
-The customized engine would convert `==marked==` to `<mark>marked</mark>`.
+The customized engine will convert `==marked==` to `<mark>marked</mark>`.
 
 ### Confirm engine version
 
@@ -434,12 +449,11 @@ pdf: true
 
 ```javascript
 // marp.config.js
-const { Marp } = require('@marp-team/marp-core')
-const container = require('markdown-it-container')
+const markdownItContainer = require('markdown-it-container')
 
 module.exports = {
   // Customize engine on configuration file directly
-  engine: (opts) => new Marp(opts).use(container, 'custom'),
+  engine: ({ marp }) => marp.use(markdownItContainer, 'custom'),
 }
 ```
 
@@ -491,7 +505,9 @@ The advanced options that cannot specify through CLI options can be configured b
 
 `options` can set the base options for the constructor of the used engine. You can fine-tune constructor options for [Marp Core](https://github.com/marp-team/marp-core#constructor-options) / [Marpit](https://marpit-api.marp.app/marpit).
 
-For example, the below configuration will set constructor option for Marp Core as specified:
+##### Example
+
+The below configuration will set constructor option for Marp Core as specified:
 
 - Disables [Marp Core's line breaks conversion](https://github.com/marp-team/marp-core#marp-markdown) (`\n` to `<br />`) to match for CommonMark, by passing [markdown-it's `breaks` option](https://markdown-it.github.io/markdown-it/#MarkdownIt.new) as `false`.
 - Disable minification for rendered theme CSS to make debug your style easily, by passing [`minifyCSS`](https://github.com/marp-team/marp-core#minifycss-boolean) as `false`.

src/config.ts

@@ -1,13 +1,12 @@
 /* eslint-disable @typescript-eslint/no-non-null-assertion */
 import fs from 'fs'
 import path from 'path'
-import { Marp } from '@marp-team/marp-core'
 import chalk from 'chalk'
 import { cosmiconfig } from 'cosmiconfig'
 import { osLocale } from 'os-locale'
 import { info, warn } from './cli'
 import { ConverterOption, ConvertType } from './converter'
-import resolveEngine, { ResolvableEngine, ResolvedEngine } from './engine'
+import { ResolvableEngine, ResolvedEngine } from './engine'
 import { keywordsAsArray } from './engine/meta-plugin'
 import { error } from './error'
 import { TemplateOption } from './templates'
@@ -77,11 +76,11 @@ export class MarpCLIConfig {
     if (args.configFile !== false) await conf.loadConf(args.configFile)
 
     conf.engine = await (() => {
-      if (conf.args.engine) return resolveEngine(conf.args.engine)
+      if (conf.args.engine) return ResolvedEngine.resolve(conf.args.engine)
       if (conf.conf.engine)
-        return resolveEngine(conf.conf.engine, conf.confPath)
+        return ResolvedEngine.resolve(conf.conf.engine, conf.confPath)
 
-      return resolveEngine(['@marp-team/marp-core', Marp])
+      return ResolvedEngine.resolveDefaultEngine()
     })()
 
     return conf

src/converter.ts

@@ -1,11 +1,11 @@
 /* eslint-disable @typescript-eslint/no-non-null-assertion */
 import { URL } from 'url'
-import { MarpOptions } from '@marp-team/marp-core'
+import type { MarpOptions } from '@marp-team/marp-core'
 import { Marpit, Options as MarpitOptions } from '@marp-team/marpit'
 import chalk from 'chalk'
 import puppeteer from 'puppeteer-core'
 import { silence, warn } from './cli'
-import { Engine } from './engine'
+import { Engine, ResolvedEngine } from './engine'
 import infoPlugin, { engineInfo, EngineInfo } from './engine/info-plugin'
 import metaPlugin from './engine/meta-plugin'
 import { error } from './error'
@@ -149,8 +149,8 @@ export class Converter {
         isFile(file) && this.options.watch && type === ConvertType.html
           ? await notifier.register(file.absolutePath)
           : undefined,
-      renderer: (tplOpts) => {
-        const engine = this.generateEngine(tplOpts)
+      renderer: async (tplOpts) => {
+        const engine = await this.generateEngine(tplOpts)
         tplOpts.modifier?.(engine)
 
         const ret = engine.render(stripBOM(`${markdown}${additionals}`))
@@ -420,28 +420,41 @@ export class Converter {
     return ret
   }
 
-  private generateEngine(
+  private async generateEngine(
     mergeOptions: MarpitOptions
-  ): Marpit & { [engineInfo]: EngineInfo | undefined } {
+  ): Promise<Marpit & { [engineInfo]?: EngineInfo }> {
     const { html, options } = this.options
     const { prototype } = this.options.engine
     const opts = { ...options, ...mergeOptions, html }
 
-    const engine =
+    let engine: any
+
+    if (
       prototype &&
       Object.prototype.hasOwnProperty.call(prototype, 'constructor')
-        ? new this.options.engine(opts)
-        : (<any>this.options.engine)(opts)
+    ) {
+      engine = new this.options.engine(opts)
+    } else {
+      // Expose "marp" getter to allow accessing a bundled Marp Core instance
+      const defaultEngine = await ResolvedEngine.resolveDefaultEngine()
+
+      Object.defineProperty(opts, 'marp', {
+        get: () => new defaultEngine.klass(opts),
+      })
+
+      engine = (this.options.engine as any)(opts)
+    }
 
     if (typeof engine.render !== 'function')
       error('Specified engine has not implemented render() method.')
 
+    // Enable HTML tags
     if (html !== undefined) engine.markdown.set({ html })
 
     // Marpit plugins
     engine.use(metaPlugin).use(infoPlugin)
 
-    // Additional themes
+    // Themes
     this.options.themeSet.registerTo(engine)
 
     return engine

src/engine.ts

@@ -5,41 +5,72 @@ import pkgUp from 'pkg-up'
 import { error } from './error'
 
 export type Engine = typeof Marpit
-export type ResolvableEngine = Engine | string
+export type ResolvableEngine = Engine | DelayedEngineResolver | string
+
+const delayedEngineResolverSymbol = Symbol('delayedEngineResolver')
+
+type DelayedEngineResolver = {
+  [delayedEngineResolverSymbol]: () => Promise<Engine>
+}
+
+const delayedEngineResolver = (
+  fn: () => Promise<Engine>
+): DelayedEngineResolver => ({ [delayedEngineResolverSymbol]: fn })
 
 export class ResolvedEngine {
   klass: Engine
   package?: Record<string, any>
 
+  private static _defaultEngine: ResolvedEngine | undefined
+
   static async resolve(
     engine: ResolvableEngine | ResolvableEngine[],
     from?: string
   ): Promise<ResolvedEngine> {
     const resolvedEngine = new ResolvedEngine(
-      ResolvedEngine.resolveModule(engine, from)
+      await ResolvedEngine.resolveModule(engine, from)
     )
 
     await resolvedEngine.resolvePackage()
     return resolvedEngine
   }
 
-  private static resolveModule(
+  static async resolveDefaultEngine(): Promise<ResolvedEngine> {
+    if (
+      ResolvedEngine._defaultEngine === undefined ||
+      process.env.NODE_ENV === 'test'
+    ) {
+      ResolvedEngine._defaultEngine = await ResolvedEngine.resolve([
+        '@marp-team/marp-core',
+        delayedEngineResolver(
+          async () => (await import('@marp-team/marp-core')).Marp
+        ),
+      ])
+    }
+    return ResolvedEngine._defaultEngine
+  }
+
+  private static async resolveModule(
     engine: ResolvableEngine | ResolvableEngine[],
     from?: string
   ) {
     let resolved
-    ;(Array.isArray(engine) ? engine : [engine]).some((eng) => {
+
+    for (const eng of ([] as ResolvableEngine[]).concat(engine)) {
       if (typeof eng === 'string') {
         resolved =
           (from && importFrom.silent(path.dirname(path.resolve(from)), eng)) ||
           importFrom.silent(process.cwd(), eng)
 
         if (resolved?.__esModule) resolved = resolved.default
+      } else if (typeof eng === 'object' && eng[delayedEngineResolverSymbol]) {
+        resolved = await eng[delayedEngineResolverSymbol]()
       } else {
         resolved = eng
       }
-      return resolved
-    })
+
+      if (resolved) break
+    }
 
     if (!resolved) error(`The specified engine has not resolved.`)
     return resolved
@@ -73,5 +104,3 @@ export class ResolvedEngine {
     return undefined
   }
 }
-
-export default ResolvedEngine.resolve

src/templates/index.ts

@@ -21,7 +21,9 @@ interface TemplateCoreOption {
   base?: string
   lang: string
   notifyWS?: string
-  renderer: (tplOpts: TemplateRendererOptions) => RendererResult
+  renderer: (
+    tplOpts: TemplateRendererOptions
+  ) => RendererResult | Promise<RendererResult>
 }
 
 export interface TemplateMeta {
@@ -60,7 +62,7 @@ export type Template<T = TemplateOption> = ((
 }
 
 export const bare: Template<TemplateBareOption> = async (opts) => {
-  const rendered = opts.renderer({
+  const rendered = await opts.renderer({
     container: [],
     inlineSVG: true,
     slideContainer: [],
@@ -80,15 +82,21 @@ export const bare: Template<TemplateBareOption> = async (opts) => {
 Object.defineProperty(bare, 'printable', { value: true })
 
 export const bespoke: Template<TemplateBespokeOption> = async (opts) => {
-  const rendered = opts.renderer({
+  const rendererOptions = {
     container: new Element('div', { id: 'p' }),
     inlineSVG: true,
     slideContainer: [],
-    modifier: (marpit) => {
+  }
+
+  // Hide template-specific modifier from options which have exposed to the functional engine
+  Object.defineProperty(rendererOptions, 'modifier', {
+    value: (marpit) => {
       if (opts.transition) marpit.use(transitionPlugin)
     },
   })
 
+  const rendered = await opts.renderer(rendererOptions)
+
   return {
     rendered,
     result: bespokePug({

src/version.ts

@@ -1,21 +1,23 @@
-import { Marp } from '@marp-team/marp-core'
 import { version as bundledCoreVer } from '@marp-team/marp-core/package.json'
 import { name, version } from '../package.json'
 import { MarpCLIConfig } from './config'
+import { ResolvedEngine } from './engine'
 
-export const isMarpCore = (klass: any): boolean => klass === Marp
+export const isMarpCore = async (engine: ResolvedEngine): Promise<boolean> =>
+  engine.package?.name === '@marp-team/marp-core' ||
+  engine === (await ResolvedEngine.resolveDefaultEngine())
 
 export default async function outputVersion(config: MarpCLIConfig): Promise<0> {
   let engineVer = ''
   const { engine } = config
 
-  if (isMarpCore(engine.klass)) {
+  if (await isMarpCore(engine)) {
     engineVer = `@marp-team/marp-core v${bundledCoreVer}`
 
     if (engine.package && engine.package.version !== bundledCoreVer) {
       engineVer = `user-installed @marp-team/marp-core v${engine.package.version}`
     }
-  } else if (engine.package && engine.package.name && engine.package.version) {
+  } else if (engine.package?.name && engine.package.version) {
     engineVer = `customized engine in ${engine.package.name} v${engine.package.version}`
   } else {
     engineVer = `customized engine`