How to organise a third-party theme and engine repo

[mil-ad]

I have been using marp for a while and now have my own custom theme and also an slightly custom engine. But right now they both live in a repo I've hacked together and I need to clone this repo to use them. It also makes sharing them with others a bit difficult.

Maybe this is a trivial js question (which I'm not super familiar with) but I was wondering if there is a way to organise my theme and engine in a repo (or two repos?) such that I can use them directly in marp --engine @my-github-user/some-repo --theme-set @my-github-user/some-repo ...? @yhatt I think it'd be really helpful if there was a template repo for people who want to make their own custom themes and engines

[yhatt]

--engine option in Marp CLI can pass the name of installed npm module. If you provided a custom engine as npm module, Marp CLI users can use your custom engine easily.

// package.json
{
  "name": "marp-custom-engine",
  "version": "0.0.1",
  "keywords": ["marp", "marp-cli", "marp-engine"],
  "type": "module",
  "main": "engine.js",
}

// engine.js
export default ({ marp }) => {
  console.log('Using custom engine...')
  return marp
}

CLI users can use the engine by installing it from npm.

npm i --save-dev @marp-team/marp-cli marp-custom-engine
npx marp --engine marp-custom-engine slide.md

npm package manager also can fetch the module from GitHub repository directly. (The engine name is specified by name field of package.json in the module repository)

npm i --save-dev @marp-team/marp-cli github-user/github-repo
npx marp --engine marp-custom-engine slide.md

For testing your custom engine repository in local environment, npm also can use the local directory as npm package.

npm i --save-dev @marp-team/marp-cli ./path/to/marp-custom-engine
npx marp --engine marp-custom-engine slide.md

And you can provide the custom theme within the engine through Marpit's interface. This way can provide your own themes as your custom engine so no need to specify --theme-set option by user.
https://marpit.marp.app/usage?id=add-to-theme-set

// engine.js
export default ({ marp }) => marp.use(({ marpit }) => {
  marpit.themeSet.add(`
/* @theme custom-theme */

section {
  background-color: #123;
  /* ... */
}
`)
})

[yhatt]

Another example: A deadly simple custom engine can provide via GitHub Gist 😄
https://gist.github.com/yhatt/c8949276ceab6cd979f0f5c7b7c1b7fc

$ npm i --save @marp-team/marp-cli gist:c8949276ceab6cd979f0f5c7b7c1b7fc
$ npx marp --engine marp-custom-engine your-slide.md
[  INFO ] Converting 1 markdown...
You are using marp-custom-engine.
[  INFO ] your-slide.md => your-slide.html

[yhatt]

In general, Sass source should compile to CSS before publishing to npm module.

[mil-ad]

amazing!

[mil-ad]

One final question. Am I right in thinking that this custom engine can't be used with the vs code plugin?

[yhatt]

Right. The reason has been described at #543. Alternative of Marp preview is using preview window provided by Marp CLI (--preview).