博客使用指南-配置 - Shiina's Blog
Shiina's Blog

博客使用指南-配置

2023 年 2 月 10 日 - 00:00:00 发布
6.2K 字 21分钟
博客
博客
配置
本作品采用 CC BY-NC-SA 4.0 进行许可。
本文距离首次发布已经过去了 224 天，请注意文章的时效性！

博客配置

本部分会对 blog.config.ts 与 astro.config.mjs 必要的配置进行详细说明

astro.config.mjs

如果需要高度自定义可以参考：https://docs.astro.build/zh-cn/guides/configuring-astro/

此处我们对可能需要自定义的部分进行一个详细说明

site、base

参考：https://docs.astro.build/zh-cn/reference/configuration-reference/#site

这个选项是必要的，Astro 会以这个作为最终构建的规范链接

base 同理，当你的存在以二级路径为开头时需要设置

比如本仓库的配置：

当你部署页面是直接在 https://(yourname).github.io 时，就不需要填写 base 了

服务端渲染

假如你的博客要启用服务端渲染时，可以参考：https://docs.astro.build/zh-cn/guides/server-side-rendering/

博客内有一个 node 的 ssr 集成，将注释取消掉即可启用

export default defineConfig({
  // ...
  // 启用 node 作为服务端渲染载体
  output: 'server',
  adapter: node({
    mode: 'standalone'
  })
});

blog.config.ts

起步前检查

首先确认以下设置：

export default defineBlogConfig({
  WebsiteSettings: {
    site, // 设置成与 `astro.config.mjs` 相同的值
    base, // 设置成与 `astro.config.mjs` 相同的值，如果没有填写则可以省略
  },
})

这一步将会影响到博客所有静态资源的解析

当你在博客内写文章引入图片或资源时注意到以下这种警告：

11:45:14 [dev] Requests for items in your public folder must also include your base.

就说明你引入图片的时候没有带上配置中的 base 路径，这在写博客期间不受影响，但是上线后就会因为路径问题而无法解析图片！

如果以上步骤都完成后，你就可以开始对博客进行详细配置了！

配置博客时附带智能提示

注意：一定要通过 defineBlogConfig 对配置进行包裹，因为其内部有对配置进行预处理

PageDefaultSettings

这是对所有页面的通用设置，当页面单独的配置找不到对应项时会继承此处的配置项

声明部分：BasicPageConfig

PageDefaultSettings.header

title

当前网站标题，会用于 head 部分设置网站标题与大标题，一般不需要修改

hidden

隐藏 header，默认 false

keepBackgroundColor

保持背景颜色，即取消透明模式，默认 true

PageDefaultSettings.background

type

值：'photo' | 'fade' | 'purity'

背景类型，photo 为图片；fade 为渐变色，但只要是 background-image 可接受的参数即可；purity 为纯色

content

填入内容，根据 type 选项决定

  • photo，则填入图片路径，将图片放在 public 文件夹下，并将 public 作为根路径来查找图片，博客内部会自动补全 base 路径
  • fade 则填入 background-image 可接受参数，比如 linear-gradient()
  • purify 则填入颜色代码，如 #eee
jsPlugin (未启用)

将会在未来进行处理

filter

为背景提供一个毛玻璃效果，默认 false，详见：MDN filter

mask

为背景提供一个暗色效果，默认 false，详见：MDN background-color，颜色不透明度 0.3

useMaskOnDarkMode

暗色模式下启用背景面罩，用于降低背景亮度，默认 false

PageDefaultSettings.footer

hidden

隐藏 footer，默认 false

content

底部 footer内容，接受一个 string[]，默认内容是 Copyright © {当前年份}，会作为 HTML 插入到页尾

PageDefaultSettings.setMinHeight

给予页面中心部分最小高度，默认为 content

  • ‘content’ 会将内容控制在 header 与 footer 之间
  • ‘fill’ 将会以百分百宽高填充整个可见区域，并隐藏屏幕滚动条
  • ‘unset’ 将不对高度做任何处理，保留滚动条

WebsiteSettings

声明：BasicWebsiteConfig

WebsiteSettings.title

网站默认标题，会被放入 head 标签内的 title 部分，header 处也会使用

示例：首页 - Shiina's Blog

右侧的 Shiina’s Blog 就由该部分决定

WebsiteSettings.description

网站描述，会被放到 head 部分作为基本描述

WebsiteSettings.site

网站线上链接，请设置成 astro.config.mjs 下的 site 值

export default defineConfig({
   site: '', // 确保此处的值与 blog.config.ts 的值相同
})

WebsiteSettings.useIndex

为博客添加一个自定义主页，默认为 false

WebsiteSettings.base

网站二级路径，请设置成 astro.config.mjs 下的 base 值

export default defineConfig({
   base: '', // 确保此处的值与 blog.config.ts 的值相同
})

UserInfo

UserInfo.name

你的名字，用于资料卡名字展示

UserInfo.introduction

你的简介

UserInfo.avatar

头像路径，从public目录开始查找，如：/avatar/avatar2.jpg

你的网站外链，如 GitHub，会展示在资料卡

sitename

网站名字

网站跳转链接

class

字体图标 class 类名，可以前往 /public/fonts/social/demo_index.html 查看

你也可以前往 iconfont 官网挑选自己喜欢的图标并替代该目录下的文件

官网：https://www.iconfont.cn/

color

网站主题颜色

color.light、color.dark

分别为亮色和暗色的主题色

backgroundDefault

背景默认颜色，默认：#f2f5f8，夜间默认：#222

backgroundActiveDefault

选择框激活 / 鼠标悬浮时的背景颜色，默认：#ddd，夜间默认：#444

textDefault

文字默认颜色，默认：#000，夜间默认：#fff

tipsDefault

文字按钮激活 / 鼠标悬浮时默认颜色，默认：#3F5EFB，夜间默认：#919edf

SearchConfig

声明：BasicSearchConfig

前往 搜索文档 可以了解更多

SearchConfig.active

激活搜索功能，默认 true

SearchConfig.buildSearchIndex

是否构建搜索索引，默认为 true

构建搜索索引会被放到生产环境目录下，博客编写环境下会缓存到 .blog 文件夹中，可以删除

SearchConfig.searchIndexPath

输出搜索索引文件的路径，返回一个绝对路径来指定，返回内容为空时将不会输出文件

你需要向里面传入一个函数，并返回一个 string

一般不需要特别设置

SearchConfig.mode

值：'static' | 'server'

网页处理搜索结果的模式，默认为 static

SearchConfig.requestURL

请求的URL地址，默认是搜索索引被构建出来的位置，需要自己托管搜索索引文件时可以修改此项，内部使用 fetch api 实现文件获取

静态生成的站点一般无需修改，其默认指向静态文件路径；服务端渲染的博客如果将 mode 选项设置为 server 时需要设置为自己的接口

开发环境默认使用静态生成的索引文件

SearchConfig.staticSearchHandler

静态搜索处理函数，当搜索索引不是内置生成的文件时需要修改

pages

他是一个对象，其键值对为：页面位置 -> PageDefaultSettings

如 index -> index 专属的页面设置，其选项继承于 PageDefaultSettings

以下页面继承通用页面设置：

  • index 首页
  • tags 标签页
  • about 关于页
  • posts 文章页
  • search 搜索页

以下页面除了继承通用页面设置，还添加了一些自己的专属设置：

  • blog 博客页
  • collect 集合页
  • friends 好友页

pages.blog

PageArticleCount

博客页中每页展示的文章数量，默认展示 5 篇

pages.collect

PageArticleCount

集合页中每页展示的文章数量，默认10

pages.collect

FriendList

友链列表，其接受一个数组：

[
  {
    // 名字
    name: 'test',
    // 外链
    link: 'http://test.com',
    // 头像链接
    avatar: 'http://test.com/avatar.jpg',
    // 个人描述
    description: '114514'
  }
]

一些操作技巧

页面通用设置

模板中所有页面的背景都是渐变色，其在配置中这样处理：

export default defineBlogConfig({
  PageDefaultSettings: {
    // 背景
    background: {
      // 渐变色
      type: 'fade',
      // 填入 background-image 的内容
      content: `linear-gradient(to left, #12c2e9, #c471ed, #f64f59)`,
    },
    footer: {
      // 插入 footer 的 html
      content: [
        '<div>Powered by Astro & Vue</div>',
        '<a href="https://github.com/QingXia-Ela/Shiina-Astro-Blog/" target="_blank">Github Link</a>',
      ]
    }
  },
})

主页

这里的博客模板主页是一个全屏的主页，其配置如下：

export default defineBlogConfig({
  // 省略其他的配置
  pages: {
    index: {
      header: {
        // 隐藏头部导航栏
        hidden: true
      },
      background: {
        // 背景类型为图片
        type: "photo",
        content: "/indexBG.png",
        // 在暗色模式下降低图片亮度
        useMaskOnDarkMode: true
      },
      footer: {
        // 隐藏 footer
        hidden: true
      },
      // 将填充模式设置为全屏
      setMinHeight: "fill"
    }
  }
})

下一步？

个人信息
avatar
Shiinafan
文章
10
标签
8
归档
3
近期文章
博客使用指南-概览
2023-02-09
博客使用指南-配置
2023-02-09
博客使用指南-编写文章
2023-02-02
导航