因为写过开源的简单入门案例,附加的md文档详细说明,但总觉得不是很规范不是非常美观,所以萌生了如何去快速生成静态网站,像基于elementui开源的vue-element-admin文档那样赏心悦目,所以总结了下内容:
- loppo: 非常简单的静态站点生成器
- idoc:简单的文档生成工具
- gitbook:大名鼎鼎的文档协作工具
- docsify:一个神奇的文档站点生成器,简单轻巧,无需静态构建htmldocsify官网地址
- mkdoc
- read the doc
以上几款都是快速生成文档的,其中我使用过docsify,使用方法就不赘述,可自行查看其他作者文档:docsify - 生成文档网站简单使用教程
参考下我随便做的效果:
如上图:可以很明显看到涉及到代码部分没有黑色背景色,找遍百度终于在gitee找到答案,VuePress!!!
官网地址快速上手vuepress
mkdir vuepress-starter && cd vuepress-starter
新建vuepress-starter文件夹,再进入vuepress-starter
npm init
初始化项目
npm install -D vuepress
本地安装vuepress
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
在package.json中添加配置
npm run docs:dev
本地启动服务器
进本目录结构
.
├── docs
│ ├── .vuepress (可选的)
│ │ ├── components (可选的)
│ │ ├── theme (可选的)
│ │ │ └── Layout.vue
│ │ ├── public (可选的)
│ │ ├── styles (可选的)
│ │ │ ├── index.styl
│ │ │ └── palette.styl
│ │ ├── templates (可选的, 谨慎配置)
│ │ │ ├── dev.html
│ │ │ └── ssr.html
│ │ ├── config.js (可选的)
│ │ └── enhanceApp.js (可选的)
│ │
│ ├── README.md
│ ├── guide
│ │ └── README.md
│ └── config.md
│
└── package.json
在.vuepress文件夹同济目录下的README.md文件可添加内容
---
home: true
heroImage: /hero.png
heroText: Hero 标题
tagline: Hero 副标题
actionText: 快速上手 →
actionLink: /zh/guide/
features:
- title: 简洁至上
details: 以 Markdown 为中心的项目结构,以最少的配置帮助你专注于写作。
- title: Vue驱动
details: 享受 Vue + webpack 的开发体验,在 Markdown 中使用 Vue 组件,同时可以使用 Vue 来开发自定义主题。
- title: 高性能
details: VuePress 为每个页面预渲染生成静态的 HTML,同时在页面被加载的时候,将作为 SPA 运行。
footer: MIT Licensed | Copyright © 2018-present Evan You
---
在.vuepress文件夹的config.js文件添加
module.exports = {
themeConfig: {
logo: '/assets/img/logo.png', //导航Logo
nav: [ //右上角导航栏链接
{ text: 'Home', link: '/' },
{ text: 'Guide', link: '/guide/' },
{ text: 'External', link: 'https://google.com' },
],
sidebar: { //侧边栏
'/foo/': [
'', /* /foo/ */
'one', /* /foo/one.html */
'two' /* /foo/two.html */
],
'/bar/': [
'', /* /bar/ */
'three', /* /bar/three.html */
'four' /* /bar/four.html */
],
// fallback
'/': [
'', /* / */
'contact', /* /contact.html */
'about' /* /about.html */
]
}
}
}
效果: