feat: addons doc (#71)

* fix: title levels

* feat: add addons doc

* fix: remove compiler macro warnings

Author: tonai

.vitepress/config.js

@@ -70,6 +70,17 @@ const Theme = [
   },
 ]
 
+const Addon = [
+  {
+    text: 'Use Addon',
+    link: '/addons/use',
+  },
+  {
+    text: 'Write an Addon',
+    link: '/addons/write-an-addon',
+  },
+]
+
 const Translations = [
   {
     text: 'English',
@@ -191,6 +202,10 @@ const slidebars = [
     text: 'Themes',
     children: Theme,
   },
+  {
+    text: 'Addons',
+    children: Addon,
+  },
   {
     text: 'Customizations',
     children: Customizations,
@@ -254,6 +269,10 @@ module.exports = {
         text: 'Theme',
         items: Theme,
       },
+      {
+        text: 'Addon',
+        items: Addon,
+      },
       {
         text: 'Customize',
         items: Customizations,
@@ -271,6 +290,7 @@ module.exports = {
     sidebar: {
       '/guide/': slidebars,
       '/themes/': slidebars,
+      '/addons/': slidebars,
       '/custom/': slidebars,
       '/builtin/': slidebars,
       '/resources/': slidebars,

.vitepress/theme/components/AlgoliaSearchBox.vue

@@ -5,7 +5,7 @@
 <script setup lang="ts">
 import '@docsearch/css'
 import { useRoute, useRouter } from 'vitepress'
-import { defineProps, getCurrentInstance, onMounted, watch } from 'vue'
+import { getCurrentInstance, onMounted, watch } from 'vue'
 import docsearch from '@docsearch/js'
 import type { DocSearchHit } from '@docsearch/react/dist/esm/types'
 import type { DefaultTheme } from '../config'

.vitepress/theme/components/BooleanDisplay.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { ref, defineProps } from 'vue'
+import { ref } from 'vue'
 
 const props = defineProps({
   value: {

.vitepress/theme/components/Environment.vue

@@ -1,6 +1,4 @@
 <script setup lang="ts">
-import { defineProps } from 'vue'
-
 defineProps<{ type: 'node' | 'client' }>()
 </script>
 

.vitepress/theme/components/NavBar.vue

@@ -39,7 +39,6 @@
 </template>
 
 <script setup lang="ts">
-import { defineEmit, defineProps } from 'vue'
 import { useRepo } from '../composables/repo'
 import NavBarTitle from './NavBarTitle.vue'
 import NavLinks from './NavLinks.vue'
@@ -48,7 +47,7 @@ import DarkModeSwitch from './DarkModeSwitch.vue'
 
 const repo = useRepo()
 
-defineEmit(['toggle'])
+defineEmits(['toggle'])
 
 defineProps({
   showSidebar: { type: Boolean, required: true },

.vitepress/theme/components/NavDropdownLink.vue

@@ -14,7 +14,7 @@
 </template>
 
 <script setup lang="ts">
-import { defineProps, ref, watch } from 'vue'
+import { ref, watch } from 'vue'
 import { useRoute } from 'vitepress'
 import type { DefaultTheme } from '../config'
 import NavDropdownLinkItem from './NavDropdownLinkItem.vue'

.vitepress/theme/components/NavDropdownLinkItem.vue

@@ -9,7 +9,7 @@
 </template>
 
 <script setup lang="ts">
-import { defineProps, toRefs } from 'vue'
+import { toRefs } from 'vue'
 import type { DefaultTheme } from '../config'
 import { useNavLink } from '../composables/navLink'
 import OutboundLink from './icons/OutboundLink.vue'

.vitepress/theme/components/NavLink.vue

@@ -7,7 +7,7 @@
 </template>
 
 <script setup lang="ts">
-import { defineProps, toRefs } from 'vue'
+import { toRefs } from 'vue'
 import type { DefaultTheme } from '../config'
 import { useNavLink } from '../composables/navLink'
 import OutboundLink from './icons/OutboundLink.vue'

.vitepress/theme/components/ShowCaseInfo.vue

@@ -1,5 +1,4 @@
 <script setup lang="ts">
-import { defineProps } from 'vue'
 import type { ShowCaseInfo } from '../../showcases'
 
 defineProps<{

.vitepress/theme/components/SideBar.vue

@@ -11,7 +11,6 @@
 </template>
 
 <script setup lang="ts">
-import { defineProps } from 'vue'
 import NavLinks from './NavLinks.vue'
 import SideBarLinks from './SideBarLinks.vue'
 

.vitepress/theme/components/ThemeGallery.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { defineProps, computed } from 'vue'
+import { computed } from 'vue'
 import { official, community } from '../../themes'
 
 const props = defineProps({

.vitepress/theme/components/ThemeInfo.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { defineProps, ref } from 'vue'
+import { ref } from 'vue'
 import { isClient, useIntervalFn } from '@vueuse/core'
 import type { ThemeInfo } from '../../themes'
 

.vitepress/theme/components/Tweet.vue

@@ -8,7 +8,7 @@ Usage:
 
 <script setup lang="ts">
 import { useScriptTag, isClient } from '@vueuse/core'
-import { defineProps, getCurrentInstance, onMounted, ref } from 'vue'
+import { getCurrentInstance, onMounted, ref } from 'vue'
 import { isDark } from '../composables/dark'
 
 const props = defineProps<{

TRANSLATIONS.md

@@ -77,6 +77,11 @@ In case it's already been translated but you're wondering how to maintain it, sk
 - [ ] `use.md` - How to use Slidev themes
 - [ ] `write-a-theme.md` - Write your own theme
 
+### addons/
+
+- [ ] `use.md` - How to use Slidev addons
+- [ ] `write-an-addon.md` - Write your own addon
+
 ## Publishing your translations
 
 - [ ] When you finish the translation (at least 90%), `@antfu` in the Discord and we will invite you to the org and make the translation official.

addons/use.md

@@ -0,0 +1,38 @@
+# Use Addon
+
+Addons are sets of additionnal components, layouts, styles, configuration...etc. that you can use in your presentation.
+
+They are quite similar to [themes](/themes/use), but in general:
+
+* they don't affect the global styles of your slides
+* you can use multiple addons in one presentation
+
+To use addons, you have to install them manually via:
+
+```bash
+$ npm install [slidev-addon-package1] [slidev-addon-package2]
+```
+
+And then declare the addons either in your frontmatter:
+
+```yaml
+---
+addons:
+  - slidev-addon-package1
+  - slidev-addon-package2
+---
+```
+
+Or in your `package.json` file:
+
+```json
+// package.json
+{
+  "slidev": {
+    "addons": [
+      "slidev-addon-package1",
+      "slidev-addon-package2",
+    ]
+  }
+}
+```

addons/write-an-addon.md

@@ -0,0 +1,71 @@
+# Write an Addon
+
+> Available since v0.32.1
+
+## Capability
+
+An addon can contribute to the following points:
+
+- Global styles (use with caution has it is more the role of [themes](/themes/use))
+- Provide custom layouts or override the existing one
+- Provide custom components or override the existing one
+- Extend Windi CSS configurations
+- Configure tools like Monaco and Prism
+
+## Conventions
+
+Adons are published to npm registry, and they should follow the conventions below:
+
+- Package name should start with `slidev-addon-`, for example: `slidev-addon-awesome`
+- Add `slidev-addon` and `slidev` in the `keywords` field of your `package.json`
+
+## Setup
+
+### Initialization
+
+To create your addon, start by creating a directory with create a `package.json` file (you can use `npm init`).
+
+Then, install slidev dependencies:
+
+```bash
+$ npm install -D @slidev/cli
+```
+
+### Testing
+
+To set up the testing playground for your addon, you can create an `example.md` file with some content.
+
+And optionally, you can also add some scripts to your `packages.json`
+
+```json
+// package.json
+{
+  "scripts": {
+    "dev": "slidev example.md",
+    "build": "slidev build example.md",
+    "export": "slidev export example.md",
+    "screenshot": "slidev export example.md --format png"
+  }
+}
+```
+
+To publish your theme, 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).
+
+Addon contribution points follow the same conventions as local customization, please refer to [the docs for the naming conventions](/custom/). 
+
+## Addon metadata
+
+### Slidev Version
+
+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:
+
+```json
+// package.json
+{
+  "engines": {
+    "slidev": ">=0.32.1"
+  }
+}
+```
+
+If users are using older versions of Slidev, an error will be thrown.

guide/install.md

@@ -137,7 +137,7 @@ You can visit your slides from http://localhost/
 
 Refer to the [tangramor/slidev_docker](https://github.com/tangramor/slidev_docker) for more details.
 
-### Command Line Interface (CLI)
+## Command Line Interface (CLI)
 
 `@slidev/cli` Expose a few commands you can use with `npx slidev ...` or by adding scripts in your `package.json`:
 ```json
@@ -160,7 +160,7 @@ If you use npm scripts, don't forget to add `--` after the npm command:
 npm run slidev -- --open
 ```
 
-#### `slidev [entry]`
+### `slidev [entry]`
 
 Start a local server for Slidev.
 
@@ -175,7 +175,7 @@ Options:
 * `--force`, `-f` (`boolean`, default `false`): force the optimizer to ignore the cache and re-bundle.
 * `--theme`, `-t` (`string`): override theme.
 
-#### `slidev build [entry]`
+### `slidev build [entry]`
 
 Build hostable SPA.
 
@@ -189,7 +189,7 @@ Options:
 * `--download` (`boolean`, default: `false`): allow to download the slides as PDF inside the SPA.
 * `--theme`, `-t` (`string`): override theme.
 
-#### `slidev export [entry]`
+### `slidev export [entry]`
 
 Export slides to PDF (or other format).
 
@@ -205,13 +205,13 @@ Options:
 * `--with-clicks`, `-c` (`boolean`, default: `false`): export pages for every clicks (see https://sli.dev/guide/animations.html#click-animations).
 * `--theme`, `-t` (`string`): override theme.
 
-#### `slidev format [entry]`
+### `slidev format [entry]`
 
 Format the markdown file.
 
 * `[entry]` (`string`, default: `slides.md`): path to the slides markdown entry.
 
-#### `slidev theme [subcommand]`
+### `slidev theme [subcommand]`
 
 Theme related operations.