Vuepress 2从0-1保姆级进阶教程——标准化流程(Tailwindcss v4+commitizen)
Vuepress 2 专栏目录【已完结】
1. 入门阶段
- Vuepress 2从0-1保姆级入门教程——环境配置篇
- Vuepress 2从0-1保姆级入门教程——安装流程篇
- Vuepress 2从0-1保姆级入门教程——文档配置篇
- Vuepress 2从0-1保姆级入门教程——主题与部署
2.进阶阶段
更新日志
支持Tailwind CSS v4版本（提供两种方式）
添加Tailwind CSS 模版库网站
修订Tailwind CSS v3安装说明
换用czg自动提交commit工具
添加Tailwind CSS禁用Preflight方法
引用块样式矢量放大3倍，更加清晰
logo等静态文件：https://wwk.lanzouo.com/b04x8f3hg
密码：666
仓库：https://gitee.com/passwordgloo/vuepress2-tutorial
git clone git@gitee.com:passwordgloo/vuepress2-tutorial.git
cd vuepress2-tutorial
pnpm install
# 谨慎更新包
# pnpm docs:update-package
一、样式
美化与模版更多是自己手写样式，我们学习使用Tailwind CSS，使用它丰富的模版、组件，简化我们的书写
如果你专注写作，请跳过样式
（一）介绍
Tailwind CSS 是一个以 Utility Class 为基础的 CSS 框架和设计系统，可以快速地为组件添加常用样式，同时支持主题样式的灵活扩展
初次使用Tailwind css会被它的class恶心到，比如自定义一个按钮样式
<button type="button" class="relative w-full cursor-default rounded-md bg-white py-1.5 pl-3 pr-10 text-left text-gray-900 shadow-sm ring-1 ring-inset ring-gray-300 focus:outline-none focus:ring-2 focus:ring-indigo-500 sm:text-sm sm:leading-6" aria-haspopup="listbox" aria-expanded="true" aria-labelledby="listbox-label">
<span class="ml-3 block truncate">Tom Cook</span>
</button>
但是用的时间长了，你可以从class名字直接了解样式信息，一些重复写的样式直接拿来用
Tailwind CSS 搭配autoprefixer更佳，那autoprefixer是干啥的？
由于浏览器厂商对标准制定的争夺大战，css3有些写法到今天都没统一下来， 各个浏览器写法不同，比如写个动画延时，虽然现在大多数浏览器支持标准写法animation-delay，考虑到各种浏览器旧版本兼容问题，要这样写（略微夸张，实际不会写那么多）：
.test{
-moz-animation-delay:.3s;
-webkit-animation-delay:.3s;
-o-animation-delay: .3s;
animation-delay: .3s;
}
前缀-moz(火狐浏览器)、-webkit(Chrome浏览器)、-o(opera浏览器)指代不同的浏览器。Autoprefixer是一个用于添加浏览器前缀的工具，在代码打包后自动运行
Tailwind CSS v3借助postcss生成css，具体过程参见程序员晚天的Tailwind CSS PostCSS 插件都做了些什么？
（二）模版
1. 站点
https://www.hyperui.dev (仅限Tailwind CSS 4)
https://tailblocks.cc
https://merakiui.com (支持Tailwind CSS 4，Tailwind CSS 3版本谨慎使用)
https://www.creative-tim.com/templates/tailwind
https://windytoolbox.com（部分模版会标注付费）
https://tailwindtemplates.io/templates
https://www.material-tailwind.com
https://daisyui.com
2. 样式测试
（三）安装
方式一满足大多数人需求
方式二仅支持主流浏览器2023年3月后版本
方式三监视文档代码，只输出已有Tailwind css样式到index.scss
根据自己需要选择相应版本
方式一：Tailwind CSS v3
pnpm install -D tailwindcss@3 postcss autoprefixer
1.初始化配置
新建tailwind.config.js，postcss.config.js配置文件
编辑tailwind.config.js
/** @type {import('tailwindcss').Config} */
export default {
content: [
//./**/*.md", 不建议使用通配符，会消耗性能
"./docs/about.md",
"./docs/.vuepress/layouts/NotFound.vue",
"./.vuepress/**/*.{vue,js,ts,jsx,tsx}",
],
theme: {
colors: {
'blue': '#1fb6ff',
'purple': '#7e5bef',
'pink': '#ff49db',
'orange': '#ff7849',
'green': '#13ce66',
'yellow': '#ffc82c',
'gray-dark': '#273444',
'gray': '#8492a6',
'gray-light': '#d3dce6',
},
extend: {},
},
plugins: [],
}
【可选，心理安慰操作】编辑postcss.config.js，其实没必要建，因为起作用的是下面样式调用里的配置
export default {
plugins: {
tailwindcss: {},
autoprefixer: {},
},
}
2.样式调用
Tailwind CSS base基础样式默认注入preflight，和Normalize.css功能一样，重置浏览器的默认样式，优先性很高，默认主题样式会冲突，需要禁用。
在.vuepress/styles/index.scss调用
/* @tailwind base; 不启用，vuepress会覆盖掉样式*/
@tailwind components;
@tailwind utilities;
3.配置
import autoprefixer from 'autoprefixer'
import tailwindcss from 'tailwindcss'
export default defineUserConfig({
bundler: viteBundler({
viteOptions: {
css: {
postcss: {
plugins: [
autoprefixer({
overrideBrowserslist: ['Chrome > 40', 'ff > 31', 'ie 11'],
}),
tailwindcss()
]
}
}
}
}),
})
4.测试
在.vuepress/styles/index.scss里面添加样式
.test{
animation-delay: .3s;
}
🏅 pnpm docs:build查看📁dist，成功奏效
编辑about.md文件，添加以下代码
<div class="relative mt-2">
<button type="button" class="relative w-full cursor-default rounded-md bg-white py-1.5 pl-3 pr-10 text-left text-gray-900 shadow-sm ring-1 ring-inset ring-gray-300 focus:outline-none focus:ring-2 focus:ring-indigo-500 sm:text-sm sm:leading-6" aria-haspopup="listbox" aria-expanded="true" aria-labelledby="listbox-label">
<span class="flex items-center">
<img src="https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=facearea&facepad=2&w=256&h=256&q=80" alt="" class="h-5 w-5 flex-shrink-0 rounded-full">
<span class="ml-3 block truncate">Passwordgloo</span>
</span>
<span class="pointer-events-none absolute inset-y-0 right-0 ml-3 flex items-center pr-2">
<svg class="h-5 w-5 text-gray-400" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true">
<path fill-rule="evenodd" d="M10 3a.75.75 0 01.55.24l3.25 3.5a.75.75 0 11-1.1 1.02L10 4.852 7.3 7.76a.75.75 0 01-1.1-1.02l3.25-3.5A.75.75 0 0110 3zm-3.76 9.2a.75.75 0 011.06.04l2.7 2.908 2.7-2.908a.75.75 0 111.1 1.02l-3.25 3.5a.75.75 0 01-1.1 0l-3.25-3.5a.75.75 0 01.04-1.06z" clip-rule="evenodd" />
</svg>
</span>
</button>
</div>
然后pnpm docs:dev查看
方式二：Tailwind CSS v4（postcss）
Tailwind CSS v4版本进行了大刀阔斧的变革，无需使用sass等构建工具，不再需要安装autoprefixer等插件，换来的代价是Tailwind CSS v4.0 无法在较旧的浏览器中工作。
另外，Vite环境从tailwind v3 升级到 v4需要注意新变化
1.安装插件
pnpm install tailwindcss @tailwindcss/postcss postcss
2.编辑config.ts
import tailwindcss from '@tailwindcss/postcss'
export default defineUserConfig({
bundler: viteBundler({
viteOptions: {
css: {
postcss: {
plugins: [
tailwindcss()
]
}
}
}
})
})
3.编辑index.scss文件
Tailwind CSS v4 Preflight 重置了基础样式
两种解决方式，一是自己按需覆盖掉原样式，适合小打小闹
@use "tailwindcss";
//覆盖图片样式块元素，保护logo不换行
@layer base{
img{
display: inline;
}
}
二是干脆不引入base，直接不和其他样式冲突
@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/utilities.css" layer(utilities);
4.测试
编辑任意一个文档，添加Tailwind CSS代码测试效果
<h1 class="text-3xl font-bold underline">
Hello world!
</h1>
<p class="text-blue-600 dark:text-sky-400">The quick brown fox...</p>
<span
class="rounded-full bg-purple-100 px-2.5 py-0.5 text-sm whitespace-nowrap text-purple-700 dark:bg-purple-700 dark:text-purple-100">
Live
</span>
<span
class="rounded-full border border-purple-500 px-2.5 py-0.5 text-sm whitespace-nowrap text-purple-700 dark:text-purple-100">
Live
</span>
测试成功～
方式三：Tailwind CSS v4（CLI）
不需要安装postcss插件
pnpm install tailwindcss @tailwindcss/cli
在📁 styles下新建input.css，输入
@import "tailwindcss";
不想用base样式，参阅方式二的解决方法👆
监听文档，并转化输出为index.scss文件
npx @tailwindcss/cli -i ./docs/.vuepress/styles/input.css -o ./docs/.vuepress/styles/index.scss --watch
然后编辑任意一个文档，添加Tailwind CSS代码测试效果，index.scss文件会自动更新样式
生产端想最小化css文件，输入
npx @tailwindcss/cli -i ./docs/.vuepress/styles/input.css -o ./docs/.vuepress/styles/index.scss --minify
二、Commit
是不是经常发现自己推送的commit不知道做了啥，Changelog不想写？随便一写，后面版本更迭，摸不到头脑，用以下工具更好的帮你理清思路
（一）cz-git
1.安装
pnpm install -D czg
2.修改package.json
czg不需要单独安装commitment，支持表情、ai总结，详见czg交互式命令行工具
"scripts": {
"docs:build": "vuepress build docs",
"docs:clean-dev": "vuepress dev docs --clean-cache",
"docs:dev": "vuepress dev docs",
"docs:update-package": "pnpm dlx vp-update",
"commit": "git add . && czg emoji"
},
3.配置模版
模版任选其一
简写版
根目录新建.czrc，下面的scopes指定范围，后续可参照全文版添加新的参数
{
"$schema": "https://cdn.jsdelivr.net/gh/Zhengqbbb/cz-git@1.11.0/docs/public/schema/cz-git.json",
"scopes": [
"css",
"scss",
"tailwindcss"
],
"allowBreakingChanges": [
"docs",
"fix"
]
}
全文版
根目录新建commitlint.config.cjs（esm规范项目）
// commitlint.config.cjs
/** @type {import('cz-git').UserConfig} */
module.exports = {
rules: {
// @see: https://commitlint.js.org/#/reference-rules
},
prompt: {
alias: { fd: 'docs: fix typos' },
messages: {
type: '选择你要提交的类型 :',
scope: '选择一个提交范围（可选）:',
customScope: '请输入自定义的提交范围 :',
subject: '填写简短精炼的变更描述 :\n',
body: '填写更加详细的变更描述（可选）。使用 "|" 换行 :\n',
breaking: '列举非兼容性重大的变更（可选）。使用 "|" 换行 :\n',
footerPrefixesSelect: '选择关联issue前缀（可选）:',
customFooterPrefix: '输入自定义issue前缀 :',
footer: '列举关联issue (可选) 例如: #31, #I3244 :\n',
confirmCommit: '是否提交或修改commit ?'
},
types: [
{ value: 'feat', name: '✨ feat: 新的功能 | A new feature' },
{ value: 'fix', name: '🐞 fix: Bug 修复 | A bug fix' },
{ value: 'docs', name: '📚 docs: 文档更新 | Documentation only changes' },
{ value: 'style', name: '💅 style: 代码格式 | Changes that do not affect the meaning of the code' },
{ value: 'refactor', name: '🔨 refactor: 功能重构 | redesign structure of project' },
{ value: 'perf', name: '🌸 perf: 性能优化 | A code change that improves performance' },
{ value: 'test', name: '🏁 test: 测试相关 | Adding missing tests or correcting existing tests' },
{ value: 'build', name: '🧰 build: 构建相关 | Changes that affect the build system or external dependencies' },
{ value: 'revert', name: '⏪ revert: 回退代码 | Revert to a commit' },
{ value: 'chore', name: '⚪ chore: 其他修改 | Other changes that do not modify src or test files' },
],
useEmoji: true,
emojiAlign: 'center',
useAI: false,
aiNumber: 1,
themeColorCode: '',
scopes: [],
allowCustomScopes: true,
allowEmptyScopes: true,
customScopesAlign: 'bottom',
customScopesAlias: 'custom',
emptyScopesAlias: 'empty',
upperCaseSubject: false,
markBreakingChangeMode: false,
allowBreakingChanges: ['feat', 'fix','chore','style'],
breaklineNumber: 100,
breaklineChar: '|',
skipQuestions: [],
issuePrefixes: [
// 如果使用 gitee 作为开发管理
{ value: 'link', name: 'link: 链接 ISSUES 进行中' },
{ value: 'closed', name: 'closed: 标记 ISSUES 已完成' }
],
customIssuePrefixAlign: 'top',
emptyIssuePrefixAlias: 'skip',
customIssuePrefixAlias: 'custom',
allowCustomIssuePrefix: true,
allowEmptyIssuePrefix: true,
confirmColorize: true,
scopeOverrides: undefined,
defaultBody: '',
defaultIssues: '',
defaultScope: '',
defaultSubject: ''
}
}
4.项目提交
pnpm commit
(二）conventional-changelog
发布新版本时，使用angular格式自动更新 CHANGELOG.md 文件，减少手动工作
1.安装
pnpm install -D conventional-changelog-cli
2.修改快捷指令
修改package.json，
"scripts": {
"docs:build": "vuepress build docs",
"docs:clean-dev": "vuepress dev docs --clean-cache",
"docs:dev": "vuepress dev docs",
"docs:update-package": "pnpm dlx vp-update",
"commit": "git add . && czg emoji",
"changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 2"
},
3.使用
pnpm changelog
尾声
🎉 Vuepress 2 保姆级教程已全部更新完毕！涵盖环境搭建、Vuepress 2安装、主题文档配置、美化与模版、全文搜索等内容。
🐮 全网仅次于官方文档的保姆级教程，远远超越那些教你下载安装的低劣教程
🪫 个人精力有限，除非Vuepress 2后续有大更新，否则内容不做大的调整
浙公网安备 33010602011771号