Goalonez Blog

Appearance

VitePress博客搭建 ​

Node.js环境安装 ​

Volta安装 ​

  • 建议使用Volta进行版本管理

Linux or MacOS安装 ​

shell
curl https://get.volta.sh | bash

Windows安装 ​

Volta安装

安装Node.js ​

shell
volta install node@18.17.1

安装VitePress ​

创建一个目录 ​

shell
mkdir blog
cd ./blog

安装依赖 ​

shell
npm add -D vitepress

VitePress 附带一个命令行设置向导 ​

可帮助您构建基本项目。安装后，通过运行以下命令启动向导

shell
npx vitepress init
shell
┌   Welcome to VitePress! 
│
◇  Where should VitePress initialize the config?
│  ./docs
│
◇  Site title:
│  test
│
◇  Site description:
│  A VitePress Site
│
◇  Theme:
│  Default Theme
│
◇  Use TypeScript for config and theme files?
│  Yes
│
◇  Add VitePress npm scripts to package.json?
│  Yes
│
└  Done! Now run npm run docs:dev and start writing.

这时候会拥有一个初始化结构 ​

  • 自建一下目录和文件
shell
.
├─ .github                       //这个目录自建，用于存放部署脚本
│  └─ workflows                  //这个目录自建，用于存放部署脚本
│       └─ deploy.yml            //这个文件自建，用于部署脚本
├─ docs
│  ├─ .vitepress
│  │    ├─ components            //这个目录自建，用于存放组件
│  │    │    └─ post-comments.vue //这个文件自建，用于引入评论组件
│  │    ├─ theme                 //这个目录自建，用于存放主题相关文件
│  │    │    ├─ custom.css       //这个文件自建，用于存放自定义样式
│  │    │    └─ index.ts         //这个文件自建，用于引入主题和组件
│  │    └─ config.mts
│  ├─ blog                       //这个目录自建，用于存放博客内容
│  ├─ public                     //这个目录自建，用来存放公共资源等，引用的时候路径不需要包含public
│  │    ├─ logo.ico              //浏览器图标，自己找图
│  │    └─ logo.png              //首页右侧图片和logo，自己找图
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  └─ index.md
└─ package.json

package.json自带脚本 ​

json
{
  ...
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  },
  ...
}

调试 ​

shell
npm run docs:dev

构建 ​

shell
npm run docs:build

使用Volta固定Node.js版本 ​

shell
volta pin node@18.17.1

这时候package.json会自动生成以下内容 ​

json
"volta": {
    "node": "18.17.1"
}

这时候进入当前项目目录，会自动切换到该Node.js版本 ​

配置 ​

首页 ​

  • 编辑./docs/index.md
yaml
---
layout: home

hero:
  name: "Goalonez"
  text: "Hello World"
  tagline: 万变不离其宗
  image:
        src: /logo.png
        alt: Goalonez
  actions:
    - theme: brand
      text: 随便看看
      link: /aboutme

features:
  - title: Telegram
    details: 即刻与我联系
    link: https://t.me/Goalonez
  - title: Email
    details: 不妨给我发封电子邮件
    link: mailto:z4781854680@gmail.com
  - title: Twitter
    details: 欢迎在Twitter上关注我
    link: https://twitter.com/Goalonez
---

image-20230904160641701

主题设置 ​

  • 编辑./docs/.vitepress/theme/index.ts

  • 引入默认主题

  • 引入自定义css文件

ts
import DefaultTheme from 'vitepress/theme';
import './custom.css';

export default {
  ...DefaultTheme,
  enhanceApp(ctx) {
    DefaultTheme.enhanceApp(ctx)
  },
};

  • 编辑./docs/.vitepress/theme/custom.css

  • 参考以下官方链接

https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css

  • 我主要调整了以下内容
css
/* 整体配色改成绿色 */
:root {
    --vp-c-green-1: #52b788;
    --vp-c-green-2: #52b788;
    --vp-c-green-3: #52b788;
    --vp-c-green-soft: rgba(16, 185, 129, 0.16);
}
/* 整体配色改成绿色（暗黑模式） */
.dark {
    --vp-c-green-1: #52b788;
    --vp-c-green-2: #52b788;
    --vp-c-green-3: #52b788;
    --vp-c-green-soft: rgba(16, 185, 129, 0.16);
}
/* 整体配色改成绿色 */
:root {
    --vp-c-brand-1: var(--vp-c-green-1);
    --vp-c-brand-2: var(--vp-c-green-2);
    --vp-c-brand-3: var(--vp-c-green-3);
    --vp-c-brand-soft: var(--vp-c-green-soft);
}
:root {
  /* 设置主题字体颜色 */
  --vp-home-hero-name-color: transparent;
  --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #bd34fe, #41d1ff);

  /* 设置右图像渐变 */
  --vp-home-hero-image-background-image: linear-gradient( -45deg, #6a00f4 30%, #ffffff 70% );
  --vp-home-hero-image-filter: blur(130px);
}

/* 引用块配色 */
.vp-doc blockquote {
  background-color: #ecf8f3;
  border-left: solid #42b983 !important;;
}
/* 引用块配色（暗黑模式） */
.dark .vp-doc blockquote {
  background-color: #4a5f53;
  border-left: solid #b9eed6 !important;;
}
/* 引用块配色（暗黑模式字体） */
.dark .vp-doc blockquote > p {
  color: #92cab2;
}

核心配置 ​

  • 编辑./docs/.vitepress/config.mts

  • 具体直接参考下面的配置吧

ts
import { defineConfig } from 'vitepress'

export default defineConfig({
  // 标题（浏览器后缀）
  title: "Goalonez",
  // 描述
  description: "Goalonez Blog",
  // 语言
  lang: 'zh-CN',
  // 根目录，如果需要部署成htpps://github.com/blog/的形式，则设置/blog/
  base: '/',
  // 文档最后更新时间展示
  lastUpdated: true,
  // 去除浏览器链接中的.html后缀
  cleanUrls: true,
  // markdown显示行数
  markdown: {
    lineNumbers: true,
  },
  // head设置
  head: [
    // 浏览器中图标
    ["link", {rel: "icon", href: "/logo.ico"}],
    // 添加百度统计代码
    ['script', {},
    `
      var _hmt = _hmt || [];
      (function() {
        var hm = document.createElement("script");
        hm.src = "https://hm.baidu.com/hm.js?自己申请";
        var s = document.getElementsByTagName("script")[0]; 
        s.parentNode.insertBefore(hm, s);
      })();
    `
    ]
  ],
  // 主题设置
  themeConfig: {
    // 左上角logo
    logo: '/logo.png',
    // 首页右上角导航栏
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Blog', link: '/aboutme' }
    ],
    // 文章左侧导航栏
    sidebar: [
      {
        text: '博客',
        items: [
          { text: 'About Me', link: '/aboutme' }
        ]
      }
    ],
    // 文章底部导航栏的自定义配置，默认是英语
    docFooter: {
			prev: '上一篇',
			next: '下一篇',
		},
    // 文章右侧目录展示级别和标题
    outline: {
      level: [2, 6],
      label: '文章目录'
    },
    // 文章更新时间的前缀文本
    lastUpdatedText: '最后更新时间',
    // 开启本地搜索（左上角）
    search: {
      provider: 'local',
    },
    // 右上角Github链接
    socialLinks: [
      { icon: 'github', link: 'https://github.com/Goalonez/goalonez.github.io' }
    ],
    // 页脚
    footer: {
			copyright: 'Copyright © 2023-present Goalonez',
		}
  }
})

部署到Github Pages ​

  • 编辑.github/workflows/deploy.yml
  • 提交代码到main分支即自动触发部署到Github Pages
yaml
name: Deploy
on:
  workflow_dispatch: {}
  push:
    branches:
      - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v3
        with:
          node-version: 18.17.1
          cache: npm
      - run: npm ci
      - name: Build
        run: npm run docs:build
      - uses: actions/configure-pages@v2
      - uses: actions/upload-pages-artifact@v1
        with:
          path: docs/.vitepress/dist
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v1

其他配置 ​

引入评论（giscus） ​

giscus 基于 GitHub Discussions，不需要在前端保存 clientSecret，比旧的 OAuth 方案干净很多。

前置准备 ​

  • 仓库开启 Discussions
  • 安装 giscus GitHub App
  • 在仓库 Discussions 里创建一个分类，例如 Announcements
  • 打开 https://giscus.app/zh-CN 生成配置
  • 页面与 discussion 的映射建议选择 pathname，并开启严格匹配

编辑配置 ​

  • 编辑 ./docs/.vitepress/components/post-comments.vue
vue
<template>
  <div ref="container" class="comment-thread comment-thread--giscus"></div>
</template>

<script setup lang="ts">
import { onBeforeUnmount, onMounted, ref } from 'vue'

const container = ref<HTMLDivElement | null>(null)

function clearContainer() {
  if (container.value) {
    container.value.innerHTML = ''
  }
}

onMounted(() => {
  if (!container.value) {
    return
  }

  clearContainer()

  const script = document.createElement('script')
  script.src = 'https://giscus.app/client.js'
  script.async = true
  script.crossOrigin = 'anonymous'

  script.setAttribute('data-repo', '用户名/仓库名')
  script.setAttribute('data-repo-id', '从 giscus 页面复制')
  script.setAttribute('data-category', 'Announcements')
  script.setAttribute('data-category-id', '从 giscus 页面复制')
  script.setAttribute('data-mapping', 'pathname')
  script.setAttribute('data-strict', '1')
  script.setAttribute('data-reactions-enabled', '1')
  script.setAttribute('data-emit-metadata', '0')
  script.setAttribute('data-input-position', 'top')
  script.setAttribute('data-theme', 'preferred_color_scheme')
  script.setAttribute('data-lang', 'zh-CN')
  script.setAttribute('data-loading', 'lazy')

  container.value.appendChild(script)
})

onBeforeUnmount(clearContainer)
</script>
  • 编辑 ./docs/.vitepress/theme/index.ts
ts
import DefaultTheme from 'vitepress/theme'
import './custom.css'
// @ts-ignore
import PostComments from '../components/post-comments.vue'

export default {
  ...DefaultTheme,
  enhanceApp(ctx) {
    DefaultTheme.enhanceApp(ctx)
    ctx.app.component('PostComments', PostComments)
  },
}

使用 ​

在需要的 Markdown 里使用 <PostComments/> 开启评论

接入百度统计 ​

  • 去官网申请，获取接入代码

  • 编辑./docs/.vitepress/config.mts

ts
// head设置
  head: [
    // 添加百度统计代码
    ['script', {},
    `
      var _hmt = _hmt || [];
      (function() {
        var hm = document.createElement("script");
        hm.src = "https://hm.baidu.com/hm.js?自己申请";
        var s = document.getElementsByTagName("script")[0]; 
        s.parentNode.insertBefore(hm, s);
      })();
    `
    ]
  ],

开始书写 ​

  • 记得写完在./docs/.vitepress/config.mts里编辑themeConfig.sidebar。

Copyright © 2023-present Goalonez