|
1 | | -# TutorialKit Starter |
| 1 | +# Vite Plugin tutorial |
2 | 2 |
|
3 | | -👋 Welcome to TutorialKit! |
4 | | - |
5 | | -This README includes everything you need to start writing your tutorial content quickly. |
6 | | - |
7 | | -## Project Structure |
8 | | - |
9 | | -```bash |
10 | | -. |
11 | | -├── astro.config.mjs # TutorialKit uses Astro 🚀 (https://astro.build) |
12 | | -├── src |
13 | | -│ ├── ... |
14 | | -│ ├── content |
15 | | -│ │ └── tutorial # Your tutorial content lives here |
16 | | -│ └── templates # Your templates (see below for more information) |
17 | | -├── public |
18 | | -│ ├── favicon.svg |
19 | | -│ └── logo.svg # Default logo used in top left for your tutorial |
20 | | -├── ... |
21 | | -├── theme.ts # Customize the theme of the tutorial |
22 | | -└── uno.config.ts # UnoCSS config (https://unocss.dev/) |
23 | | -``` |
24 | | - |
25 | | -## Getting Started |
26 | | - |
27 | | -Make sure you have all dependencies installed and started the dev server: |
28 | | - |
29 | | -```bash |
30 | | -pnpm install |
31 | | -pnpm run dev |
32 | | -``` |
33 | | - |
34 | | -## UI Structure |
35 | | - |
36 | | -```markdown |
37 | | -┌─────────────────────────────────────────────────────┐ |
38 | | -│ ● ● ● │ |
39 | | -├───────────────────────────┬─────────────────────────┤ |
40 | | -│ │ │ |
41 | | -│ │ │ |
42 | | -│ │ │ |
43 | | -│ │ │ |
44 | | -│ │ Code Editor │ |
45 | | -│ │ │ |
46 | | -│ │ │ |
47 | | -│ │ │ |
48 | | -│ │ │ |
49 | | -│ Content ├─────────────────────────┤ |
50 | | -│ │ │ |
51 | | -│ │ │ |
52 | | -│ │ Preview & Boot Screen │ |
53 | | -│ │ │ |
54 | | -│ │ │ |
55 | | -│ ├─────────────────────────┤ |
56 | | -│ │ │ |
57 | | -│ │ Terminal │ |
58 | | -│ │ │ |
59 | | -└───────────────────────────┴─────────────────────────┘ |
60 | | -``` |
61 | | - |
62 | | -## Authoring Content |
63 | | - |
64 | | -A tutorial consists of parts, chapters, and lessons. For example: |
65 | | - |
66 | | -- Part 1: Basics of Vite |
67 | | - - Chapter 1: Introduction |
68 | | - - Lesson 1: Welcome! |
69 | | - - Lesson 2: Why Vite? |
70 | | - - … |
71 | | - - Chapter 2: Your first Vite project |
72 | | -- Part 2: CLI |
73 | | - - … |
74 | | - |
75 | | -Your content is organized into lessons, with chapters and parts providing a structure and defining common metadata for these lessons. |
76 | | - |
77 | | -Here’s an example of how it would look like in `src/content/tutorial`: |
78 | | - |
79 | | -```bash |
80 | | -tutorial |
81 | | -├── 1-basics-of-vite |
82 | | -│ ├── 1-introduction |
83 | | -│ │ ├── 1-welcome |
84 | | -│ │ │ ├── content.md # The content of your lesson |
85 | | -│ │ │ ├── _files # Initial set of files |
86 | | -│ │ │ │ └── ... |
87 | | -│ │ │ └── _solution # Solution of the lesson |
88 | | -│ │ │ └── ... |
89 | | -│ │ ├── 2-why-vite |
90 | | -│ │ │ ├── content.md |
91 | | -│ │ │ └── _files |
92 | | -│ │ │ └── ... |
93 | | -│ │ └── meta.md # Metadata for the chapter |
94 | | -│ └── meta.md # Metadata for the part |
95 | | -├── 2-advanced |
96 | | -│ ├── ... |
97 | | -│ └── meta.md |
98 | | -└── meta.md # Metadata for the tutorial |
99 | | -``` |
100 | | - |
101 | | -### Supported Content Formats |
102 | | - |
103 | | -Content can be either written as Markdown (`.md`) files or using [MDX](https://mdxjs.com/) (`.mdx`). Files have a Front Matter at the top that contains the metadata and everything that comes after is the content of your lesson. |
104 | | - |
105 | | -**Example** |
106 | | - |
107 | | -```markdown |
108 | | ---- |
109 | | -type: lesson |
110 | | -title: Welcome! |
111 | | ---- |
112 | | - |
113 | | -# Welcome to TutorialKit! |
114 | | - |
115 | | -In this tutorial we'll walk you through how to setup your environment to |
116 | | -write your first tutorial 🤩 |
117 | | -``` |
118 | | - |
119 | | -The metadata file (`meta.md`) of parts, chapters, and lessons do not contain any content. It only contains the Front Matter for configuration. |
120 | | - |
121 | | -### Metadata |
122 | | - |
123 | | -Here is an overview of the properties that can be used as part of the Front Matter: |
124 | | - |
125 | | -| Property | Required | Type | Inherited | Description | |
126 | | -| --------------- | -------- | --------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | |
127 | | -| type | ✅ | `part \| chapter \| lesson` | ❌ | The type of the metadata. | |
128 | | -| title | ✅ | `string` | ❌ | The title of the part, chapter, or lesson. | |
129 | | -| slug | | `string` | ❌ | Let’s you customize the URL pathname which is `/:partSlug/:chapterSlug/:lessonSlug`. | |
130 | | -| previews | | `Preview[]` | ✅ | Configure which ports should be used for the previews. If not specified, the lowest port will be used. | |
131 | | -| autoReload | | `boolean` | ✅ | Navigating to a lesson that specifies `autoReload` will always reload the preview. This is typically only needed if your server does not support HMR. | |
132 | | -| prepareCommands | | `Command[]` | ✅ | List of commands to execute sequentially. They are typically used to install dependencies or to run scripts. | |
133 | | -| mainCommand | | `Command` | ✅ | The main command to be executed. This command will run after the `prepareCommands`. | |
134 | | - |
135 | | -A `Command` has the following shape: |
136 | | - |
137 | | -```ts |
138 | | -string | [command: string, title: string] | { command: string, title: string } |
139 | | -``` |
140 | | - |
141 | | -The `title` is used as part of the boot screen (see [UI Structure](#ui-structure)). |
142 | | - |
143 | | -A `Preview` has the following shape: |
144 | | - |
145 | | -```ts |
146 | | -string | [port: number, title: string] | { port: number, title: string } |
147 | | -``` |
148 | | - |
149 | | -In most cases, metadata is inherited. For example, if you specify a `mainCommand` on a chapter without specifying it on any of its lessons, each lesson will use the `mainCommand` from its respective chapter. This extends to chapter and parts as well. |
| 3 | +Deployed at https://tutorial-vite-plugin.pages.dev/ |
0 commit comments