✨ feat: 允许导入文档的时候只导入 API 定义部分

README.md

@@ -12,6 +12,9 @@ The embedded block feature of SiYuan supports querying using JavaScript syntax.
 > You can download it and click the "Help Document" button in the top-left menu. The plugin will automatically create a help document within SiYuan.
 >
 > ​![image](assets/image-20241211194348-sfzl8pc.png)​
+>
+> The help documentation will include the latest API type definitions for the plugin.  
+> If you are only interested in reviewing the interface content and not the other parts of the help documentation, you can set "User documentation only imports type references" to `true`​ in the plugin settings.
 
 ## 0. Quick Overview of Features
 
@@ -488,6 +491,12 @@ interface IWrappedBlock extends Block {
     /** Block's SiYuan reference format text */
     asref: string;
 
+    /** Blocks's ial list, as object
+     * @example
+     * let icon = block.asial['icon'];
+    */
+    asial: Record<string, string>;
+
     /**
      * Returns a rendered SiYuan attribute
      * @param attr - Attribute name
@@ -515,12 +524,13 @@ interface IWrappedBlock extends Block {
 All properties can be grouped into several categories:
 
 1. Rendering as links or references, i.e., `aslink`​, `asref`​ (however, since rendering as a reference does not actually create a relationship in the ref table, most of the time using link is sufficient, and ref is not very meaningful).
-2. Timestamp-related: Additional properties are extended for updated, created, etc., to facilitate direct display of block timestamps.
-3. ​`attr`​ function:
+2. ​`asial`​: The ial list of the block itself is a string field. Using this method, the ial can be parsed into an object of type `{ [key: string]: string}`​
+3. Timestamp-related: Additional properties are extended for updated, created, etc., to facilitate direct display of block timestamps.
+4. ​`attr`​ function:
 
     * Takes a block and block attribute and the return will be rendered as suitable markdown text (as mentioned in the table section earlier).
     * You can also pass a custom renderer and return a markdown text. If no return or return null, the default rendering scheme is used.
-4. ​`custom-xxx`​ properties: Directly access the block's custom attributes, e.g., `block['custom-b']`​, which accesses the `custom-b`​ attribute of the corresponding block.
+5. ​`custom-xxx`​ properties: Directly access the block's custom attributes, e.g., `block['custom-b']`​, which accesses the `custom-b`​ attribute of the corresponding block.
 
 You can try the following code, and get to know there differences.
 
@@ -2087,7 +2097,9 @@ The plugin provides a button in the block menu to directly perform the above con
 
 ​![image](assets/image-20241209001506-1j38x18.png)​
 
-## Complete API
+## Reference
+
+​`<!-- REFERENCE-START -->`​
 
 > Note: Since the interface file will change with development, the README itself does not include the interface code but some placeholders.
 >
@@ -2105,18 +2117,20 @@ The plugin provides a button in the block menu to directly perform the above con
 {{Query}}
 ```
 
-### DataView
+### IWrapBlock & IWrapList
 
 ```ts
-{{DataView}}
+{{Proxy}}
 ```
 
-### IWrapBlock & IWrapList
+### DataView
 
 ```ts
-{{Proxy}}
+{{DataView}}
 ```
 
+​`<!-- REFERENCE-END -->`​
+
 ## Example Demonstrations
 
 Some example codes are provided. Some cases have actually appeared in the above documentation.

README_zh_CN.md

@@ -8,6 +8,9 @@
 > 你可以在下载下来之后，点击左上角菜单按钮中的“帮助文档”按钮，插件会自动在思源内创建一个帮助文档。
 >
 > ​![image](assets/image-20241211194348-sfzl8pc.png)​
+>
+> 帮助文档中会包含插件最新的 API 类型定义接口。  
+> 如果你只想要查阅接口内容而对帮助文档的其他部分不感兴趣，可以在插件中将“用户文档只导入类型参考”设置为 `true`​。
 
 ## 0. 功能速览
 
@@ -484,6 +487,12 @@ interface IWrappedBlock extends Block {
     /** Block's SiYuan reference format text */
     asref: string;
 
+    /** Blocks's ial list, as object
+     * @example
+     * let icon = block.asial['icon'];
+    */
+    asial: Record<string, string>;
+
     /**
      * Returns a rendered SiYuan attribute
      * @param attr - Attribute name
@@ -511,12 +520,13 @@ interface IWrappedBlock extends Block {
 以上所有的属性可以分为几组来理解：
 
 1. 渲染为链接或者引用，也就是 `aslink`​, `asref`​ 这些（不过实际上由于渲染成为引用并不会真的在 ref 表中创建关联关系，所以大部分时候使用 link 就可以了，ref 的意义不大）
-2. 时间戳相关：额外为 updated，created 这些拓展了一些属性，方便直接用来展示块的时间戳
-3. ​`attr`​ 函数：
+2. ​`asial`​：块的 ial 列表本身为一个字符串字段，使用这个方法，可以把 ial 解析为一个 `{ [key: string]: string}`​ 的对象
+3. 时间戳相关：额外为 updated，created 这些拓展了一些属性，方便直接用来展示块的时间戳
+4. ​`attr`​ 函数：
 
     * 传入块和块的属性，会讲块的属性渲染为合适的 markdown 文本（就像我们前面在 table 小节提到的那样）
     * 你也可以自己传入一个自定义的 renderer，然后返回一段 markdown 文本，如果没有返回或者返回 null，则回退到默认的渲染方案
-4. ​`custom-xxx`​ 属性，可以直接访问块的自定义属性，例如 `block['custom-b']`​，会访问对应块的 `custom-b`​ 属性。
+5. ​`custom-xxx`​ 属性，可以直接访问块的自定义属性，例如 `block['custom-b']`​，会访问对应块的 `custom-b`​ 属性。
 
 你可以尝试一下下面的代码，会有直观的区别:
 
@@ -2087,7 +2097,9 @@ dv.render();
 
 ​![image](assets/image-20241209001506-1j38x18.png)​
 
-## 完整 API
+## Reference
+
+​`<!-- REFERENCE-START -->`​
 
 > 注：由于接口文件会随着开发而变动，所以 README 本体中并不包含 interface 代码，而是放了一些 placeholder 。
 >
@@ -2105,18 +2117,20 @@ dv.render();
 {{Query}}
 ```
 
-### DataView
+### IWrapBlock & IWrapList
 
 ```ts
-{{DataView}}
+{{Proxy}}
 ```
 
-### IWrapBlock & IWrapList
+### DataView
 
 ```ts
-{{Proxy}}
+{{DataView}}
 ```
 
+​`<!-- REFERENCE-END -->`​
+
 ## 案例演示
 
 提供了一些 example 代码。部分案例在上面的文档中其实已经出现过了。

public/i18n/en_US.yaml

@@ -33,9 +33,14 @@ src_setting_indexts:
     is "code -w {{filepath}}" which represents opening with VSCode, where {{filepath}}
     will be replaced with the actual code file at runtime
   open_local_editor: ✒️ Open Local Editor
+  plugin_import_help_doc: The plugin allows the help documentation to be imported
+    into SiYuan. By default, the complete README document and TypeScript Reference
+    will be imported. If this option is enabled, only the Reference part will be imported
+    during the import and no other parts.
   reload: Reload
   table_default_columns: 🔑 Default columns displayed in table view
   user_custom_view: User custom view
+  user_doc_import_type_ref: User documentation only imports type references
   user_self_written_view: User self-written View component, stored under '/data/public/custom-query-view.js'
 src_userhelp_examplests:
   backlinks_table: Display backlinks of the current document in a table format
@@ -95,6 +100,8 @@ src_userhelp_indexts:
     the following two lines
 src_userhelp_sydocts:
   create_user_doc: 'Create user documentation:'
+  plugin_setting_doc: '> 🖊️ Due to your settings in the plugin, this help document only
+    contains the type definitions of the API.'
   plugin_update_doc: Detected plugin version update, updating documentation, please
     wait...
 user_help:

public/i18n/zh_CN.yaml

@@ -25,9 +25,12 @@ src_setting_indexts:
   local_command_desc: 本地用于打开代码编辑器的命令, 默认为 "code -w {{filepath}}" 代表使用 VSCode 打开, 其中
     {{filepath}} 在运行时会被替换为真实的代码文件
   open_local_editor: ✒️ 打开本地编辑器
+  plugin_import_help_doc: 插件允许将帮助文档导入到思源笔记中，默认情况下会导入完整的 README 文档以及 Tyepscript Reference；如果开启了这个选项，那么在导入的时候将只导入
+    Reference 部分而不会导入其余部分
   reload: 重新加载
   table_default_columns: 🔑 表格视图默认显示列
   user_custom_view: 用户自定义视图
+  user_doc_import_type_ref: 用户文档只导入类型参考
   user_self_written_view: 用户自行编写的 View 组件, 存放在 '/data/public/custom-query-view.js'
     下
 src_userhelp_examplests:
@@ -64,6 +67,7 @@ src_userhelp_indexts:
   useview2: 如果要使用 DataView 请注释上面的 return, 并取消下方两行注释
 src_userhelp_sydocts:
   create_user_doc: '创建用户文档:'
+  plugin_setting_doc: '> 🖊️ 由于你在插件中的设置，此帮助文档只包含了 API 的类型定义。'
   plugin_update_doc: 检查到插件版本已更新，正在更新文档，请稍等...
 user_help:
   ahead_hint: |

public/types.d.ts

@@ -2,7 +2,7 @@
  * @name sy-query-view
  * @author frostime
  * @version 1.0.2
- * @updated 2024-12-20T13:21:00.445Z
+ * @updated 2024-12-20T14:03:43.400Z
  */
 
 declare module 'siyuan' {

src/setting/index.ts

@@ -3,7 +3,7 @@
  * @Author       : frostime
  * @Date         : 2024-12-01 16:25:57
  * @FilePath     : /src/setting/index.ts
- * @LastEditTime : 2024-12-13 12:48:22
+ * @LastEditTime : 2024-12-20 21:58:58
  * @Description  : 
  */
 
@@ -17,7 +17,8 @@ import { loadUserCustomView } from "@/core/custom-view";
 let defaultSetting = {
     codeEditor: 'code -w {{filepath}}',
     defaultTableColumns: ['type', 'content', 'hpath', 'box'].join(','),
-    echartsRenderer: 'svg'
+    echartsRenderer: 'svg',
+    onlyImportDtsInUserDoc: true
 };
 
 let settingUtils: SettingUtils;
@@ -58,6 +59,13 @@ export const load = async (plugin: Plugin) => {
         key: 'apiDoc',
         value: '',
     });
+    settingUtils.addItem({
+        type: 'checkbox',
+        title: i18n.src_setting_indexts.user_doc_import_type_ref,
+        description: i18n.src_setting_indexts.plugin_import_help_doc,
+        key: 'onlyImportDtsInUserDoc',
+        value: defaultSetting.onlyImportDtsInUserDoc,
+    });
     settingUtils.addItem({
         type: 'textinput',
         title: i18n.src_setting_indexts.open_local_editor,

src/types/i18n.d.ts

@@ -30,9 +30,11 @@ interface I18n {
         import_success: string;
         local_command_desc: string;
         open_local_editor: string;
+        plugin_import_help_doc: string;
         reload: string;
         table_default_columns: string;
         user_custom_view: string;
+        user_doc_import_type_ref: string;
         user_self_written_view: string;
     };
     src_userhelp_examplests: {
@@ -68,6 +70,7 @@ interface I18n {
     };
     src_userhelp_sydocts: {
         create_user_doc: string;
+        plugin_setting_doc: string;
         plugin_update_doc: string;
     };
     user_help: {

src/user-help/sy-doc.ts

@@ -3,6 +3,7 @@ import type QueryViewPlugin from "@/index";
 import { openBlock } from "@/utils";
 import { confirm, showMessage } from "siyuan";
 import { i18n } from "@/index";
+import { setting } from "@/setting";
 
 
 const CUSTOM_USER_README_ATTR = 'custom-query-view-user-readme';
@@ -38,6 +39,22 @@ const createReadmeText = async (plugin: QueryViewPlugin) => {
     const response = await fetch(`/plugins/sy-query-view/${fname}`);
     let readme = await response.text();
 
+    if (setting.onlyImportDtsInUserDoc) {
+        // 找到 ​`<!-- REFERENCE-START -->`​ 和 ​`<!-- REFERENCE-END -->`​ 之间的内容
+        const start = '`<!-- REFERENCE-START -->`';
+        const end = '`<!-- REFERENCE-END -->`';
+        const startIndex = readme.indexOf(start);
+        const endIndex = readme.indexOf(end);
+
+        const hint = i18n.src_userhelp_sydocts.plugin_setting_doc;
+
+        if (startIndex !== -1 && endIndex !== -1) {
+            readme = readme.substring(startIndex + start.length, endIndex).trim();
+        }
+
+        readme = hint + '\n\n' + readme;
+    }
+
     const AheadHint = i18n.user_help.ahead_hint.trim();
     let ahead = AheadHint.replace('{{version}}', plugin.version);
     readme = ahead + '\n' + OutlineCode + '\n\n' + readme;

vite.config.ts

@@ -267,8 +267,8 @@ function replaceMDImgUrl(dirname: string) {
                 }
 
                 const prefix_github = 'https://github.com/frostime/sy-query-view/raw/main';
-                // const prefix_cdn = 'https://cdn.jsdelivr.net/gh/frostime/sy-query-view@main';
-                const prefix_cdn = 'https://ghp.ci/https://github.com/frostime/sy-query-view/raw/main';
+                const prefix_cdn = 'https://cdn.jsdelivr.net/gh/frostime/sy-query-view@main';
+                // const prefix_cdn = 'https://ghgo.xyz/https://github.com/frostime/sy-query-view/raw/main';
 
                 let readmePath = resolve(dirname, 'README.md');
                 await replace(readmePath, prefix_github);