介绍
文档是成功项目的重要组成部分,但您的项目可能不需要完整的文档系统,在这种情况下,静态页面可能就足够了。
VuePress解析在文件夹中结构化的Markdown文件到HTML文件,以便提供服务。 VuePress船与 Vue, Vue Router,和 webpack.每个Markdown文件被解析为Vue模板和资产由Webpack组合。将Markdown文件解析为Vue模板还允许您使用原生Vue脚本作为单个文件组件。
<$>[注] 注: 本教程是用手动安装来编写的,也可以使用一个名为 create-vuepress-site的自动排列工具。
在本文中,您将构建一个静态文档网站,这也是使用Vue驱动的静态网站构建程序VuePress的单页应用程序。
前提条件
如果您想跟随这篇文章,您将需要:
- Node.js 的本地开发环境 遵循 如何安装 Node.js 并创建本地开发环境。
本教程已通过 Node v16.6.2, npm v8.1.0 和 vuepress v1.8.2 进行验证。
步骤1 - 设置项目
在本节中,您将创建您的项目并安装VuePress。
首先,创建一个新的项目目录:
1mkdir vuepress-example
接下来,更改到新项目目录:
1cd vuepress-example
然后,开始一个新的项目:
1npm init --yes
此命令可以快速将一个新项目放置,并创建一个package.json文件。
接下来,将VuePress本地安装为 dev 依赖性:
1npm install [email protected] --save-dev
一旦VuePress在项目中安装,您将拥有所需的一切,因为VuePress配备了用于该项目的默认文档主题。
在此时刻,你应该修改你的package.json,以便编写脚本来构建和服务VuePress网站。
在代码编辑器中打开package.json,并添加突出的代码行:
1[label package.json]
2{
3 "name": "vuepress-example",
4 "version": "1.0.0",
5 "description": "",
6 "main": "index.js",
7 "scripts": {
8 "test": "echo \"Error: no test specified\" && exit 1",
9 "docs:dev": "vuepress dev docs",
10 "docs:build": "vuepress build docs"
11 },
12 "keywords": [],
13 "author": "",
14 "license": "ISC",
15 "devDependencies": {
16 "vuepress": "^1.8.2"
17 }
18}
在此时,您已经安装了VuePress并修改了package.json,以支持dev和build命令。
第2步:创建首页
在本节中,您将创建目录结构和 Markdown 文件,使用位置持有人文本。
在 VuePress 中创建文件夹时要小心,因为它根据其目录结构对文件夹和 Markdown 文件进行评估。
首先,创建一个docs目录来容纳组件和配置:
1mkdir docs
现在,使用代码编辑器在这个目录中创建一个新的 index.md 文件:
1[label docs/index.md]
2---
3home: true
4actionText: Counter Component
5actionLink: /counter/
6features:
7- title: Embedded Vue Compments
8 details: A Vue counter developed using Vue is embedded in this documentation. Now that's the power of VuePress!
9- title: Documentation made with VuePress
10 details: This entire documentation was made with VuePress which parsed Markdown files and corresponding assets using webpack.
11footer: Developed using VuePress by William Imoh
12---
特殊的)(无论是在YAML,JSON或TOML格式)在Markdown文件中指示VuePress提供标题,lang和其他属性。
此时,您可以构建和服务应用程序,并观察到您迄今为止所拥有的内容:
1npm run docs:dev
应用程序建成后,您将收到一个成功消息,其中还提供要访问的URL(默认情况下应该是localhost:8080)。
现在,在您的 Web 浏览器中打开此 URL. Markdown 代码将生成一个按钮 Counter Component ,有关功能的信息列和脚印。
VuePress配备了热重加功能,可实现开发过程中对应用程序所做的任何更改。
但是,如果创建 Vue 组件而本地开发服务器是活跃的,则需要重新启动开发服务器。
步骤3 - 创建反对页面
对于本项目的目的,您的文档将跟踪增加和减少数值的计数组件的细节。
在docs目录中,创建一个新的.vuepress子目录:
1mkdir docs/.vuepress
在这个.vuepress目录下,创建一个新的components子目录;
1mkdir docs/.vuepress/components
现在,使用代码编辑器在.vuepress/components目录中创建一个新的counter.vue文件:
1[label docs/.vuepress/components/counter.vue]
2<template>
3 <div class="counter">
4 <h1>{{ number }}</h1>
5 <button @click="increment">Increment</button>
6 <button @click="decrement">Decrement</button>
7 </div>
8</template>
9
10<script>
11export default {
12 data() {
13 return {
14 number: 0
15 };
16 },
17 methods: {
18 increment() {
19 if (this.number >= 0) {
20 this.number++;
21 }
22 },
23 decrement() {
24 if (this.number > 0) {
25 this.number--;
26 }
27 }
28 }
29};
30</script>
31
32<style scoped>
33.counter {
34 display: inline-block;
35 margin-left: 30%;
36}
37
38button {
39 display: inline-block;
40 padding: 20px;
41 margin: 10px;
42 font-weight: bold;
43 border-radius: 5px;
44 box-shadow: 0px 0px 5px 0px rgb(11, 11, 114);
45}
46
47h1 {
48 text-align: center;
49}
50</style>
此代码会显示值(‘数字’),并根据 Increment 或** Decrement** 按钮交互的次数,该值会改变。
现在,您将创建页面以显示<counter/>组件。
在docs目录中,创建一个新的反对子目录:
1mkdir counter
现在,使用代码编辑器在docs/counter目录中创建一个新的README.md文件:
1[label docs/counter/README.md]
2---
3title: Counter Component
4---
5# Counter Component
6
7<counter/>
8
9## Details
10
11The `counter` component allows users to **Increment** and **Decrement** numeric values. The value starts at `0` and has a minimum value of `0`.
12
13### Props
14
15n/a
16
17### State
18
19n/a
在此目录中创建几个额外的页面. 此演示文稿将包含 usage.md:
1[label docs/counter/usage.md]
2---
3title: Counter Component - Usage
4---
5# Usage
6
7Currently, this component is used in our app as part of a demonstration.
其次是看也看也看。
1[label docs/counter/see-also.md]
2---
3title: Counter Component - See Also
4---
5# See Also
6
7* [Number](https://en.wikipedia.org/wiki/Number)
8* [Increment and decrement operators](https://en.wikipedia.org/wiki/Increment_and_decrement_operators)
这些文件将后来转换为静态页面。
现在你有所有所需的 Markdown 文件。
步骤 4 – 配置布局和风格
在本节中,您将配置网站以使用指定的标题,描述,nav和侧面栏。
「config.js」文件用于定制文档系统. 使用您的代码编辑器在「.vuepress」目录中创建一个新的「counter.vue」文件:
1[label docs/.vuepress/config.js]
2module.exports = {
3 title: 'VuePress',
4 description: 'A demo documentation using VuePress',
5 themeConfig: {
6 nav: [
7 { text: 'Counter', link: '/counter/' }
8 ],
9 sidebar: [
10 {
11 title: 'Counter',
12 collapsable: false,
13 children: [
14 ['/counter/usage', 'Usage'],
15 ['/counter/see-also', 'See Also']
16 ]
17 }
18 ]
19 }
20};
首先,您指定网站的标题,并分配给它一个描述,这对SEO来说是很好的。
在脚本中,接下来是themeConfig对象,它接收了在主题上实现某些功能所需的参数. 要创建一个navbar,你会创建一个包含显示文本和每个nav元素路线的对象的nav数组。
<$>[注] 注: 您可以在官方文件中了解更多关于 the navbar。
此代码还包含组合的侧栏,以便用户可以随时快速查看文档中的菜单。
<$>[注] 注: 您可以在官方文档中了解更多关于(https://vuepress.vuejs.org/theme/default-theme-config.html# sidebar)。
作为配置演示示文稿的最后一步,您将使用风格取代默认颜色。
在docs/.vuepress/目录结构下,创建一个新的风格子目录:
1mkdir docs/.vuepress/styles
现在,使用代码编辑器在.vuepress/styles目录中创建一个新的palette.styl文件:
1[label docs/.vuepress/styles/palette.styl]
2$accentColor = #cfa809
3$textColor = #2c3e50
4$borderColor = #eaecef
5$codeBgColor = #282c34
此语法和文件扩展为 Stylus sheets. VuePress 使用 Stylus 来配置颜色和分区。
保存您的更改并使用以下命令重新启动开发服务器:
1npm run docs:dev
请注意,对.styl 文件所做的更改会立即反映在浏览器中。
您现在已经完成了单个页面的文档系统。
结论
在本教程中,您开发了一个静态文档网站,这也是一个单页应用程序,使用VuePress。
VuePress 提供了在 Markdown 文件中编写 Vue 脚本的灵活性,这引入了交互式演示。
VuePress是SEO友好的,默认情况下提供了在您的页面上使用Google Analytics实施分析跟踪的手段,VuePress还提供了一个最小的搜索系统,该系统在网站上索引所有标题,并在搜索时显示它们。
通过修改项目以包括额外的文件夹和相应的 Markdown 文件来继续学习。
如果您想了解更多关于VuePress可用的选项,请参阅我们的VuePress介绍(https://andsky.com/tech/tutorials/vuejs-vuepress-introduction)。