博客写作技术说明

2/9/2022

# 博客的目的

上一个博客因为各种原因,废弃了,一开始是因为写得多了之后太过于庞杂,没有后台管理导致内容和组织越来越混乱,一边写一边思考解决方法,最后发现了Obsidian简直是理想中的模式,遂直接重开,用Obsidian写笔记,寻找最大兼容的语法,直接放进博客渲染。
所以这次就不赶潮流了,Obsidian直接固定下来,博客只要稳定就固定下来,感觉这个模式已经成熟了,不出意外不去更新,这个页面是关于博客如何组织的说明,上一篇是关于Obsidian的事项

# 博客的写作

安装helloworld什么的我就不多说了,文档上很齐全,照着来就是了。

# metadata信息

^18f313 文件的开头会有metadata信息,如下代码块

---
title: first page  
date: 2022-02-11 15:31:09 
subSidebar: false
isShowComments: false
search: false
publish: false 
sticky: 1
pageClass: custom-series-page-class
keys:
 - '123456'
categories:  
- 系列1
tags: 
- 说明
---
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
  • title 必填不要重名
  • date 必填用@可以直接生成
  • next和prev,就是上下页,如果已经被纳入侧边栏系列文章就可以不用配置,自己会生成
  • subSidebar: false 默认生成侧边栏,可手动关闭
  • isShowComments: false/true 默认使用评论,可单独页面开关
  • search: false 全文检索插件的是否被检索,除了社科类的,都直接不写
  • publish: false/true 是否发布
  • sticky 接受数字,降序排列(大在前)置顶
  • pageClass:自定义本页css,我用来写非系列连续文章next和prev已经失效了
    • custom-guide-page-class 去掉顶栏作者和标题
    • custom-series-page-class 去掉侧边栏以形成连续非系列文章
  • keys 可多个密码,必须字符串,默认加密只是将页定位到实际内容上方,加密本身是没有什么作用的
  • categories 可以用中文,类似于系列,只要新出现的都会自动创建,可以一篇文章多个category
  • tags 标签可以用中文,vuepress只会解析metadata里的标签,可以用Tag Wrangler插件管理

# 写作注意事项

库写作时的注意事项^255951

  1. vuepress-theme-reco 中,请摒弃一级标题,使用 front-matter 生成标题以及其他文章信息,正文从二级标题开始,二三级标题生成左侧子目录 二级标题在前面会有一个小竖条定位
  2. 所有的文件夹不要用中文,但是tag和categories可以
  3. 使用Admonition时的对应关系,事先约定规则,写一个python脚本,转换Admonition语法为Markdown-it-container,想的是用的regex替换
    1. vuepress使用markdown-it-container,支持 tip danger warning theorem details,类型 标题
    2. Admonition支持note,abstract,info,tip,success,question,warning,failure,danger,bug,example,quote
    3. example默认collapse是open,用detail,不加前缀,其他的collapse默认关闭直接删除。
    4. 把所有的(static/ 替换为(./static/ 省得自己配置了
    5. 其他的把title拿上去,前面加前缀,例子ad-note 你好= 📝Note 你好
    • tip: note =📝Note,abstract=📘Abstract,info=📄Info,tip=📌Tip,success=🎉Success,绿色
    • warning: question=❓Question,warning=⚠️Warning,橙色
    • danger: failure=❌Failure,danger=⚡️Danger,bug=🐛BUG,红色
    • theorem: quote,details: example 这俩直接加标题白色
  4. <!-- more --> 之上的是文章简介,其实可以搭配:::使用但是Obsidian里面不渲染,有点突兀 自己写脚本解决了
  5. 标签和分类
    • 成系列的文章放一个categories
    • categories分类
      • 课程,书和电影,语言分类,工具安利,随笔,代码之外,剩下的按技术方向
    • 非系列连续文章也需要配置
    • tag尽量精简而全
    • 阅读顺序从上往下
  6. 已经全配置好了,展示组件也写好了

Warning

Card给的id一定要和ThreePageJson里面的id匹配,最好还能和课程名字匹配
图床做了baseUrl在/.vuepress/public/js/pgmanor-self换地址要记得修改
sidebarConfig的路径是博客里的路径不要混了,希望自动生成就[],不然自己配置顺序
7. Course自动生成侧边栏是匹配的是regex ^第xx章 文件名以第多少章开头才会排序预留2000。
去除侧边栏连续非系列文章看下面

# 自己修改文件

# 脚本规格说明书

脚本规格说明书:

拼装
笔记路径->博客路径:
/others/安利 -> /docs/guids/安利
/others/随笔 -> /docs/guids/随笔

/blogs -> /blogs

/Courses -> /Courses

/others/FilmBookReview -> /blogs/FilmBookReview
/others/Personalwiki -> /blogs/Personalwiki
/others/社科读书笔记 -> /blogs/社科读书笔记

res/Site-map.svg -> /docs/README/static/Site-map.svg
res/introduction/Courses -> /docs/guids/Courses
res/introduction/FilmBookReview -> /docs/guids/FilmBookReview
res/introduction/SocialScienceReadingNotes -> /docs/guids/SocialScienceReadingNotes

执行语法兼容转化:
/docs/guids/随笔
/docs/guids/安利
/blogs

生成sidebar请查看sidebarConfig

# 魔改

太多了,写得有点乱
本来想启用和文档一样的博客,发现怎么也搞不出来,要问的东西太多了,而且我的文档好像也和别人的不太一样,干脆就自己写了个按钮,直接强制定位到那里了,在首页readme.md
参照这两篇 (opens new window)顺便修改了一下CSS,就完事了。 [^2]

  • 首页添加了按钮
    • 直接写了个插件解决的[^3],放在了包里
  • 写了个展示卡,用来展示连续的课程
  • 插件,层级目录独立出js来
    • 魔改了一个自动生成最多二级大侧边栏的js,可以直接配置了
  • index.styl和palette.styl样式文件修改css
    • 二级标题添加anchor前标
    • CSS调整侧边栏字号
    • 自定义介绍页面的CSS去掉标题栏[^4]
    • 自定义css去掉侧边栏,把内容左对齐,以便非系列连续文章使用
  • 写个脚本兼容语法

# 配置

把插件,导航,侧边栏,友链分离出去.[^1] 侧边栏
注意开启侧边栏 (opens new window):subSidebar: 'auto'
"sidebar"现在只能通过配置config来展示多篇文章集合,集合文件夹下README.md是首页,首页配置时为""
大标题栏在config->"themeConfig"->"sidebar"里面配置,配置之后会按照数组直接有前后页。

     "/docs/guids/": [  
       "",  
       "recommend",   
     ],
    "/blogs/category2/2017/":[  
        '',
        {  
            title: 'Grou1',  
            collapsable: true,  
            sidebarDepth: 4,  
            children: [  
                '01',  
                '02',  
            ]  
        },
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

大标题栏的子标题类似文档 (opens new window)这样
侧边栏可以分组,children里面是可以进行一个娃的套的,例子已经注释了起来,sidebarDepth默认设置2就行
套娃也不能按文件夹套,无法设置路径,只能在一个文件夹里手动分

# 插件

插件都是文档上给的,插件一定要["plugins",{attribute:aaa}]这样引入,否则报错

# 评论

上次评论用的Vaillne,又更新服务了没法用了还得绑定手机号,直接换Vssue用github
参考页面 | Vssue (opens new window)很简单照着文档 (opens new window)把东西填上就好了,他的评论是储在指定的repo的issue里,所以最好直接扔github,repo只需要填repo名字就行。

# 复制按钮

vuepress-plugin-nuggets-style-copy
代码块添加复制按钮,直接引入用就行了,就俩参数不用配置,代码直接去文件里看

# 看板娘

@vuepress-reco/vuepress-plugin-kan-ban-niang
有些模型是不能使用了,找找能用的主题,theme设置为单字符串就可以
不是普通的看板娘插件,必须是theme-reco的看板娘插件

# TOC目录插件

@vuepress/plugin-toc@next 提供一个目录 (table-of-contents, TOC) 组件。
默认是toc代码块用(四个点的)渲染,用脚本直接更改为双括号[[toc]] 就可以在vuepress中渲染

# 中文md转拼音路径

npm install -D vuepress-plugin-permalink-pinyin vuepress不支持当文件名含有中文时,对应页面无法跳转,可通过如下插件解决这个问题,这个插件会将中文路径转换为拼音路径

# 禁用静态文件转码

cnpm i markdown-it-disable-url-encode [^5] 图片和附件含有中文时会被编码导致读不出来,配置之后就可以了

# 全文检索插件[^6]

cnpm i vuepress-plugin-fulltext-search
默认情况下,搜索关键字的结果是下划线的,没有高亮。修改文件.vuepress/styles/index.styl

// 搜索结果样式
.suggestions {
  max-height: 80vh; // 搜索结果框高度自适应
  overflow-y: scroll;
}
.suggestions .highlight{
  color: #646cff
  font-weight: bold
}
1
2
3
4
5
6
7
8
9

全文检索

plugins: [
      // 支持中文文件名
      [
        "permalink-pinyin",
        {
          lowercase: true, // Converted into lowercase, default: true
          separator: "-", // Separator of the slug, default: '-'
        },
      ],
  ]
......
//config.js
"markdown": {  
  "lineNumbers": true,  
  extendMarkdown: md => {  
    md.use(require("markdown-it-disable-url-encode"));  
  }  
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 错误

猜测是编译时目录层级过多,导致错误[^7],但build的网页可以正常使用
找到原因了,是vue-router的和侧边栏原因

  • package.json里面vue-router版本指定^3.5.3,渲染不出错[^8]
    • TypeError: vue.defineComponent is not a function

[^1]: vuepress-theme-reco主题优化 | 小弋の阅览室 (opens new window)
[^2]: vuepress-theme-reco主题魔改 | 小弋の生活馆 (opens new window)
[^3]: 从零实现一个 VuePress 插件 - SegmentFault 思否 (opens new window)
[^4]: 默认主题配置 | VuePress (opens new window)
[^5]: Vuepress 图片资源中文路径问题 - SegmentFault 思否 (opens new window)
[^6]: Vuepress配置全文搜索插件fulltext-sarch | 二丫讲梵 (opens new window)
[^7]: vuepress编译时报错TypeError _normalized undefined的解决 | 二丫讲梵 (opens new window)
[^8]: vue vue-router 版本不兼容导致 (TypeError: vue.defineComponent is not a function) - 简书 (opens new window)

Last Updated: 4/29/2022, 3:46:50 PM