feat: add html meta config.

jaywcjlove · Mar 25, 2024 · becee49 · becee49
1 parent 468c108
commit becee49
Show file tree

Hide file tree

Showing 7 changed files with 106 additions and 21 deletions.
diff --git a/.idoc/.filesStat.json b/.idoc/.filesStat.json
@@ -36,9 +36,9 @@
     "birthtime": "2022-04-10T14:24:24.106Z"
   },
   "docs/introduce/api/config.md": {
-    "atime": "2024-02-28T16:20:22.259Z",
-    "mtime": "2024-02-28T16:20:22.412Z",
-    "ctime": "2024-02-28T16:20:22.412Z",
+    "atime": "2024-03-25T14:34:10.609Z",
+    "mtime": "2024-03-25T14:34:10.516Z",
+    "ctime": "2024-03-25T14:34:10.516Z",
     "birthtime": "2022-04-20T04:23:01.592Z"
   },
   "docs/introduce/getting-started/installation.md": {

diff --git a/docs/assets/banner.png b/docs/assets/banner.png
diff --git a/docs/introduce/api/config.md b/docs/introduce/api/config.md
@@ -263,6 +263,52 @@ logo: ./logo.png
 favicon: ./logo.png
 ```
 
+### `meta`
+
+meta 标记描述 HTML 文档中的元数据，值支持模板变量
+
+```yml
+data: 
+  site_name: idoc # 向 meta 配置模板中添加模板数据
+meta:
+  - <meta name="author" content="Kenny Wong">
+  - <meta property="og:site_name" content="<%= data.site_name %>">
+  - <meta property="og:url" content="">
+  - <meta property="og:image" content="<%=homepage%>logo.png">
+  - <meta property="og:type" content="website">
+  - <meta property="og:title" content="<%= title %>">
+  - <meta property="og:description" content="<%= description%>">
+```
+
+头信息中生成 `HTML` 如下：
+
+```html
+<meta name="author" content="Kenny Wong">
+<meta property="og:site_name" content="idoc">
+<meta property="og:url" content="">
+<meta property="og:image" content="https://wangchujiang.com/idoc/logo.png">
+<meta property="og:type" content="website">
+<meta property="og:title" content="配置文件">
+<meta property="og:description" content="配置文件可以添加设置网站内容和主题等。">
+```
+
+配置 Twitter 卡片
+
+```yml
+data: 
+  site_name: idoc # 向 meta 配置模板中添加模板数据
+
+copyAssets: 
+  - '*/assets/*.(png|jpg)' # 存放在 `docs` 目录中匹配的资源
+meta:
+  - <meta property="twitter:image:src" content="<%=homepage%>assets/banner.png">
+  - <meta property="twitter:site" content="@jaywcjlove">
+  - <meta property="twitter:creator" content="jaywcjlove">
+  - <meta property="twitter:card" content="summary_large_image">
+  - <meta property="twitter:title" content="<%= title %>">
+  - <meta property="twitter:description" content="<%= description%>">
+```
+
 ### `element`
 
 模板中的某些节点 props 设置部位样式，例如设置 `wrapper` 定义网页最外层最大宽度：
@@ -307,7 +353,7 @@ cacheFileStat: true
 ```yml
 ## Copy Assets
 # -----------------------
-copyAssets: '**/assets/*.{mp3,ogm}'
+copyAssets: '**/assets/*.(mp3,ogm)'
 
 copyAssets: 
   - '**/assets/*.mp3'

diff --git a/idoc.yml b/idoc.yml
@@ -56,6 +56,35 @@ scope:
   - introduce
   - markdown
 
+## Template Data
+# -----------------------
+data: 
+  # 向 meta 配置模板中添加模板数据
+  site_name: idoc
+
+meta:
+  - <meta name="author" content="Kenny Wong">
+  - <meta property="og:site_name" content="<%= data.site_name %>">
+  - <meta property="og:url" content="<%=homepage%><%=RESOLVE_PATH%>">
+  - <meta property="og:image" content="<%=homepage%>logo.png">
+  - <meta property="og:type" content="website">
+  - <meta property="og:title" content="<%= title %> - idoc">
+  - <meta property="og:description" content="<%= description%>">
+  - <meta property="twitter:image:src" content="<%=homepage%>assets/banner.png">
+  - <meta property="twitter:site" content="@jaywcjlove">
+  - <meta property="twitter:creator" content="jaywcjlove">
+  - <meta property="twitter:card" content="summary_large_image">
+  - <meta property="twitter:title" content="<%= title %>">
+  - <meta property="twitter:description" content="<%= description%>">
+
+## Copy Assets
+# -----------------------
+# https://github.com/micromatch/micromatch
+# 
+# copyAssets: '**/assets/*.{mp3,ogm}'
+copyAssets: 
+  - '*/assets/*.(png|jpg)'
+
 ## Navigation Menu.
 # -----------------------
 menus:
@@ -68,11 +97,6 @@ menus:
   #   url: https://github.com/jaywcjlove/idoc
   #   target: __blank
 
-## Copy Assets
-# -----------------------
-# https://github.com/micromatch/micromatch
-# 
-# copyAssets: '**/assets/*.{mp3,ogm}'
 
 footer: |
   Released under the MIT License. Copyright © {{idocYear}} Kenny Wong<br />
@@ -83,10 +107,6 @@ footer: |
 # sideEffectFiles:
 #   - README.zh.md
 
-## Template Data
-# -----------------------
-data: 
-  good: test
 
 giscus: 
   src: https://giscus.app/client.js

diff --git a/src/markdown/markdown.ts b/src/markdown/markdown.ts
@@ -51,7 +51,10 @@ export interface PageConfig extends Omit<SiteGlobalConfig, 'menus'> {
 }
 
 export interface TemplateData extends Omit<Config, 'menus' | 'chapters'> {
+  /** 相对路径 `../../` */
   RELATIVE_PATH?: string;
+  /** 输出完整目录 `markdown/basic-syntax.html` */
+  RESOLVE_PATH?: string;
   markdown?: string;
   html?: string;
   menus?: MenuData[];
@@ -161,6 +164,7 @@ export async function createHTML(mdStr: string = '', fromPath: string, toPath: s
   data.version = config.data.version;
   data.idocVersion = config.data.idocVersion;
   data.RELATIVE_PATH = config.getRelativePath(toPath);
+  data.RESOLVE_PATH = path.relative(config.data.output, toPath).split(path.sep).join('/');
   const { global, ...other } = config.data;
   config.data.global = { ...other };
   data.chapters = formatChapters(config.data.chapters, toPath);
@@ -217,6 +221,7 @@ export async function createHTML(mdStr: string = '', fromPath: string, toPath: s
     }
   }
   const varData: ConfigData = {
+    meta: [],
     ...config.all,
     ...data,
     giscusScript: '',
@@ -225,6 +230,10 @@ export async function createHTML(mdStr: string = '', fromPath: string, toPath: s
     markdown: mdStr,
     html: mdHtml,
   };
+  if (varData.meta && Array.isArray(varData.meta)) {
+    varData.meta = varData.meta.map((item) => render(item || '', { ...varData }, {}));
+  }
+
   if (config.data.giscus) {
     const resultGiscus = Object.keys(config.data.giscus).map((key) => `${key}="${config.data.giscus[key]}"`);
     varData.giscusScript = `<script ${resultGiscus.join(' ')}></script><div class=".giscus"></div>`;

diff --git a/src/utils/conf.ts b/src/utils/conf.ts
@@ -24,20 +24,25 @@ export type LogoOrFavicon = {
 };
 
 export interface SiteGlobalConfig {
-  /** site name */
+  /** 网站名称 */
   site?: string;
+  /** 网站标题 */
   title?: string;
+  /** 搜索引擎能搜索到的关键词 */
   keywords?: string;
-  /** The url to the project homepage. */
-  homepage?: string;
+  /** meta 标记描述 HTML 文档中的元数据 */
+  meta?: string[];
+  /** 对网页的一个简单概述，默认获取当前 Markdown 页面第一段文本 **/
   description?: string;
+  /** 项目主页的 url **/
+  homepage?: string;
+  /** 导航上的logo */
+  logo?: LogoOrFavicon;
+  /** 网站 favicon 设置 */
+  favicon?: LogoOrFavicon;
   scope?: string[];
   scopePrivate?: string[];
   tocs?: Toc[] | boolean;
-  /** website logo icon */
-  logo?: LogoOrFavicon;
-  /** website favicon icon */
-  favicon?: LogoOrFavicon;
   editButton?: {
     label?: string;
     url?: string;
@@ -247,7 +252,9 @@ export class Conf {
           if (/.(md|markdown)$/.test(filestat.path)) {
             cacheFile.add(filestat);
           }
-          return /.(md|markdown)$/.test(filestat.path) || (copyAssets && micromatch.isMatch(filestat.path, copyAssets));
+          return (
+            /.(md|markdown)$/.test(filestat.path) || (copyAssets && micromatch.contains(filestat.path, copyAssets))
+          );
         },
       });
     }

diff --git a/themes/default/partial/header.ejs b/themes/default/partial/header.ejs
@@ -11,6 +11,9 @@
   <% if (keywords) { %>
   <meta name="keywords" content="<%= keywords %>">
   <% }%>
+  <% (meta || []).forEach((val) => { %>
+  <%- val %>
+  <% }) %>
   <link rel="stylesheet" type="text/css" href="<%= RELATIVE_PATH %>css/main.css?v=<%=idocVersion%>">
   <link rel="stylesheet" type="text/css" href="<%= RELATIVE_PATH %>css/tocbot.css?v=<%=idocVersion%>">
   <link rel="stylesheet" type="text/css" href="<%= RELATIVE_PATH %>css/media.css?v=<%=idocVersion%>">