|
| 1 | +# Write an Addon |
| 2 | + |
| 3 | +> Available since v0.32.1 |
| 4 | +
|
| 5 | +## Capability |
| 6 | + |
| 7 | +An addon can contribute to the following points: |
| 8 | + |
| 9 | +- Global styles (use with caution has it is more the role of [themes](/themes/use)) |
| 10 | +- Provide custom layouts or override the existing one |
| 11 | +- Provide custom components or override the existing one |
| 12 | +- Extend Windi CSS configurations |
| 13 | +- Configure tools like Monaco and Prism |
| 14 | + |
| 15 | +## Conventions |
| 16 | + |
| 17 | +Addons are published to npm registry, and they should follow the conventions below: |
| 18 | + |
| 19 | +- Package name should start with `slidev-addon-`, for example: `slidev-addon-awesome` |
| 20 | +- Add `slidev-addon` and `slidev` in the `keywords` field of your `package.json` |
| 21 | + |
| 22 | +## Setup |
| 23 | + |
| 24 | +### Initialization |
| 25 | + |
| 26 | +To create your addon, start by creating a directory with create a `package.json` file (you can use `npm init`). |
| 27 | + |
| 28 | +Then, install slidev dependencies: |
| 29 | + |
| 30 | +```bash |
| 31 | +$ npm install -D @slidev/cli |
| 32 | +``` |
| 33 | + |
| 34 | +### Testing |
| 35 | + |
| 36 | +To set up the testing playground for your addon, you can create an `example.md` file with some content. |
| 37 | + |
| 38 | +And optionally, you can also add some scripts to your `packages.json` |
| 39 | + |
| 40 | +```json |
| 41 | +// package.json |
| 42 | +{ |
| 43 | + "scripts": { |
| 44 | + "dev": "slidev example.md", |
| 45 | + "build": "slidev build example.md", |
| 46 | + "export": "slidev export example.md", |
| 47 | + "screenshot": "slidev export example.md --format png" |
| 48 | + } |
| 49 | +} |
| 50 | +``` |
| 51 | + |
| 52 | +To publish your addon, simply run `npm publish` and you are good to go. There is no build process required (which means you can directly publish `.vue` and `.ts` files, Slidev is smart enough to understand them). |
| 53 | + |
| 54 | +Addon contribution points follow the same conventions as local customization, please refer to [the docs for the naming conventions](/custom/). |
| 55 | + |
| 56 | +## Addon metadata |
| 57 | + |
| 58 | +### Slidev Version |
| 59 | + |
| 60 | +If the addon is relying on a specific feature of Slidev that are newly introduced, you can set the minimal Slidev version required to have your addon working properly: |
| 61 | + |
| 62 | +```json |
| 63 | +// package.json |
| 64 | +{ |
| 65 | + "engines": { |
| 66 | + "slidev": ">=0.32.1" |
| 67 | + } |
| 68 | +} |
| 69 | +``` |
| 70 | + |
| 71 | +If users are using older versions of Slidev, an error will be thrown. |
0 commit comments