Skip to content

Latest commit

 

History

History
256 lines (203 loc) · 11.8 KB

USAGE.md

File metadata and controls

256 lines (203 loc) · 11.8 KB
Raw

使用

当前文档描述了针对 blogit 的配置内容：

初始化

可通过 blogit init path/to/blog/dir 进行初始经，会在 path/to/blog/dir 生成完整的项目文件。

conf.yaml

项目的配置文件，大部分项目的全局修改均由该文件配置。

名称 类型 描述
title string 网站标题
subtitle string 网站副标题
titleSeparator string 标题分隔符，在 html>head>title 标签中，非首页通过该符号在标题后加网站标题
url string 网站根目录，比如 https://example.com/blog
language string 网站的默认语言，在文章中若没有专门配置，则采用此值作为文章的默认语言，比如 cmn-Hans
uptime string 网站的上线时间，rfc3999 格式
icon Icon favicon 图标定义
author Author 网站的默主作者
license Link 网站的默认版权信息
theme string 网站采用的主题，该名称必须是 themes/ 下的文件夹名称。
keywords string 首页的 html>head>meta.keywords 标签的值
description string 首页的 html>head>meta.description 标签的值
menus []Link 菜单栏内容
toc number 当标题数量大于此值时，才会生成 TOC 数据，默认值为 0。
index Index 索引页相关的设置
archive Archive 存档页的相关定义，可以为空，表示不需要该页面。
rss RSS RSS 的相关定义，为空表示不需要。
atom RSS atom 的相关定义，为空表示不需要。
Sitemap Sitemap sitemap 的相关定义，为空表示不需要。
Robots []Agent robots.txt 文件的配置，如果为空表示不需要由项目管理 robots.txt 文件。
Profile Profile 管理 README.md 的生成，github 中仅与账号同名的项目才会在 profile 中显示。

Icon

名称 类型 描述
url string 图标地址，比如 /favicon.svg
type string 图标的类型，比如 image/svg+xml
sizes string 图标的大小，比如 256x256

Author

名称 类型 描述
name string 作者名称
url string 作者网站
email string 作者的邮箱
avatar string 头像

Link

名称 类型 描述
text string 链接的文本
url string 链接指向的地址

RSS

名称 类型 描述
title string 标题，部分模板可能会引用到。
size number 生成的文章数量

Index

名称 类型 描述
title string 标题，可以带 %d 占位符，表示当前页的页码数字。
size number 生成的文章数量

Sitemap

名称 类型 描述
title string 标题，部分模板可能会引用到。
enableTag boolean 是否将标签页也放入 sitemap
postPriority number 对应文章的 priority 值
postChangefreq string 对应文章的 changefreq 值
priority number 其它页面的 priority 值
changefreq string 其它页面的 changefreq 值

Agent

名称 类型 描述
agent []string 指定可用的爬虫，比如 ['*']
disallow []string 禁止抓取的目录
allow []string 允许的目录

Profile

名称 类型 描述
title string 标题，该值会自动加上 ### 字符
footer string 页脚部分，自动加上 ##### 字符
size string 生成该数量的文章列表

该配置生成的内容大致如下：

### title

[post title](post link)
[post title](post link)
[post title](post link)

##### footer

标签

blogit 不支持文章分类，也没有一般博客的页面和文章的区别，只能通过标签对文章进行归类统计。

通过 tags.yaml 可以定义标签的相关信息：

tags.yaml

名称 类型 描述
title string 标签页的标题
keywords string 标签页的 html>head>meta.keywords 中的值，如果没有，则提取所有标签值作为该值
description string 标签页的 html>head>meta.description 元素的值。
order string 排序，可是 asc 和 desc
orderType string 排序方式，可以是 size 表示按关联文章数量进行排序，或是为空，按添加顺序。
tags []Tag 标签列表

Tag

名称 类型 描述
title string 标签名称
slug string 标签的唯一 ID，一般会显示在 URL 中
content string 标签的描述，可以是 markdown 格式。

主题

主题包含在 themes/ 目录下，每个目录为一个主题，每个主题包含 theme.yaml 文件， 该文件配置了与主题相关的一些内容。

theme.yaml

名称 类型 描述
url string 主题关联的地址
description string 详细说明
authors []Author 主题作者
screenshots []string 截图
templates []string 文章详情页的模板名称，在文章配置项指定的模板必须上此列表中的某个值。
highlights Highlight 语法高亮的相关配置
sitemap string 为 sitemap.xml 指定一个 xsl 转换文件
atom string 为 atom.xml 指定一个 xsl 转换文件
rss string 为 rss.xml 指定一个 xsl 转换文件

Highlight

名称 类型 描述
name string 名称，该值可通过 blogit styles 获取
media string 对应的媒体查询值，比如 print、(prefers-color-scheme: dark) 等。

模板

每个主题下的 layout 目录之下可以存放模板。模板采用 go 的 html/template 语法。传递的变量如下：

名称 类型 描述
Type string 当前页面类型，同时也是页面采用的模板名称。除了文章详情之外，其它值都是固定的。
Site Site 站点的数据，不同页面该数据都是相同的。
Title string 当前页的标题，出现在 html>head>title 元素中，会加上网站名称作为后缀。
Permalink string 当前页的唯一链接
Keywords string 当前页的 html>head>meta.keywords 元素中数据。
Description string 当前页的 html>head>meta.description 元素中数据。
Description string 当前页的 html>head>meta.description 元素中数据。
Prev Link 前一页的链接
Next Link 后一页的链接
Author Author 当前页内容的作者
License Link 当前页的版权信息
Language string 当前页所采用的语言
JSONLD string 当前页的 JSON-LD 数据
Tag Tag 如果当前页是 tag，那么表示该标签的数据，否则为空值。
Post Post 如果当前页是 post，那么表示该页的数据，否则为空值。
Index Index 如果当前页是 index，那么表示该页的数据，否则为空值。
Archives Archives 存档信息

Type 可以有以下值：

  • tags: 标签列表
  • index: 首页
  • tag: 标签页
  • archive: 存档页
  • post: 文章详情页，文章情况页也可以是其它任意非空值。
Site
名称 类型 描述
AppName string 生成该模板的程序名称
AppVersion string 生成该模板的程序版本
Theme Theme 主题信息
Highlights []StyleLink 代码高这所需要的 CSS 文件
Title string 网站名称
Subtitle string 网站副标题
URL string 网站根地址
Icon Icon 网站图标
Author Author 网站的默认作者
RSS Link RSS 链接
Atom Link Atom 链接
Sitemap Link Sitemap 链接
Menus []Link 全局菜单
Tags Tags 标签列表
Uptime date 上线时间
Created date 最后次创建文章的时间
Modified date 最后次修改文章的时间
Builded date 编译项目的时间
Index
名称 类型 描述
Title string 页标题
Permalink string 链接
Posts []Post 文章列表
Index number 当前页的页码
Path string 当前页的文件地址
StyleLink
名称 类型 描述
URL string CSS 指向的地址
Media string 对应的媒体查询值，比如 print、(prefers-color-scheme: dark) 等。

添加文章

命令 blogit post path/to/file 可以在当前目录下添加 posts/path/to/file.md 文件，并在文件中添加必要的字段， 每个文件中可用的字段如下：

名称 类型 描述
title string 文章标题
created string 创建时间，rfc3339 格式
modified string 修改时间，rfc3339 格式
summary string 摘要
tags []string 关联的标签
state string 状态，可以是以下值：top 表示文章被置顶；last 表示文章会被放置在最后；draft 表示这是一篇草稿；空值 按默认的方式进行处理。
image string 封面图片
jsonld string 自定义 json-ld 数据，为空则会自动生成。
authors []Author 作者，如果为空，则采用 conf.yaml 中对应的值。
license string 文章的版权信息，如果为空则采用 conf.yaml 中对应的值。
template string 文章的模板，如果为空，则采用默认值 post。
keywords string html>head>meta.keywords 的值，如果为空，自动提取 tags 作为默认值。
language string 页面的语言，如果为空，则采用 conf.yaml 中对应的值。