Olá a todos, meu nome é Hongyan. Não muito tempo atrás, a documentação oficial do Vue3 ganhou um novo visual, e essa mudança é louvável. Como desenvolvedor, escrever documentação técnica para o seu trabalho também é uma habilidade importante. Vamos apresentar em detalhes como usar o scaffolding de linha de comando para construir rapidamente um site como a documentação oficial mais recente do Vue.
começo rápido
Execute o seguinte comando na linha de comando:
npm init @quick-start/docs
复制代码Este comando irá instalar e executar a ferramenta scaffolding create-docs. Você verá dicas para alguns recursos opcionais, como temas e suporte a TypeScript:
✔ Project name: … <my-docs>
✔ Select a theme: › vue
✔ Add TypeScript? … No / Yes
Scaffolding project in ./<my-docs>...
Done.
复制代码Após criar o projeto, siga as instruções para instalar as dependências e iniciar o servidor de desenvolvimento:
> cd <my-docs>
> npm install
> npm run dev
复制代码Estrutura do diretório principal do projeto:
.
├──.vitepress
│ ├──theme
│ │ └──index.ts
│ └──index.ts
├──.vscode
├──docs
│ ├──public
│ │ └──...
│ ├──...
│ └──index.md
├──.editorconfig
├──.prettierrc.yaml
├──env.d.ts
├──package.json
└──tsconfig.json
复制代码Exibir
O mesmo estilo de interface da documentação oficial do Vue:
Modo escuro:
Responsivo:
VitePress
Todo o projeto do site é VitePressconstruído no , por que escolher o VitePress e quais são suas vantagens?
Primeiro, é importante saber que o Vitepress é Viteconstruído em cima disso e utiliza Vue3análise estática de modelo aprimorada para restringir o conteúdo estático o máximo possível.
Tem as seguintes vantagens:
- Inicialização mais rápida do serviço de desenvolvimento
- Atualizações quentes mais rápidas
- construção mais rápida
Por outro lado, a razão para escolher o VitePress é que ele empurra o minimalismo de menos configuração e páginas mais leves .
Para o uso do VitePress, não apresentaremos muito aqui, você pode acessar o site oficial para verificar:
Além disso, também queremos falar sobre suas deficiências: quando um projeto tem muitos menus de navegação e menus de barra lateral, muitas vezes é necessário dividi-los em diferentes arquivos para configuração e importá-los para o arquivo de configuração principal para uso. No entanto, o VitePress não pode monitorar hot updates para outros módulos importados em seu arquivo de configuração , o que fará com que nossas alterações de configuração não tenham efeito, e precisamos salvar manualmente o arquivo de configuração principal para acionar hot updates. Embora seja possível evitar esse problema consolidando toda a configuração no arquivo de configuração, é muito ruim para leitura e gerenciamento de código.
Por fim, resumimos:
VitePress = Vite + Vue3 + Markdown-It
主题
只有 VitePress 并不能实现像 Vue 官方文档一样的界面风格，项目还内置了一个主题插件：VitePress-Theme-Vue。
VitePress-Theme-Vue 主题是基于@vue/theme的基础上开发的。为什么不直接使用 @vue/theme 主题呢？
@vue/theme 存在一些硬编码和bug，也许开发之初就没有为其通用性考虑，只为 Vue 官网打造。
VitePress-Theme-Vue 与 @vue/theme 不同之处，或者说做了哪些优化工作：
- 移除硬编码，让其更通用
- 优化样式，更好看
- 支持公共目录下部署（这部分 @vue/theme 存在若干 bug）
- 支持YAML配置主页（@vue/theme 无主页功能）
- 更多实用组件支持（如Tag等）
对于这些优化工作，并不是通过 Fork 方式来修改代码实现，而是仍然依赖它，以获得更新和维护支持，不重复造轮子。
具体改造工作从两方面入手：
一方面，基于 @vue/theme 导出的 Layout 布局组件插槽（slots），重新编写组件对硬编码组件进行覆盖，再导出新的 Layout 布局组件。
另一方面，在前文中提到 VitePress 的本质核心还是 Vite，我们可以通过编写 Vite 插件，在构建编译时将相关组件进行替换。以下是 Vite 插件代码示例：
const bugFix = function () {
return {
name: 'replace-navbar',
enforce: 'pre',
transform(code, id) {
if (id.includes('VPNavBarTitle.vue') {
return `
// Replace Component Code
`
}
}
}
}
复制代码同时，我们将这些配置变更重新导出以便使用者扩展使用：
const baseConfig = require('@vue/theme/config')
module.exports = async () => {
let config = await baseConfig()
config.vite.plugins = [bugFix()]
//...
return config
}
复制代码在使用 VitePress-Theme-Vue 主题时，需在 VitePress 配置文件中继承配置：
// .vitepress/config.js
import { defineConfig } from 'vitepress'
import baseConfig from 'vitepress-theme-vue/config'
export default defineConfig({
extends: baseConfig,
themeConfig: {
// ...
}
})
复制代码上述方式也给我们一个思考，有时我们可以通过这种方式来紧急修复一些第三方组件bug，而不是干等。
VitePress-Theme-Vue 项目地址：
VitePress-Theme-Vue 文档手册：
结语
create-docs项目现在已经开源，欢迎各位感兴趣的小伙伴参与贡献提交 PR 或反馈 issue，给予 star 支持。
开始你的文档写作吧！
npm init @quick-start/docs
复制代码