+简约风的 VitePress 博客主题 示例运行项目。 +
+ + + +## Usage + +先安装 `pnpm` + +```sh +npm i -g pnpm +``` + +安装依赖 + +```sh +pnpm install +``` + +开发启动 + +```sh +pnpm dev +``` + +构建 + +```sh +pnpm build +``` + +预览产物 + +```sh +pnpm serve +``` + +## Github Pages 部署 + +① Github Pages 开启 Git Actions 部署支持 + + + +② 复制文件 `.github/workflows/deploy.yml` 到自己的项目相同目录下 + +示例项目已包含，可以直接进行下一步 + +③ 修改 `docs/.vitepress/config.mts` 里的构建配置 + +**如果项目名已经为 name.github.io 域名，则不需要修改，保持默认值 `/` 即可** + +`base` 改为 `"/仓库名/"` 即可 + +```ts +// 省略无关代码 +const base = '/vitepress-blog-sugar-template/' +export default defineConfig({ + base, +}) +``` + +④ 推送 `main` 分支即可 + +需要进一步修改部署和构建配置，详见`deploy.yml` 文件。 diff --git a/docs/.vitepress/blog-theme.ts b/docs/.vitepress/blog-theme.ts new file mode 100644 index 0000000..8202714 --- /dev/null +++ b/docs/.vitepress/blog-theme.ts @@ -0,0 +1,105 @@ +// 主题独有配置 +import { getThemeConfig } from '@sugarat/theme/node' + +// 开启RSS支持（RSS配置） +// import type { Theme } from '@sugarat/theme' + +// const baseUrl = 'https://sugarat.top' +// const RSS: Theme.RSSOptions = { +// title: '粥里有勺糖', +// baseUrl, +// copyright: 'Copyright (c) 2018-present, 粥里有勺糖', +// description: '你的指尖,拥有改变世界的力量（大前端相关技术分享）', +// language: 'zh-cn', +// image: 'https://img.cdn.sugarat.top/mdImg/MTY3NDk5NTE2NzAzMA==674995167030', +// favicon: 'https://sugarat.top/favicon.ico', +// } + +// 所有配置项，详见文档: https://theme.sugarat.top/ +const blogTheme = getThemeConfig({ + // 开启RSS支持 + // RSS, + + // 搜索 + // 默认开启pagefind离线的全文搜索支持（如使用其它的可以设置为false） + // search: false, + + // 默认开启 markdown 图表支持（会增加一定的构建耗时） + // mermaid: false + + // 页脚 + footer: { + // message 字段支持配置为HTML内容，配置多条可以配置为数组 + // message: '下面 的内容和图标都是可以修改的噢（当然本条内容也是可以隐藏的）', + copyright: 'MIT License | 粥里有勺糖', + // icpRecord: { + // name: '蜀ICP备19011724号', + // link: 'https://beian.miit.gov.cn/' + // }, + // securityRecord: { + // name: '公网安备xxxxx', + // link: 'https://www.beian.gov.cn/portal/index.do' + // }, + }, + + // 主题色修改 + themeColor: 'el-blue', + + // 文章默认作者 + author: '粥里有勺糖', + + // 友链 + friend: [ + { + nickname: '粥里有勺糖', + des: '你的指尖用于改变世界的力量', + avatar: + 'https://img.cdn.sugarat.top/mdImg/MTY3NDk5NTE2NzAzMA==674995167030', + url: 'https://sugarat.top', + }, + { + nickname: 'Vitepress', + des: 'Vite & Vue Powered Static Site Generator', + avatar: + 'https://vitepress.dev/vitepress-logo-large.webp', + url: 'https://vitepress.dev/', + }, + ], + + // 公告 + popover: { + title: '公告', + body: [ + { type: 'text', content: '👇公众号👇---👇 微信 👇' }, + { + type: 'image', + src: 'https://img.cdn.sugarat.top/mdImg/MTYxNTAxODc2NTIxMA==615018765210~fmt.webp' + }, + { + type: 'text', + content: '欢迎大家加群&私信交流' + }, + { + type: 'text', + content: '文章首/文尾有群二维码', + style: 'padding-top:0' + }, + { + type: 'button', + content: '作者博客', + link: 'https://sugarat.top' + }, + { + type: 'button', + content: '加群交流', + props: { + type: 'success' + }, + link: 'https://theme.sugarat.top/group.html', + } + ], + duration: 0 + }, +}) + +export { blogTheme } diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts new file mode 100644 index 0000000..e02266d --- /dev/null +++ b/docs/.vitepress/config.mts @@ -0,0 +1,58 @@ +import { defineConfig } from 'vitepress' + +// 导入主题的配置 +import { blogTheme } from './blog-theme' + +// 如果使用 GitHub/Gitee Pages 等公共平台部署 +// 通常需要修改 base 路径，通常为“/仓库名/” +// 如果项目名已经为 name.github.io 域名，则不需要修改！ +// const base = process.env.GITHUB_ACTIONS === 'true' +// ? '/vitepress-blog-sugar-template/' +// : '/' + +// Vitepress 默认配置 +// 详见文档：https://vitepress.dev/reference/site-config +export default defineConfig({ + // 继承博客主题(@sugarat/theme) + extends: blogTheme, + // base, + lang: 'zh-cn', + title: '@sugarat/theme', + description: '粥里有勺糖的博客主题，基于 vitepress 实现', + lastUpdated: true, + // 详见：https://vitepress.dev/zh/reference/site-config#head + head: [ + // 配置网站的图标（显示在浏览器的 tab 上） + // ['link', { rel: 'icon', href: `${base}favicon.ico` }], // 修改了 base 这里也需要同步修改 + ['link', { rel: 'icon', href: '/favicon.ico' }] + ], + themeConfig: { + // 展示 2,3 级标题在目录中 + outline: { + level: [2, 3], + label: '目录' + }, + // 默认文案修改 + returnToTopLabel: '回到顶部', + sidebarMenuLabel: '相关文章', + lastUpdatedText: '上次更新于', + + // 设置logo + logo: '/logo.png', + // editLink: { + // pattern: + // 'https://github.com/ATQQ/sugar-blog/tree/master/packages/blogpress/:path', + // text: '去 GitHub 上编辑内容' + // }, + nav: [ + { text: '首页', link: '/' }, + { text: '关于作者', link: 'https://sugarat.top/aboutme.html' } + ], + socialLinks: [ + { + icon: 'github', + link: 'https://github.com/ATQQ/sugar-blog/tree/master/packages/theme' + } + ] + } +}) diff --git a/docs/.vitepress/theme/assets/bg.webp b/docs/.vitepress/theme/assets/bg.webp new file mode 100644 index 0000000..cc2c4d0 Binary files /dev/null and b/docs/.vitepress/theme/assets/bg.webp differ diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts new file mode 100644 index 0000000..c7daf46 --- /dev/null +++ b/docs/.vitepress/theme/index.ts @@ -0,0 +1,9 @@ +import BlogTheme from '@sugarat/theme' + +// 自定义样式重载 +// import './style.scss' + +// 自定义主题色 +// import './user-theme.css' + +export default BlogTheme diff --git a/docs/.vitepress/theme/style.scss b/docs/.vitepress/theme/style.scss new file mode 100644 index 0000000..8872fe9 --- /dev/null +++ b/docs/.vitepress/theme/style.scss @@ -0,0 +1,13 @@ +.VPHome { + // 定义遮罩样式 + background: radial-gradient(ellipse, + rgba(var(--bg-gradient-home), 1) 0%, + rgba(var(--bg-gradient-home), 0) 150%); + + // 自定义首页背景图 + &::before { + // 图片来源：https://zhuanlan.zhihu.com/p/54060187 + background-image: url(./assets/bg.webp); + background-size: cover; + } +} \ No newline at end of file diff --git a/docs/.vitepress/theme/user-theme.css b/docs/.vitepress/theme/user-theme.css new file mode 100644 index 0000000..fa4c5a9 --- /dev/null +++ b/docs/.vitepress/theme/user-theme.css @@ -0,0 +1,26 @@ +/* 所有变量：https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css */ +/* 自定义主题色示例，如下 */ + +/* 浅色模式使用的变量 */ +html[theme] { + --vp-c-user-1:red; + --vp-c-user-2:blue; + --vp-c-user-3:green; + --vp-c-user-soft:rgba(255,0,0,.5); +} + +/* 深色模式使用的变量 */ +html[theme].dark { + --vp-c-user-1:yellow; + --vp-c-user-2:purple; + --vp-c-user-3:orange; + --vp-c-user-soft:rgba(255,255,0,.5); +} + +/* 覆盖默认变量 */ +html[theme],html[theme].dark { + --vp-c-brand-1: var(--vp-c-user-1); + --vp-c-brand-2: var(--vp-c-user-2); + --vp-c-brand-3: var(--vp-c-user-3); + --vp-c-brand-soft: var(--vp-c-user-soft); +} \ No newline at end of file diff --git a/docs/about.md b/docs/about.md new file mode 100644 index 0000000..e06520a --- /dev/null +++ b/docs/about.md @@ -0,0 +1,67 @@ +--- +sticky: 1 +--- +# 关于主题 + +简约风的 Vitepress 博客主题，基于 [vitepress](https://vitepress.dev/) 的自定义主题实现 + + + +更多细节见 https://theme.sugarat.top + +## 已支持功能 +介绍一下主要的，非所有 + +* 博客首页 +* 文章列表 +* 精选文章 +* 友链 +* 标签分类 +* 图片预览 +* 搜索（基于[pagefind](https://github.com/cloudcannon/pagefind)支持离线全文搜索） +* [giscus](https://giscus.app/zh-CN)驱动的评论系统 +* 推荐文章（类似文章目录） +* 阅读时间计算 +* 全局的提示弹窗 (由 el-alert 驱动) +* 全局的公告弹窗，支持设置图片，文字，按钮 +* 作品聚合页（为个人作品提供一个展示） +* tabs（[vitepress-plugin-tabs](https://vitepress-plugins.sapphi.red/tabs/)） +* 流程图（[vitepress-plugin-mermaid](https://github.com/emersonbottero/vitepress-plugin-mermaid#readme)） +* RSS +* 主题色统一 +* 更多可定制的主题样式 + +## 规划中功能 +* Valine 评论系统 +* 文章合集（类似于聚合一个内容专题） +* 文章时间线页面支持 +* 背景图自动更换 +* 首屏铺满slogan，参考reco + +## 参考项目 +或多或少借鉴&使用了如下的一下开源项目，博客，网站的能力或者UI样式 + +* [reco](https://vuepress-theme-reco.recoluan.com/) +* [掘金](https://juejin.cn/) +* [surmon](https://surmon.me/) +* [@vue/theme](https://github.com/vuejs/theme) +* [vitest](https://vitest.dev/) +* [element-plus](https://element-plus.gitee.io/zh-CN/) +* [charles7c.github.io](https://github.com/Charles7c/charles7c.github.io) +* [vitepress-blog-zaun](https://github.com/clark-cui/vitepress-blog-zaun) +* [vuejs/blog](https://github.com/vuejs/blog/tree/main) +* [列表无限滚动轮播效果](https://code.juejin.cn/pen/7145007064350195748) + +## 主题相关资源 +* 主题地址：https://theme.sugarat.top/ +* 主题包：[@sugarat/theme](https://www.npmjs.com/package/@sugarat/theme) +* 项目地址：https://github.com/ATQQ/sugar-blog/tree/master/packages/theme +* 作者博客地址：https://sugarat.top + + +## 最后 +如果你有建议的 功能&想法 欢迎 私信&评论区 交流 + +如果你觉得主题不错，欢迎分享与使用，可以在评论区留下你的网站地址 + +笔者后续会单独开个板块展示大家优秀的博客，感谢大家的支持 \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..415bd87 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,16 @@ +--- +layout: home +# 首页部分元素定制 +blog: + name: '@sugarat/theme' + motto: 简约风的 Vitepress 博客主题 + inspiring: + - 基于 Vitepress 定制的主题🎨 + - 千万不要因为走得太久，而忘记了我们为什么出发 + - 人生就像一场修行，你不可能一开始就修成正果 + - 无论多么沉重的负担，也不要忘记微笑；无论多么漫长的路程，也不要忘记坚持 + - 生活的真谛不在繁华，而在于淡泊 + # 设置 inspiringTimeout 可以实现自动切换 + inspiringTimeout: 3000 + pageSize: 6 +--- \ No newline at end of file diff --git a/docs/public/.spa b/docs/public/.spa new file mode 100644 index 0000000..e69de29 diff --git a/docs/public/favicon.ico b/docs/public/favicon.ico new file mode 100644 index 0000000..ce2037b Binary files /dev/null and b/docs/public/favicon.ico differ diff --git a/docs/public/logo.png b/docs/public/logo.png new file mode 100644 index 0000000..ce2037b Binary files /dev/null and b/docs/public/logo.png differ diff --git a/docs/public/robots.txt b/docs/public/robots.txt new file mode 100644 index 0000000..c2a49f4 --- /dev/null +++ b/docs/public/robots.txt @@ -0,0 +1,2 @@ +User-agent: * +Allow: / diff --git a/docs/sop/component.md b/docs/sop/component.md new file mode 100644 index 0000000..3e469ba --- /dev/null +++ b/docs/sop/component.md @@ -0,0 +1,411 @@ +--- +description: 默认支持流程图，tabs面板，待办列表，作品页面 +--- + +# 内置第三方插件能力 + +部分内置组件（插件），来源 [vitepress.yiov.top](https://vitepress.yiov.top/plugin.html) 推荐 + +## oml2d - 看板娘集成 +* Type：[oml2dOptions](https://oml2d.hacxy.cn/api/interfaces/Options.html) + +为网站提供一个 Live2D 看板组件。 + +:::tip 一点说明 +通过内置 [oh-my-live2d](https://oml2d.hacxy.cn) 实现, 可以通过 `oml2d` 选项配置。 + +通过这个能力可以快速加入并定制属于自己的看板娘, 开启只需要为其传递一个 [配置选项](https://oml2d.hacxy.cn/options/Options.html) 即可 +::: + +以下是一个简单的使用示例，当模型加载成功时它将出现在您网站的左下角。 + +```ts +const blogTheme = getThemeConfig({ + oml2d: { + mobileDisplay: true, + models: [ + { + path: 'https://registry.npmmirror.com/oml2d-models/latest/files/models/Senko_Normals/senko.model3.json' + } + ] + } +}) +``` +效果图如下 + + + +之后您还可以前往[配置选项](https://oml2d.hacxy.cn/options/Options.html)查阅更多自定义内容 + +:::tip 版本说明 +由于时间原因，主题内置的版本不一定都是最新的，可以通过 `resolutions` 配置指定要使用的版本。 + +下面是使用示例，配置在 `package.json` 中，其它依赖覆盖版本也是这样操作。 +```json +{ + "resolutions": { + "oh-my-live2d": "^0.17.0" + } +} +``` +::: + +## task-checkbox +* Type: `boolean | TaskCheckbox` + +支持渲染 markdown 任务列表，内置 [markdown-it-task-checkbox](https://github.com/linsir/markdown-it-task-checkbox) 插件提供支持 + +* [ ] 🥔 TODO +* [ ] 真不戳 +* [x] 内置任务列表 + +语法如下 +```md +* [ ] 🥔 TODO +* [ ] 真不戳 +* [x] 内置任务列表 +``` + +默认开启，你可以进一步配置 + +:::code-group +```ts [① 关闭] +const blogTheme = getThemeConfig({ + taskCheckbox: false +}) +``` +```ts [② 进一步配置] +const blogTheme = getThemeConfig({ + taskCheckbox: { + // refer https://github.com/linsir/markdown-it-task-checkbox for options + } +}) +``` +```ts [③ type] +interface TaskCheckbox { + disabled?: boolean + divWrap?: boolean + divClass?: string + idPrefix?: string + ulClass?: string + liClass?: string +} +``` +::: + +## timeline +* Type: `boolean` +* default: `true` + +提供 markdown 时间线语法，在 vitepress 中使用 markdown 渲染时间线（时间轴）样式。 + +:::tip 一点说明 +内置 [vitepress-markdown-timeline](https://github.com/HanochMa/vitepress-markdown-timeline) 实现 +::: + +效果如下 + +::: timeline 2023-05-24 +- **do some thing1** +- do some thing2 +::: + +::: timeline 2023-05-23 +do some thing3 +do some thing4 +::: + +语法如下 +```md +::: timeline 2023-05-24 +- **do some thing1** +- do some thing2 +::: + +::: timeline 2023-05-23 +do some thing3 +do some thing4 +::: +``` + +:::code-group +```ts [关闭] +const blogTheme = getThemeConfig({ + timeline: false +}) +``` +::: +## tabs +* Type: `boolean` + +支持局部的`tabs`面板，**默认开启** + +:::details 我之前手动安装配置了怎么办？ +① package.json 中移除 vitepress-plugin-tabs 依赖 + +② .vitepress/theme/index.ts 中移除注册的组件`enhanceAppWithTabs` + +③ （可选）`getThemeConfig` 中移除配置项`tabs` +::: +:::tip 一点说明 +基于 [vitepress-plugin-tabs@0.2.0](https://www.npmjs.com/package/vitepress-plugin-tabs) 内置实现 +::: + +效果如下 + +:::=tabs +::tab1 +一些内容 + +一些内容 + +一些内容 + +::tab2 +一些内容 。。。 +::: + +简单的使用方式如下（效果如上面的示例） + +```md +:::=tabs +::tab1 +一些内容 + +一些内容 + +一些内容 + +::tab2 +一些内容 。。。 +::: +``` + +共享状态的使用方式如下 + +```md +:::=tabs=ab +::a +a content + +::b +b content +::: + +:::=tabs=ab +::a +a content 2 + +::b +b content 2 +::: +``` + + +:::=tabs=ab +::a +a content + +::b +b content +::: + +:::=tabs=ab +::a +a content 2 + +::b +b content 2 +::: + +不需要也可以关闭 + +```ts +// .vitepress/blog-theme.ts +const blogTheme = getThemeConfig({ + tabs: false +}) +``` + +## Mermaid - 图表 +* Type: `boolean`|`object` + +>通过解析类 Markdown 的文本语法来实现图表的创建和动态修改。 + +:::tip 一点说明 +基于 [vitepress-plugin-mermaid](https://github.com/emersonbottero/vitepress-plugin-mermaid) 实现 +::: + +简单语法如下，详细流程图语法见 [Mermaid 中文文档](https://github.com/mermaid-js/mermaid/blob/develop/README.zh-CN.md) + ++```mermaid +flowchart TD + Start --> Stop +``` ++ + +效果如下 + +```mermaid +flowchart TD + Start --> Stop +``` + +**默认关闭**，可以通过设置 `mermaid: true` 开启，或进行进一步配置。 + +:::code-group +```ts [① 开启] +const blogTheme = getThemeConfig({ + mermaid: true +}) +``` +```ts [② 进一步配置] +const blogTheme = getThemeConfig({ + mermaid: { + // refer https://mermaid.js.org/config/setup/modules/mermaidAPI.html#mermaidapi-configuration-defaults for options + } +}) +``` +::: + +下面看一下官方其它案例 + +**时序图** +```mermaid +sequenceDiagram +Alice->>John: Hello John, how are you? +loop Healthcheck + John->>John: Fight against hypochondria +end +Note right of John: Rational thoughts! +John-->>Alice: Great! +John->>Bob: How about you? +Bob-->>John: Jolly good! +``` + +**甘特图** +```mermaid +gantt + section Section + Completed :done, des1, 2014-01-06,2014-01-08 + Active :active, des2, 2014-01-07, 3d + Parallel 1 : des3, after des1, 1d + Parallel 2 : des4, after des1, 1d + Parallel 3 : des5, after des3, 1d + Parallel 4 : des6, after des4, 1d +``` + + +## UserWorksPage +* Type: `UserWorks` + +用于作品列表展示 + +效果如下，详见 [个人作品展示](https://theme.sugarat.top/work.html) + + + +新建一个`works.md`文件，放入以下内容 + +```md +--- +layout: page +title: 个人作品展示 +sidebar: false +outline: [2,3] +sticky: 1 +--- +
+ npm create @sugarat/theme@latest
+
+
+ bun create @sugarat/theme
+
+