write-theme.md - slidev

write-theme.md

1	# Writing Themes
2
3	> Please read <LinkInline link="guide/theme-addon" /> first.
4
5	Each slides project can only have one theme. Themes should focus on providing the appearance of slides. If the feature isn't related to the appearance and can be used separately, it should be implemented as an [addon](./write-addon).
6
7	To get started, we recommend you use our generator for scaffolding your first theme
8
9	::: code-group
10
11	```bash [pnpm]
12	$ pnpm create slidev-theme
13	```
14
15	```bash [npm]
16	$ npm init slidev-theme@latest
17	```
18
19	```bash [yarn]
20	$ yarn create slidev-theme
21	```
22
23	```bash [bun]
24	$ bun create slidev-theme
25	```
26
27	```bash [deno]
28	$ deno init --npm slidev-theme
29	```
30
31	:::
32
33	Then you can modify and play with it. You can also refer to the [official themes](../resources/theme-gallery#official-themes) as examples.
34
35	## Capability
36
37	A theme can contribute to the following points:
38
39	- Global styles
40	- Provide default configurations
41	- Provide custom layouts or override the existing ones
42	- Provide custom components
43	- Configure tools like UnoCSS, Shiki, etc.
44
45	However, the following points are not recommended to be done in a theme, and may be better implemented as an [addon](./write-addon):
46
47	- New code snippets
48	- New code runners
49	- Other things that can be used separately
50
51	Basically, the way to provide global styles, layouts, components and configure tools is the same as doing these in a slides project. For example, to configure Shiki, you can create a `./setup/shiki.ts` as described in [Configure Highlighter](../custom/config-highlighter). You can refer to the [customization guide](/custom/) for more information.
52
53	To provide default Slidev configurations, you can add a `slidev.defaults` field in the `package.json` file, which will be merged with the user's configurations:
54
55	```json [package.json]
56	{
57	"slidev": {
58	"defaults": {
59	"transition": "slide-left",
60	"aspectRatio": "4/3"
61	}
62	}
63	}
64	```
65
66	### Require Slidev Version
67
68	If the theme is relying on a specific feature of Slidev that is newly introduced, you can set the minimal Slidev version required to have your theme working properly:
69
70	```json
71	{
72	"engines": {
73	"slidev": ">=0.48.0"
74	}
75	}
76	```
77
78	An error message will be shown when the an incompatible version is used.
79
80	### Theme Metadata
81
82	By default, Slidev assumes themes support both light mode and dark mode. If you only want your theme to be presented in a specific color schema, you need to specify it explicitly in the `package.json`:
83
84	```json [package.json]
85	{
86	"slidev": {
87	"colorSchema": "light" // or "dark" or "both"
88	}
89	}
90	```
91
92	## Previewing
93
94	You can preview your theme when developing by using a demo slide deck. To do so, create a `./slides.md` file with the following headmatter:
95
96	```md [slides.md]
97	---
98	theme: ./ # Use the theme in the current directory
99	---
100	```
101
102	Then you can start the demo slides as usual.
103
104	## Publishing
105
106	When publishing the theme, non-JS files like `.vue` and `.ts` files can be published directly without compiling. Slidev will automatically compile them when using the theme.
107
108	Themes should follow the following conventions:
109
110	- Package name should start with `slidev-theme-`. For example, `slidev-theme-name` or `@scope/slidev-theme-name`
111	- Add `"slidev-theme"` and `"slidev"` in the `keywords` field of your `package.json`
112
113	Theme can be used locally without publishing to NPM. If your theme is only for personal use, you can simply use it as a local theme, or publish it as a private scoped package. However, it is recommended to publish it to the NPM registry if you want to share it with others.
114

114 lines MARKDOWN