使用说明

项目说明

使用 Next.js 构建,支持 MDX 语法。

项目结构
|-- 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             => 其它通用函数

说明

  1. 增加文档分类,在 posts/menu.js 中配置分类信息,分类最多支持三级。
  2. 设置分类权限,在 posts/menu.js 中目标分类下配置 auth 字段,使用 middleware 校验权限。
  3. 文档排序,在 posts/menu.js 中目标分类下配置 sort 字段,
    • 默认:按时间升序。
    • desc :按时间降序排列。
  4. 新增 md 文档,所有的文档便于统一管理,都在 posts 目录中。
    • posts/menu.js 文件中配置了的目录中的 md 文件将被自动注入路由。
    • 特殊情况下,不属于 posts/menu.js 分类中的文档,如果要加入路由,在 posts/other.js 中配置。

注意

  1. 要加入路由的 md 文件,名称不能包含 - 字符,这个字符在路由解析中被作为关键字使用了。
  2. 项目中的大文件没有被 Git 记录,项目迁移的时候不要忽略这些文件,否则将造成资源丢失。
项目插件

插件列表

  1. next-mdx-remote:加载解析 mdx。
  2. gray-matter:同步解析 mdx 的 formatter,解析速度比 next-mdx-remote 块,只需要解析 formatter 时使用这个。
  3. rehype-urls:修改 mdx 文档中的本地资源链接。
  4. remark-gfm:支持 mdx 文档的表格语法。
  5. @mapbox/rehype-prism:语法高亮。
  6. remark-math:支持数学公式,选择 rehype-katex 插件对公式进行解析渲染。
  7. rehype-katex:数学公式解析,是 KaTeX 的封装,样式需要在 KaTeX 中下载,现在是下载后放在本地的 assets/katex 中,并在全局引用。
  8. rehype-slug-custom-id:给 <h1>...<h6> 标签增加 id(这里是将这些标签作为导航锚点)。
  9. @jsdevtools/rehype-toc:将 <h1>...<h6> 标签解析为TOC,用作导航。

插件升级:

需要注意有些包要配合升级(如 next 14 以上的版本要 node 18 以上),可以隔几年升级一次,频繁升级,处理出现的问题太麻烦。

项目升级

项目安装包升级后去 这个页面 测试是否正常,这个页面内容如果正常,说明升级成功。

维护日志
  1. 2024-07-01 注入攻击(已解决):最近一段时间网站偶尔会跳出广告,发现是运行了外部注入的脚本导致的,做了如下处理:
    • next.config.js 中配置了 Content-Security-Policy ,禁止加载不明来源的资源。
    • next.config.js 中配置了 X-Frame-Options ,禁止嵌入非同源站点的 <iframe>
脚本工具
  1. npm run media:收集 public/media 的内容,生成 utils/media.js 文件,供媒体页面使用。
  2. npm run post:批量创建 md 文档。

全局样式

  1. gl-emoji:emoji 字体,使用 Google FontsNoto Color Emoji 字体,没有全局引入的原因是它会覆盖掉一些字符的默认字体。
  2. gl-no-select:禁止选中。
  3. gl-help:鼠标指针是 ?
  4. gl-text-ellipsis:文字超出隐藏。
  5. gl-min-scrollbar:窄滚动条。

MDX 文档

  1. 如果是目录,以 拼音 或者 英文 命名;如果是独立的 md文件年月日_名称 命名;其他,以 年月日时分 命名。

  2. FrontMatter 配置

    title: '文档的名称, 作为生成的 html 的 title'
    description: '文档的描述, 作为生成的 html 的 description'
    keywords: '文档的关键字, 作为生成的 html 的 keywords'
    weather: '自定义的参数, 本来用于配置页面的背景, 还没有实现'
    layout: '自定义的参数, 用于文章的特殊样式, literature 文章类型布局, 段前空两格'
    
  3. 数学公式

    • 数学公式支持的语法

    • 行内公式:公式内容前各加一个 $$ 符(如:$$公式内容$$)。

      注意,Typora 编辑器需要设置才能正确显示,但不影响网站的解析(在 偏好设置MarkdownMarkdown 扩展语法 中 勾选 内联公式 选项)。

    • 块级公式:两个 $$ 分别处于第一行和最后一行。

      Typora 编辑器中,打两个 $$ 符,按回车,会自动生成块级数学公式。

    • 块级公式换行:

      $$
      第一行公式
      \\\\
      第二行公式
      $$
      
  4. 注释符号:①②③④⑤⑥⑦⑧⑨⑩⑪⑫⑬⑭⑮⑯⑰⑱⑲⑳㉑㉒㉓㉔㉕㉖㉗㉘㉙㉚㉛㉜㉝㉞㉟㊱㊲㊳㊴㊵㊶㊷㊸㊹㊺㊻㊼㊽㊾㊿

  5. 字体:使用 Google Fonts,目前仅引入了 Noto Color Emoji ,类名是 gl-emoji(没有全局引入的原因是它会覆盖掉一些默认字符的字体),其他使用系统默认。


MDX 组件

  1. MdxClick:被监听的点击事件,类型:
    • <MdxClick type='audio' json='音频地址][字幕地址'>描述文本</MdxClick>:音频播放。
    • <MdxClick type='video' json='视频地址'>描述文本</MdxClick>:视频播放。
  2. <MdxDetails title='名称'>被折叠的内容</MdxDetails>:详细信息折叠组件。