Предисловие:
VuePress особенно хорош для поддержки потребностей документа и его подпроектов. Vue написал проект, интерфейс VuePress очень прост, иНачать работу очень просто, а структуру проекта можно настроить за час.. Уже есть много документации такого типа, и если у вас есть проект, который требует написания технической документации, VuePress определенно может быть одним из ваших вариантов.
Узнайте о плавании и фитнесе:блог,Документы внешнего накопления,Нет публики,GitHub
Возможности VuePress:
- Встроенные расширения Markdown, оптимизированные для технической документации
- Возможность использовать компоненты Vue в файлах Markdown
- Пользовательская система тем на базе Vue
- Автоматически генерировать сервис-воркеров
- Интеграция с Google Аналитикой
- «Последнее обновление» на основе Git
- Многоязычная поддержка
- Темы по умолчанию включают:
Рекомендуется ознакомитьсяофициальная документация
Эффект:
Может быть, вы можете построить что-то вроде этогоДокументация:
Строить:
Установите VuePress глобально
yarn global add vuepress # 或者：npm install -g vuepress
новая папка
Вы можете вручную щелкнуть правой кнопкой мыши, чтобы создать новую папку, или вы можете использовать следующую команду для создания новой папки:
mkdir project
Инициализация проекта
Войтиprojectпапку, используйте командную строку для инициализации проекта:
yarn init -y # 或者 npm init -y
создастpackage.jsonФайл выглядит так:
{
"name": "project",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC"
}
Создайте новую папку docs в корневом каталоге проекта:
Этот документ будет использоваться как корень документации проекта:
mkdir docs
Создал в папке docs.vuepressпапка:
mkdir .vuepress
Здесь будут размещены все файлы, связанные с VuePress.
существует.vuepressСоздано под папкойconfig.js:
touch config.js
config.js — необходимый файл конфигурации для VuePress, он экспортирует объект javascript.
Сначала вы можете добавить следующую конфигурацию:
module.exports = {
title: 'Hello VuePress',
description: 'Just playing around'
}
существует.vuepressСоздайте общую папку в папке:
mkdir public
Эта папка используется для размещения статических ресурсов, после упаковки они будут размещены в корневом каталоге .vuepress/dist/.
Домашняя страница (например, домашняя страница документации VuePress)
Создайте файл в папке docsREADME.md:
Тема по умолчанию предоставляет домашнюю страницу, установленную, как показано ниже.home:trueВы можете установить следующие параметры вREADME.md, позже вы увидитеVuePressта самая домашняя страница.
---
home: true
heroImage: /logo.jpg
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
---
ps: Вам нужно поместить изображение в общую папку.
Наша структура проекта была настроена:
project
├─── docs
│ ├── README.md
│ └── .vuepress
│ ├── public
│ └── config.js
└── package.json
существуетpackage.jsonДобавьте две команды запуска:
{
"scripts": {
"docs:dev": "vuepress dev docs",
"docs:build": "vuepress build docs"
}
}
Запустите VuePress:
По умолчаниюlocalhost:8080порт.
yarn docs:dev # 或者：npm run docs:dev
Конструкция:
build генерирует статические файлы HTML, которые по умолчанию будут генерироваться в.vuepress/distв папке
yarn docs:build # 或者：npm run docs:build
базовая конфигурация:
Самый стандартный конечноофициальная документация, вы можете настроить его в соответствии с вашими потребностямиconfig.js.
Вы можете обратиться к моемуconfig.jsКонфигурация:
module.exports = {
title: '网站标题',
description: '网站描述',
// 注入到当前页面的 HTML <head> 中的标签
head: [
['link', { rel: 'icon', href: '/favicon.ico' }], // 增加一个自定义的 favicon(网页标签的图标)
],
base: '/web_accumulate/', // 这是部署到github相关的配置 下面会讲
markdown: {
lineNumbers: true // 代码块显示行号
},
themeConfig: {
sidebarDepth: 2, // e'b将同时提取markdown中h2 和 h3 标题，显示在侧边栏上。
lastUpdated: 'Last Updated' // 文档更新时间：每个文件git最后提交的时间
}
};
Конфигурация панели навигации:
module.exports = {
themeConfig: {
nav:[
{ text: '前端算法', link: '/algorithm/' }, // 内部链接 以docs为根目录
{ text: '博客', link: 'http://obkoro1.com/' }, // 外部链接
// 下拉列表
{
text: 'GitHub',
items: [
{ text: 'GitHub地址', link: 'https://github.com/OBKoro1' },
{
text: '算法仓库',
link: 'https://github.com/OBKoro1/Brush_algorithm'
}
]
}
]
}
}
Конфигурация боковой панели:
Конфигурация сайдбара относительно хлопотная, в ней я сделал подробные комментарии, если внимательно присмотритесь, то поймете, как это сделать самостоятельно.
module.exports = {
themeConfig: {
sidebar:{
// docs文件夹下面的accumulate文件夹 文档中md文件 书写的位置(命名随意)
'/accumulate/': [
'/accumulate/', // accumulate文件夹的README.md 不是下拉框形式
{
title: '侧边栏下拉框的标题1',
children: [
'/accumulate/JS/test', // 以docs为根目录来查找文件
// 上面地址查找的是：docs>accumulate>JS>test.md 文件
// 自动加.md 每个子选项的标题 是该md文件中的第一个h1/h2/h3标题
]
}
],
// docs文件夹下面的algorithm文件夹 这是第二组侧边栏 跟第一组侧边栏没关系
'/algorithm/': [
'/algorithm/',
{
title: '第二组侧边栏下拉框的标题1',
children: [
'/algorithm/simple/test'
]
}
]
}
}
}
разное:
Ошибка компиляции блока кода:
Код, подобный следующему, вызовет ошибку компиляции, VuePress будет искать в нем переменную и компилировать ее в текст:
{{}} 啦 {{}}
Итак, наш блок кода должен быть записан в таком виде:
//```js
{{}} 啦 {{}} // 注释需要打开 这样vuepress会把这里面包裹的当成代码块而不是js
//```
И это также сделает наш код выделенным (первый не выделен на следующем рисунке, выделен второй), и опыт чтения улучшится:
Взгляните на пользовательские контейнеры:
Изменить заголовок:
::: tip 替换tip的标题
这里是内容。
:::
фактическиДокументацияДа, я просто упоминаю это здесь.
Поддержка эмодзи
В документации упоминается только поддержка Emoji, я нашел Emoji на GitHub.список,доля.
Командная строка, размещенная на github:
существуетdocs/.vuepress/config.jsУстановите правильную базу в:
Если вы планируете публиковаться вhttps://<USERNAME>.github.io/, вы можете пропустить этот шаг, потому что базовое значение по умолчанию равно"/".
Если вы планируете публиковаться вhttps://<USERNAME>.github.io/<REPO>/(то есть ваш репозиторий находится вhttps://github.com/<USERNAME>/<REPO>), установить базу на"/<REPO>/".
module.exports = {
base: '/test/', // 比如你的仓库是test
}
Создайте файл шагов:
существуетprojectв корневом каталоге создайтеdeploy.shдокумент:
#!/usr/bin/env sh
# 确保脚本抛出遇到的错误
set -e
# 生成静态文件
npm run docs:build
# 进入生成的文件夹
cd docs/.vuepress/dist
# 如果是发布到自定义域名
# echo 'www.example.com' > CNAME
git init
git add -A
git commit -m 'deploy'
# 如果发布到 https://<USERNAME>.github.io USERNAME=你的用户名
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master
# 如果发布到 https://<USERNAME>.github.io/<REPO> REPO=github上的项目
# git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages
cd -
Настройте package.json:
{
"scripts": {
"d": "bash deploy.sh"
}
}
развертывать:
Затем вы можете запускать следующую командную строку каждый раз, чтобы отправлять последние изменения вgithubначальство:
npm run d
Если вам надоела командная строка для запуска и сборки вашего проекта, вы можете сделать это, как я:
"scripts": {
"dev": "vuepress dev docs", // 本地运行项目 npm run dev
"build": "vuepress build docs", // 构建项目 nom run build
"d": "bash deploy.sh" // 部署项目 npm run d
},
Более:
На самом деле существует гораздо больше конфигураций и применений VuePress, таких как настройка PWA и использование компонентов Vue в уценке и т. д. Я все еще изучаю эти функции, поэтому вы должны их увидеть.Документация!
Эпилог
Выше было написано максимально подробно, и описаны все ямы, с которыми я столкнулся. Это действительно легко построить. Лучше действовать, если вы хотите. Просто потратьте час или два на строительство, и вы не будете страдать. Почему бы не сделать это?
Я надеюсь, что друзья, которые прочитали это, могут нажать «Нравится» / «Подписаться», ваша поддержка — самая большая поддержка для меня.
блог,Документы внешнего накопления,Нет публики,GitHub
Выше 2018.9.9