使用说明
项目说明
项目结构
|-- assets => 自定义资源文件夹,存放几乎不更改的资源
|-- images => 图片
|-- katex => 数学公式插件 KaTeX 的样式
|-- components
|-- cipher => cipher 路由的内容(没有SEO)
|-- comm => 普通组件
|-- example => example 路由的内容(没有SEO)
|-- icon => 图标组件
|-- layout => 布局组件
|-- mdx => MDX 组件
|-- pages
|-- category
|-- [category].jsx => 分站主页
|-- [category]
|-- [menu].jsx => 分站分类
|-- cipher
|-- index.jsx => cipher页
|-- example
|-- [slug].jsx => 示例页
|-- media
|-- index.jsx => 音视频页
|-- post
|-- [slug].jsx => 文章页
|-- posts => 所有的文章
|-- menu.js => 文章目录
|-- other.js => 其他目录
|-- public => 静态资源,由 Next 内置,不可修改名称
|-- images => 图像资源
|-- bigFiles => 大资源, 不在 git 中记录
|-- posts => 文章的资源
|-- scripts => node 脚本工具
|-- styles => 样式
|-- article.css => 文章样式
|-- globals.css => 全局样式
|-- utils
|-- config.js => 全局配置
|-- example.js => 示例通用函数
|-- media.js => media 页的数据
|-- post.js => 文章通用函数
|-- utils.js => 其它通用函数
说明:
- 增加文档分类,在
posts/menu.js
中配置分类信息,分类最多支持三级。 - 设置分类权限,在
posts/menu.js
中目标分类下配置auth
字段,使用middleware
校验权限。 - 文档排序,在
posts/menu.js
中目标分类下配置sort
字段,- 默认:按时间升序。
desc
:按时间降序排列。
- 新增
md
文档,所有的文档便于统一管理,都在posts
目录中。- 在
posts/menu.js
文件中配置了的目录中的md
文件将被自动注入路由。 - 特殊情况下,不属于
posts/menu.js
分类中的文档,如果要加入路由,在posts/other.js
中配置。
- 在
注意:
- 要加入路由的
md
文件,名称不能包含-
字符,这个字符在路由解析中被作为关键字使用了。 - 项目中的大文件没有被
Git
记录,项目迁移的时候不要忽略这些文件,否则将造成资源丢失。
项目插件
插件列表:
- next-mdx-remote:加载解析 mdx。
- gray-matter:同步解析 mdx 的 formatter,解析速度比 next-mdx-remote 块,只需要解析 formatter 时使用这个。
- rehype-urls:修改 mdx 文档中的本地资源链接。
- remark-gfm:支持 mdx 文档的表格语法。
- @mapbox/rehype-prism:语法高亮。
- remark-math:支持数学公式,选择 rehype-katex 插件对公式进行解析渲染。
- rehype-katex:数学公式解析,是 KaTeX 的封装,样式需要在 KaTeX 中下载,现在是下载后放在本地的
assets/katex
中,并在全局引用。 - rehype-slug-custom-id:给
<h1>...<h6>
标签增加id
(这里是将这些标签作为导航锚点)。 - @jsdevtools/rehype-toc:将
<h1>...<h6>
标签解析为TOC,用作导航。
插件升级:
需要注意有些包要配合升级(如 next
14 以上的版本要 node
18 以上),可以隔几年升级一次,频繁升级,处理出现的问题太麻烦。
项目升级
项目安装包升级后去 这个页面 测试是否正常,这个页面内容如果正常,说明升级成功。
维护日志
- 2024-07-01 注入攻击(已解决):最近一段时间网站偶尔会跳出广告,发现是运行了外部注入的脚本导致的,做了如下处理:
- 在
next.config.js
中配置了Content-Security-Policy
,禁止加载不明来源的资源。 - 在
next.config.js
中配置了X-Frame-Options
,禁止嵌入非同源站点的<iframe>
。
- 在
脚本工具
npm run media
:收集public/media
的内容,生成utils/media.js
文件,供媒体页面使用。npm run post
:批量创建md
文档。
全局样式
gl-emoji
:emoji 字体,使用 Google Fonts 的 Noto Color Emoji 字体,没有全局引入的原因是它会覆盖掉一些字符的默认字体。gl-no-select
:禁止选中。gl-help
:鼠标指针是?
。gl-text-ellipsis
:文字超出隐藏。gl-min-scrollbar
:窄滚动条。
MDX 文档
-
如果是目录,以
拼音
或者英文
命名;如果是独立的md文件
以年月日_名称
命名;其他,以年月日时分
命名。 -
FrontMatter
配置title: '文档的名称, 作为生成的 html 的 title' description: '文档的描述, 作为生成的 html 的 description' keywords: '文档的关键字, 作为生成的 html 的 keywords' weather: '自定义的参数, 本来用于配置页面的背景, 还没有实现' layout: '自定义的参数, 用于文章的特殊样式, literature 文章类型布局, 段前空两格'
-
数学公式
-
行内公式:公式内容前各加一个
$$
符(如:$$公式内容$$
)。注意,
Typora
编辑器需要设置才能正确显示,但不影响网站的解析(在偏好设置
、Markdown
、Markdown 扩展语法
中 勾选内联公式
选项)。 -
块级公式:两个
$$
分别处于第一行和最后一行。在
Typora
编辑器中,打两个$$
符,按回车,会自动生成块级数学公式。 -
块级公式换行:
$$ 第一行公式 \\\\ 第二行公式 $$
-
注释符号:①②③④⑤⑥⑦⑧⑨⑩⑪⑫⑬⑭⑮⑯⑰⑱⑲⑳㉑㉒㉓㉔㉕㉖㉗㉘㉙㉚㉛㉜㉝㉞㉟㊱㊲㊳㊴㊵㊶㊷㊸㊹㊺㊻㊼㊽㊾㊿
-
字体:使用 Google Fonts,目前仅引入了 Noto Color Emoji ,类名是
gl-emoji
(没有全局引入的原因是它会覆盖掉一些默认字符的字体),其他使用系统默认。
MDX 组件
MdxClick
:被监听的点击事件,类型:<MdxClick type='audio' json='音频地址][字幕地址'>描述文本</MdxClick>
:音频播放。<MdxClick type='video' json='视频地址'>描述文本</MdxClick>
:视频播放。
<MdxDetails title='名称'>被折叠的内容</MdxDetails>
:详细信息折叠组件。