VuePress只有用起来才能体现它的价值


theme: cyanosis

highlight: zenburn

持续创作,加速成长!这是我参与「掘金日新计划 · 6 月更文挑战」的第8天,点击查看活动详情

废话只说一句:码字不易求个👍,收藏 === 学会,快行动起来吧!🙇‍🙇‍🙇‍。

感谢点赞、收藏、关注和提出建议的小伙伴,希望大家工作顺利、老板能给你们加鸡腿!

VuePress 是一个以 Markdown 为中心的静态网站生成器。你可以使用 Markdown在新窗口打开 来书写内容(如文档、博客等),然后 VuePress 会帮助你生成一个静态网站来展示它们。

VuePress 诞生的初衷是为了支持 Vue.js 及其子项目的文档需求,但是现在它已经在帮助大量用户构建他们的文档、博客和其他静态网站。

使用上相对来说还是比较简单的,小伙伴们可以使用这个工具,来对自己所学的知识进行系统性的梳理下,以博客文章的形式展现出来,达到既有输入也有所输出。

创建项目

先创建项目目录 vuepress ,进入目录后,进行初始化项目

  1. yarn init -y
  2. // or
  3. npm init -y

安装 vuepress

  1. yarn add -D vuepress@next
  2. // or
  3. npm install -D vuepress@next

package.json 中添加一些 scripts

  1. // 官方
  2. {
  3. "scripts": {
  4. "docs:dev": "vuepress dev docs",
  5. "docs:build": "vuepress build docs"
  6. }
  7. }
  8. // 为了方便,符合日常使用习惯,这里修改如下
  9. {
  10. "scripts": {
  11. "dev": "vuepress dev docs",
  12. "build": "vuepress build docs"
  13. }
  14. }

将默认的临时目录和缓存目录添加到 .gitignore 文件中,可以通过命令写入文件,也可以直接手动创建文件通过编辑器将目录添加进去。

  1. echo node_modules >> .gitignore
  2. echo .temp >> .gitignore
  3. echo .cache >> .gitignore

创建你的第一篇文档,这里要说下,docs目录为必备目录,页面md文件和配置文件都要存储在这个目录下。

  1. mkdir docs
  2. echo # Hello VuePress > docs/README.md

创建好第一个文件后,在本地启动服务器来开发你的文档网站,执行下面的命令启动吧!

  1. yarn dev
  2. // or
  3. npm run dev

VuePress 会在 http://localhost:8080在新窗口打开 启动一个热重载的开发服务器。当你修改你的 Markdown 文件时,浏览器中的内容也会自动更新。

现在,你应该已经有了一个简单可用的 VuePress 文档网站。接下来,就可以根据 VuePress 官方配置 来配置相关的内容了。

image.png

配置项目

路由

首先先来熟悉下路由规则,其实就是根目docs 目录下的md,文档所在的目录,进行映射成对应的路由的。

假设这是你的 Markdown 文件所处的目录结构:

  1. └─ docs
  2. ├─ guide
  3. ├─ getting-started.md
  4. └─ README.md
  5. ├─ contributing.md
  6. └─ README.md

docs 目录作为你的 sourceDir ,例如你在运行 vuepress dev docs 命令。此时,你的 Markdown 文件对应的路由路径为:

相对路径 路由路径
/README.md /
/index.md /
/contributing.md /contributing.html
/guide/README.md /guide/
/guide/page.md /guide/page.html

了解好路由规则后,咱们再来看下其他的配置项是如何配置的

页面配置

Markdown 文件可以包含一个 YAML在新窗口打开 Frontmatter 。Frontmatter 必须在 Markdown 文件的顶部,并且被包裹在一对三短划线中间。下面是一个基本的示例:

  1. ---
  2. lang: zh-CN
  3. title: 页面的标题
  4. description: 页面的描述
  5. ---

这里有具体的配置信息,可以根据自己需要进行选择性的配置。

配置文件

VuePress 站点的基本配置文件是 .vuepress/config.js ,但也同样支持 TypeScript 配置文件。你可以使用 .vuepress/config.ts 来得到更好的类型提示。

  1. ├─ docs
  2. ├─ .vuepress
  3. └─ config.js
  4. └─ README.md
  5. ├─ .gitignore
  6. └─ package.json

贴一份简单的配置仅供参考,创建一份文档类型的小站这些配置基本够用了

  1. const path = require("path");
  2. const { defaultTheme } = require(vuepress);
  3. module.exports = {
  4. base: /,
  5. lang: zh-CN,
  6. title: 前端技术栈,
  7. description: 这是我的第一个 VuePress 站点,
  8. head: [
  9. // [link, { rel: icon, href: /idec.ico }]
  10. ],
  11. alias: {
  12. // http://localhost:8080/@fs/Users/gaby/Desktop/Web/vuepress/docs/.vuepress/public/
  13. @pub: path.resolve(__dirname, ./public),
  14. },
  15. markdown: {
  16. importCode: {
  17. handleImportPath: (str) =>
  18. str.replace(/^@src/, path.resolve(__dirname, src)),
  19. },
  20. },
  21. plugins: [],
  22. theme: defaultTheme({
  23. // URL
  24. logo: https://vuejs.org/images/logo.png,
  25. // repo: https://gitlab.com/foo/bar, // 仓库地址
  26. // 默认主题配置
  27. navbar: [
  28. {
  29. text: 首页,
  30. link: /,
  31. },
  32. {
  33. text: 工具类,
  34. children: [
  35. {
  36. text: storage,
  37. link: /utils/storage.html
  38. },{
  39. text: Log,
  40. link: /utils/log.html
  41. }
  42. ]
  43. },
  44. // 字符串 - 页面文件路径
  45. /bar/README.md,
  46. ],
  47. // 侧边栏对象
  48. // 不同子路径下的页面会使用不同的侧边栏
  49. // 可折叠的侧边栏 需要参数 collapsible: true,
  50. sidebar: {
  51. /:[
  52. {
  53. text: Foo,
  54. collapsible: true,
  55. children: [
  56. // SidebarItem
  57. {
  58. text: github,
  59. link: https://github.com,
  60. children: [],
  61. },
  62. // 字符串 - 页面文件路径
  63. /foo/bar.md,
  64. ],
  65. },
  66. // 字符串 - 页面文件路径
  67. /bar/README.md,
  68. ],
  69. /utils/: [
  70. {
  71. text: 工具类,
  72. children: [
  73. {
  74. text: storage,
  75. link: /utils/storage.html
  76. },
  77. {
  78. text: Log,
  79. link: /utils/log.html,
  80. },
  81. // /guide/README.md, /guide/getting-started.md
  82. ],
  83. },
  84. ],
  85. /reference/: [
  86. {
  87. text: Reference,
  88. children: [/reference/cli.md, /reference/config.md],
  89. },
  90. ],
  91. }
  92. })
  93. }

image.png

这个是文件目录,可以通过 styles/index.scss 进行样式重写。

小结

好东西还是得用,才能体现他的价值,这里只做抛转引入,给大家简单介绍下使用,后续有时间再对自定义主题进行输出一篇,以帮助更多想伙伴进行主题的自定义。


文章标签:

原文连接:https://juejin.cn/post/7106505335778574349

相关推荐

JavaScript进阶内容——BOM详解

Vue详解知识概括

叮!您要的‘this绑定规则’来了

JavaScript必须掌握的四大基础知识(数据类型、原型和原型链、闭包、异步 promise)

JavaScript进阶内容——DOM详解

「React进阶」React中没有keepalive?没事!手把手教你从零到一设计并实现一个!

JavaScript基础系列(6):`this`这六种使用方式

回忆曾跨过的坎:详尽解析前端性能优化体系(一)

[教你做小游戏] 只用几行原生JS,写一个函数,播放音效、播放BGM、切换BGM

我在腾讯这一年

趣味Canvas之时钟⏰

Chrome插件开发教程

我的灿烂前端人生

JavaScript 中的单例内置对象(Global & Math)

JavaScript:聊聊作用域、作用域链与它的一些优化

『JavaScript从零开始』防抖与节流

ES6 类聊 JavaScript 设计模式之创建型模式

玩转React基础 Hook

用原生JS写一个简易版的台球

(建议收藏)JS中5个处理树结构数据的常用方法及如何将其发布到npm上的教程讲解