Update readme and docs (#49)

* Update readme and docs * Add example image on dataview feature * Update README-ZH.md * Update dataview example image and desccription * Update image url
Acylation · Dec 25, 2023 · 7fdddb8 · 7fdddb8
1 parent 7d291e0
commit 7fdddb8
Show file tree

Hide file tree

Showing 5 changed files with 103 additions and 55 deletions.
diff --git a/README-ZH.md b/README-ZH.md
@@ -6,37 +6,56 @@
 
 **Chem** 是一个旨在提升化学相关笔记记录体验的 [Obsidian.md](https://obsidian.md/) 插件。目前，本插件能够将您笔记中的SMILES字符串渲染为化学结构式。（基于 [Smiles Drawer](https://github.com/reymond-group/smilesDrawer)）
 
-> **Note**  
-> 最新插件版本: 0.2.1  
-> 文档版本: 0.2.1  
+> [!Note]
+> 最新插件版本: 0.3.0  
+> 文档版本: 0.3.0  
 
-## 功能介绍和使用说明
+## 功能介绍
 
 ### 渲染 SMILES 字符串为化学结构式
 
 如图所示，本插件能够识别语言被标记为 `smiles` 的代码块，并将其中的 SMILES 字符串逐行转化为化学结构式。得益于 SMILES 的纯文本特性，数据能够持久保存，该功能将得到稳定支持；此外，由于 SMILES 是一个通用标准，即使本插件换用了其他化学信息学工具包，SMILES 字符串仍能够被正确解析和渲染
 
-![Image](https://github.com/Acylation/obsidian-chem/assets/73122375/a9f9a440-dc66-4689-ab1a-1ef265242778)
+![渲染 SMILES 字符串](https://github.com/Acylation/obsidian-chem/assets/73122375/a9f9a440-dc66-4689-ab1a-1ef265242778)
+
+### 设置结构图像大小和样式主题
 
 您可以在插件设置页面调整化学结构式的尺寸比例，或指定图像大小，并分别调整浅色模式/深色模式下对应的结构式颜色主题。插件设置发生更改，或浅色/深色模式切换后，图像样式会自动更新
 
-![Image](https://github.com/Acylation/obsidian-chem/assets/73122375/fde8d0a4-2c9c-458c-b357-78952480b755)
+![设置大小和样式主题](https://github.com/Acylation/obsidian-chem/assets/73122375/fde8d0a4-2c9c-458c-b357-78952480b755)
+
+### 复制、导出图像
+
+复制功能位于结构图像的右键菜单。图像均以 `png` 格式导出，并能直接粘贴到笔记中，作为文件保存入附件文件夹，也可以以图片形式粘贴到微信、PowerPoint 等其他软件中。导出比例、透明/有背景色、颜色主题等可以灵活配置。
+
+### 在代码块中调用 Dataview
+
+在插件设置中启用`解析 Dataview`功能后，`smiles` 代码块将逐行被 Dataview 解析，解析结果用于渲染结构图像。内联 Dataview 查询式 (Queries) 和内联 DataviewJS 的启用、前缀等设置与 Dataview 插件本体保持一致。
+
+![在 SMILES 代码块中编写内联 Dataview](https://github-production-user-asset-6210df.s3.amazonaws.com/73122375/292734194-d227fdb8-9c8f-4c87-965a-73c0f2445993.png)
+
+> [!Note]
+> 本功能依赖 Dataview 插件本体，若要使用本功能，请确保您已安装并启用 Dataview 插件
+> 运行 DataviewJS 语句的功能调用了 `eval()` 函数，具有一定的风险。请确保您输入/粘贴的代码是受信任的，防止意外执行恶意代码
+> 若您希望在启用 Dataview 查询式 (Queries) 时禁用 DataviewJS，请在 Dataview 插件设置中禁用 `Enable JavaScript Queries` 或 `Enable Inline JavaScript Queries`
+
+## SMILES 介绍
 
-#### SMILES 是什么？
+### SMILES 是什么？
 
 简化分子线性输入规范，Simplified Molecular-Input Line-Entry System，简称 SMILES，是一种用线性 ASCII 字符串描述化学结构的规范。您可以参阅[官方网站](http://opensmiles.org/opensmiles.html)或[维基百科](https://zh.wikipedia.org/wiki/%E7%AE%80%E5%8C%96%E5%88%86%E5%AD%90%E7%BA%BF%E6%80%A7%E8%BE%93%E5%85%A5%E8%A7%84%E8%8C%83)以了解更多内容
 
-#### 为什么使用 SMILES？
+### 为什么使用 SMILES？
 
 SMILES 使用 ASCII 字符串表示化学结构的特性与 Obsidian 的纯文本编辑器的定位十分契合。作为一种通用规范，SMILES 得到了许多专业化学工具的支持，相比于 mhchem 和 chemfig 等 LaTeX 包，使用起来更加方便；而与其他通用化学结构规范相比，SMILES 的语义明晰，可读性更强
 
-#### 如何生成 SMILES 字符串？
+### 如何生成 SMILES 字符串？
 
  对于简单结构，您在初步学习 SMILES 知识后即可手动输入。对于复杂结构，您可以使用 ChemDraw，[ChemDrawJS](https://chemdrawdirect.perkinelmer.cloud/js/sample/index.html#)，[MarvinJS](https://marvinjs-demo.chemaxon.com/latest/index.html) 或 [Ketcher](https://lifescience.opensource.epam.com/KetcherDemoSA/index.html) 等**结构编辑器**先行绘制，再导出 SMILES 字符串。您也可以使用 [Open Bable](http://openbabel.org/wiki/Main_Page)，[JOELib](https://sourceforge.net/projects/joelib/) 或 [Chemical Translation Service](https://cts.fiehnlab.ucdavis.edu/) 等**化学语言转换工具**/**化学数据库**，将化合物名称、CAS 号、*.mol 文件等转化为 SMILES 格式
 
 ## 安装步骤
 
-> **Note**  
+> [!Note]
 > 确保您已在设置→第三方插件中禁用**安全模式**
 
 本插件可以在官方插件市场中找到。在`设置→第三方插件→浏览`中，搜索 `Chem` 插件，点击安装并启用
@@ -47,8 +66,6 @@ SMILES 使用 ASCII 字符串表示化学结构的特性与 Obsidian 的纯文
 2. 将上述文件复制到您本地的笔记库的插件路径，如 `[yourvault]/.obsidian/plugins/chem/`。您可能需要自行新建 `chem` 这个文件夹
 3. 打开/重启 Obsidian 或刷新插件列表，您将看到 `Chem` 插件，点击启用，安装完成！
 
-后续会在中文论坛建立面向墙内的发布方法
-
 ## 插件定位
 
 我希望本插件能够提升化学相关笔记的记录体验。例如，您可能希望在电子实验记录中记下您今天合成的化合物的结构式，或者您想创建有机化学反应的 Anki 卡片等等。下面是一些我认为本插件可以提供的功能：
@@ -62,30 +79,22 @@ SMILES 使用 ASCII 字符串表示化学结构的特性与 Obsidian 的纯文
 
 你们的意见对这个插件的迭代、建设有着很大的帮助。本插件的首个功能——将 SMILES 字符串渲染为结构式，就是在社区用户的呼唤下开发的。我十分感谢用户们的有益讨论 （参见 [acknowledgment](https://github.com/Acylation/obsidian-chem#acknowledgment) 部分），也欢迎各位的任何反馈和建议
 
-## 设计原则
-
-本插件计划提供的功能需要至少满足下列条件中的一条：
-
-- 助力化学科研笔记，如实验记录、文献阅读笔记、论文大纲撰写等
-- 帮助构建与常用化学工具紧密协作的工作流
-- 利于化学、生物等相关学科的学习，如课程笔记、暗记卡片等
+## 贡献指南
 
-作为一个 Obsidian 插件，本项目遵循以下原则：
+首先感谢您考虑为本项目添砖加瓦！本插件欢迎任何错误报告（bug report）、功能请求（feature request）和合并请求（pull request）。更多细节请参见[贡献指南](docs/CONTRIBUTING-ZH.md)
 
-- 本地化：数据留存在本地，同时尽量使用独立包实现功能，避免调用在线服务
-- 无痕化：使用常规 markdown 元素和 LaTeX 实现功能，不能引入插件特定的格式，确保笔记清洁
-- 纯文本：数据以纯文本形式存储，尽量减少修饰格式，工作流同样以纯文本为中心
+> [!Note]  
+> 您可以直接使用中文提交内容。能力允许时，还希望您能够附上对应的英文关键词/标题，以便潜在的国际用户和开发者检索和阅读。您使用中文提交的内容将由我翻译
 
-## 贡献指南
+## 开发进展
 
-首先感谢您考虑为本项目添砖加瓦！本插件欢迎任何错误报告（bug report）、功能请求（feature request）和合并请求（pull request）。更多细节请参见[贡献指南](docs/CONTRIBUTING-ZH.md)
+本项目使用 GitHub Projects 记录[开发进展](https://github.com/users/Acylation/projects/6)
 
-> **Note**  
-> 您可以直接使用中文提交内容，但能力允许时，希望您能够附上对应的英文关键词/标题，以便潜在的国际用户和开发者检索和阅读。您使用中文提交的内容将由我翻译
+## 同类插件推荐
 
-## 路线图
+`Chem` 插件目前专注于将文本渲染为化学结构。如果您希望在 Obsidian 中从头**绘制**复杂的化学结构，[Ketcher](https://github.com/yuleicul/obsidian-ketcher) 插件集成了一个强大的结构编辑器。
 
-本项目使用 GitHub Projects 记录[路线图](https://github.com/users/Acylation/projects/6)，您可以在此查看开发进度
+[Chemical Structure Renderer](https://github.com/xaya1001/obsidian-Chemical-Structure-Renderer) 与本插件功能类似。不同于本插件的本机解析、渲染，`Chemical Structure Renderer` 是由 [Ketcher](https://github.com/epam/ketcher)、[Indigo](https://github.com/epam/Indigo) 等在线服务驱动的。
 
 ## 致谢
 

diff --git a/README.md b/README.md
@@ -6,39 +6,58 @@
 
 **Chem** is a plugin for [Obsidian.md](https://obsidian.md/) providing chemistry support. It allows you to insert chemical structures into your notes through code blocks containing SMILES strings (powered by [Smiles Drawer](https://github.com/reymond-group/smilesDrawer)).
 
-> **Note**  
-> Latest release: 0.2.1  
-> Document version: 0.2.1  
+> [!Note]
+> Latest release: 0.3.0  
+> Document version: 0.3.0  
 
 ## Features & Usage
 
-### Render SMILES strings as chemical structures
+### Render SMILES Strings as Chemical Structures
 
 You can use this plugin to render chemical structures from SMILES strings. Just type the SMILES strings in a code block with `smiles` as the language. Each line should contain only one string.
 
 The data is stored as plain text, so you won’t lose it. The renderer will always work, even if the plugin changes its cheminfo core.
 
-![Image](https://github.com/Acylation/obsidian-chem/assets/73122375/a9f9a440-dc66-4689-ab1a-1ef265242778)
+![Render SMILES strings into structures](https://github.com/Acylation/obsidian-chem/assets/73122375/a9f9a440-dc66-4689-ab1a-1ef265242778)
+
+### Global Sizing and Theming
 
 You can adjust the structure scale or the image size and configure light/dark themes of the structure images in the plugin’s settings page. The structures in open notes will be automatically updated when the plugin settings or Obsidian color scheme are changed.
 
-![Image](https://github.com/Acylation/obsidian-chem/assets/73122375/fde8d0a4-2c9c-458c-b357-78952480b755)
+![Configure size and theme](https://github.com/Acylation/obsidian-chem/assets/73122375/fde8d0a4-2c9c-458c-b357-78952480b755)
+
+### Copy & Export
+
+The copy feature is accessible through the right-click menu on images. Images are copied in `png` format. Despite common applications, you can also paste the copied image into your note, which will then save the image as a file to your attachment folder. The scale of the export, transparency, and theme can be configured to suit your needs.
+
+### Utilizing Dataview
+
+Inline Dataview queries and DataviewJS rendering can be enabled in the settings tab. Once enabled, lines within the smiles block will be checked and parsed. The return value from this process is used to render chemical structures, providing greater flexibility. The prefix and strategy are fetched directly from the corresponding Dataview plugin settings.
+
+![Dataview lines in smiles block](https://github-production-user-asset-6210df.s3.amazonaws.com/73122375/292734194-d227fdb8-9c8f-4c87-965a-73c0f2445993.png)
+
+> [!Note]
+> This feature is dependent on the Dataview plugin. Please ensure that you have installed and enabled it.
+> The execution of DataviewJS is implemented by calling `eval()` at the bottom,which is known to have safety issues.To avoid unintended execution, only trusted code lines should be passed.
+> If you wish to disable DataviewJS rendering, you can toggle off the `Enable JavaScript Queries` or `Enable Inline JavaScript Queries` options through the settings tab of the Dataview plugin.
+
+## Introduction on SMILES
 
-#### What is SMILES?
+### What is SMILES?
 
 SMILES stands for Simplified Molecular-Input Line-Entry System. It is a specification to describe chemical structures using linear ASCII strings. You can learn more about it from the [official website](http://opensmiles.org/opensmiles.html) or [Wikipedia](https://en.wikipedia.org/wiki/Simplified_molecular-input_line-entry_system).
 
-#### Why using SMILES?
+### Why Using SMILES?
 
 Using SMILES strings to represent molecules is easier and more widely supported by chemistry drawing tools than using LaTeX packages like mhchem and chemfig.
 
-#### How to generate SMILES strings?
+### How to Generate SMILES Strings?
 
  For simple structures, you can type them in manually. However, for more complex ones, you may want to use **structure editors**, such as ChemDraw, [ChemDrawJS](https://chemdrawdirect.perkinelmer.cloud/js/sample/index.html#), [MarvinJS](https://marvinjs-demo.chemaxon.com/latest/index.html) and [Ketcher](https://lifescience.opensource.epam.com/KetcherDemoSA/index.html). Also, you can use **translators** like [Open Bable](http://openbabel.org/wiki/Main_Page), [JOELib](https://sourceforge.net/projects/joelib/) and the [Chemical Translation Service](https://cts.fiehnlab.ucdavis.edu/) to convert chemical names, CAS numbers and *.mol files into SMILES strings.
 
 ## Installation
 
-> **Note**  
+> [!Note]  
 > Make sure that you are not in the **Restricted Mode**.
 
 The plugin is available in the official plugin market. You can go to Settings → Community plugins → Browse, and search for the `Chem` plugin by Acylation. After installing, you need to enable the plugin to use it.
@@ -63,20 +82,6 @@ I have a lot of ideas for this plugin, but my coding skills and resources are li
 
 I'd love to hear your feedback and suggestions. Actually, the first feature of the plugin, to render SMILES strings, was suggested by community users! I’m very grateful for their input. (See the [acknowledgment](https://github.com/Acylation/obsidian-chem#acknowledgment) section for details)
 
-## Design Philosophy
-
-Before working on a new feature, I will consider the following criteria. The feature should meet at least one of them to be useful.
-
-- It helps with taking notes on chemical research, like experimental records, literature notes, paper writing, etc.
-- It promotes a workflow that integrates well with other chemistry tools.
-- It aids in learning chemistry and related subjects.
-
-As an Obsidian plugin, this project adheres to the following principles:
-
-- Localize: Data should be kept local and standalone packages are preferred over remote services.
-- Leave No Trace: The plugin must not leave plugin-specific content in notes, allowing them to be shared with non-Obsidian users.
-- Plain Text Central: Plain text is preferred over complex formats.
-
 ## Contributing
 
 Thank you for your interest in contributing to this project! We welcome bug reports, feature requests, and pull requests from anyone. For more information on how to contribute to Chem, check out [CONTRIBUTING.md](docs/CONTRIBUTING.md).
@@ -85,6 +90,12 @@ Thank you for your interest in contributing to this project! We welcome bug repo
 
 Check out the [roadmap](https://github.com/users/Acylation/projects/6) to see what's been working on.
 
+## Companion Plugins
+
+`Chem` plugin is now primarily focused on rendering texts into structures. If you want to create complex structures from scratch, the [Ketcher](https://github.com/yuleicul/obsidian-ketcher) plugin has integrated a powerful opensource editor.
+
+[Chemical Structure Renderer](https://github.com/xaya1001/obsidian-Chemical-Structure-Renderer) is a similar plugin, which uses [Ketcher](https://github.com/epam/ketcher), [Indigo](https://github.com/epam/Indigo) online service for parsing and rendering.
+
 ## Acknowledgement
 
 The plugin relies on [Smiles Drawer](https://github.com/reymond-group/smilesDrawer) as the parsing and drawing core, and uses [Mathpix](https://github.com/Mathpix/mathpix-markdown-it) as an example on how to integrate the package. Thank you very much!

diff --git a/docs/CONTRIBUTING-ZH.md b/docs/CONTRIBUTING-ZH.md
@@ -2,6 +2,20 @@
 
 [English](CONTRIBUTING.md) | [简体中文](CONTRIBUTING-ZH.md)
 
+## 设计原则
+
+本插件计划提供的功能需要至少满足下列条件中的一条：
+
+- 助力化学科研笔记，如实验记录、文献阅读笔记、论文大纲撰写等
+- 帮助构建与常用化学工具紧密协作的工作流
+- 利于化学、生物等相关学科的学习，如课程笔记、暗记卡片等
+
+作为一个 Obsidian 插件，本项目遵循以下原则：
+
+- 本地化：数据留存在本地，同时尽量使用独立包实现功能，避免调用在线服务
+- 无痕化：使用常规 Markdown 元素和 LaTeX 实现功能，不能引入插件特定的格式，确保笔记清洁
+- 纯文本：数据以纯文本形式存储，尽量减少修饰格式，工作流同样以纯文本为中心
+
 ## 通过 Issue 提交错误报告和功能请求
 
 - 您可以使用 [issue tracker](https://github.com/Acylation/obsidian-chem/issues) 报告本插件的任何错误，或提交您希望实现的功能

diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -2,6 +2,20 @@
 
 [简体中文](CONTRIBUTING-ZH.md) | [English](CONTRIBUTING.md)
 
+## Design Philosophy
+
+Before working on a new feature, I will consider the following criteria. The feature should meet at least one of them to be useful.
+
+- It helps with taking notes on chemical research, like experimental records, literature notes, paper writing, etc.
+- It promotes a workflow that integrates well with other chemistry tools.
+- It aids in learning chemistry and related subjects.
+
+As an Obsidian plugin, this project adheres to the following principles:
+
+- Localize: Data should be kept local and standalone packages are preferred over remote services.
+- Leave No Trace: The plugin must not leave plugin-specific content in notes, allowing them to be shared with non-Obsidian users.
+- Plain Text Central: Plain text is preferred over complex formats.
+
 ## How to report a bug or suggest a feature
 
 - Please use the [issue tracker](https://github.com/Acylation/obsidian-chem/issues) to report any problems or suggest new features.

diff --git a/src/SmilesBlock.ts b/src/SmilesBlock.ts
@@ -24,7 +24,7 @@ export class SmilesBlock extends MarkdownRenderChild {
 		super(el); // important
 		addBlock(this);
 	}
-  
+
 	// TODO: rendering animation
 	async render() {
 		this.el.empty();
@@ -92,7 +92,7 @@ export class SmilesBlock extends MarkdownRenderChild {
 
 			const func = new Function(
 				'api',
-				`return eval("const dv=api;const dataview = api; ${code}")` // await & async exec
+				`return eval(\`const dv=api;const dataview = api; ${code}\`)` // await & async exec
 			);
 
 			return func(api)?.toString() ?? 'DataviewJS parsing error';