1980's Maker

一个出生于80年代的程序员 -- 喜爱创[客]、美[食]、动[画]、怀[旧]的新手艺人的博客

VuePress Themes All Themes
vuepress-theme-reco
logo

vuepress-theme-onen

🎈A VuePress Theme for oneN

npm version npm download MIT license

简介

  • 一个偏文档风格的博客,灵感来自于 oneNote 笔记本
  • 博客主题追求简约文档风,抛去主流博客的元素,标签、归档等
  • 这看起来更像是对默认主题的一次改版,但也增加了主题的元素

预览

💨 Live Demo

Live

主题安装

oneN 主题基于 VuePress,首先你应该新建一个 VuePress 项目文件。详细请阅读 VuePress 官方文档 - 现有项目

在现有的 VuePress 项目文件新建如下目录结构:

目录结构

接着安装 oneN 主题:

yarn add -D vuepress-theme-onen
# or npm install -D vuepress-theme-onen 

主题配置

首先在配置文件 config.js 中添加如下字段:

// .vuepress/config.js
module.exports = {
  theme: 'onen'  // or 'vuepress-theme-onen'
}

首页

主题提供了一个首页 (Homepage) 的布局。想要使用它,需要在根级 README.mdYAML front matter 指定 home: true

以下是一个如何使用的例子:

# /README.md 
---
home: true
message: Welcome to my Blog
actionText: Start →
actionLink: /about
features:
title: 简洁至上
  details: 以 Markdown 为中心的项目结构,以 SPA 为导航的博客布局。
title: VuePress 驱动
  details: VuePress 为每个页面预渲染生成静态的 HTML。
title: oneN 主题
  details: 自搭使用 Vue 开发的主题 oneN。
---

注意,actionLink 字段读取的页面基于 VuePress 默认的页面路由方案。详细请阅读 VuePress 官方文档 - 目录结构

文件的相对路径 页面路由地址
/README.md /
/about/README.md /about/
/config.md /config.html

配置完的首页效果如下:

首页

侧边栏

侧边栏是 oneN 主题的核心组件,因为使用三级导航,配置内容稍许复杂,需要配置一二级的路径。通过 themeConfig.menu 字段进行配置:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    menu: [
      {
        text: '',
        link: '',
        children: [
          { text: '', link: '' },
          { text: '', link: '' },
          ...
        ]
      },
      ...
    ]
  }
}

可以看到 themeConfig.menu 数组中每个对象成员作为一级导航,应包含 textlinkchildren 字段,其中 children 字段又嵌套着二级导航。

侧边栏

如上图所示树形结构文件的侧边栏,配置内容应如下:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    menu: [
      {
        text: 'postA',
        link: '/post/postA',
        children: [
          { text: 'postA1', link: '/postA-1' },
          { text: 'postA2', link: '/postA-2' },
        ]
      },
      {
        text: 'postB',
        link: '/post/postB',
        children: [
          { text: 'postB1', link: '/postB-1' },
        ]
      },
    ]
  }
}

导航栏

导航栏包含头像、搜索框和选项链接。可以通过 themeConfig 的相关字段进行配置:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    avatar: '/avatar.jpg',  // 头像
    logo: '/logo.png',      // Logo
  }
}

注意,你应该在项目 .vuepress/public 目录下存放静态公共文件资源,以使 /avatar.jpg/logo.png 这样的路径能够被正确读取。

详细请阅读 VuePress 官方文档 - 静态资源

选项链接通过 themeConfig.navbar 字段配置,每个选项应该包括 typetitlehref 三个属性,分别表示图标、标题、链接路径。

// .vuepress/config.js
module.exports = {
  themeConfig: {
    navbar: [
      {
        type: 'home',
        title: 'Home',
        href: '/'
      },
      {
        type: 'user',
        title: 'About',
        href: '/about'
      },
      {
        type: 'github',
        title: 'GitHub',
        href: 'https://github.com/Veminem'
      }
    ],
  }
}

配置完的导航栏效果如下:

导航栏

音乐控件

[1.1.1] 版本中,我为博客添加了背景音乐功能。如果你想为博客添加背景音乐,只需要在配置文件 config.js 中添加 music 字段即可:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    music: // 链接
  }
}

音乐链接可以作为静态资源存放在 .vuepress/public 目录下,若如此做,对应的属性值应该为 ‘/musicFile.mp3’

(推荐) 你也可以通过引用音乐超链接,直接加载。这样做可以缓解博客资源加载压力,毕竟如果是将博客部署到 GitHub Pages 中的话,国内无法保证稳定访问。

背景音乐的状态通过头像控制,当鼠标移入头像组件时,背景音乐将暂停,移出则继续播放。若单击头像组件,背景音乐将暂停,反之继续播放。

页脚

页脚支持自定义名称和图标,只需要在配置文件 config.js 中添加如下字段:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    name: 'yourName',
    footer: {
      spin: true,      // 是否旋转: 默认 false
      type: 'Chrome',  // 图标样式: 默认 `Chrome`
      theme: 'filled'  // 图标主题: filled (实心, 默认), outline (描线)
    }
  }
}

其中图标主题有两个属性可选:filledoutline,分别是实心和描线。

配置完的页脚效果如下:

页脚

自定义图标

oneN 使用 ant-design-vue 图标库,因此你可以自定义图标样式,如上面提到的导航栏 navbar 和页脚 footer ,只需将其对应 title 属性值换成图标库中其他图标的 title 即可。

自定义颜色

如果要对主题默认预设的样式应用简单的颜色替换,或者定义一些颜色变量供以后使用,你可以创建一个 .vuepress/styles/palette.styl 文件。

你可以调整一些颜色变量:

// 默认值
// 文本
$textColor = #2c3e50      // 主要
$varColor = #d63200       // 变量
$accentColor = #42b983    // 活动
$warningColor = #ffe564   // 提示
$dangerColor = #ff0000    // 警告
 
// 背景
$bgColor = #ffffff        // 主要
$viceBgColor = #f3f5f7    // 辅助
$codeBgColor = #282c34    // 代码块
 
// 渐变色
$gradientColor = linear-gradient(to bottom right$accentColor, #2c3e50c7)

注意,你应该只在这个文件中写入颜色变量。因为 palette.styl 将在根的 stylus 配置文件的末尾引入,作为配置,它将被多个文件使用,所以一旦你在这里写了样式,你的样式就会被多次复制。

MarkDown 扩展

VuePress 提供了对 YAML front matter 开箱即用的支持,你可以在每个 .md 文件添加相应的字段。

更多关于在 VuePress 使用 MarkDown 写作的内容请阅读 VuePress 官方文档 - MarkDown 扩展

元信息

你应该为每个 .md 文件添加如下字段,以致 oneN 主题在侧边栏的三级导航中正确渲染出序号和标题。

---
index: 序号
title: 标题
---

一级标题

如果需要在内容页面中显示文档标题,你可以通过在文档中嵌入字段 {{ $frontmatter.title }}

一般的做法是在文档开头作为一级标题显示:

{{ $frontmatter.title }}

参考选项

如果你所创建的内容想要标记引用出处或转载来源,你可以在每个 .md 文件添加如下字段:

---
references:
author:
  title:
  link:
author:
  title:
  link:
- ...
---

对应几个引用出处就添加几个子字段。其中 link 可以省略,若省略标题将不会被渲染为超链接。