add doc for experimental features (#507)

hizzgdev · Oct 10, 2023 · e189f65 · e189f65
1 parent 54e0ad6
commit e189f65
Show file tree

Hide file tree

Showing 16 changed files with 223 additions and 79 deletions.
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 [![npm version](https://badge.fury.io/js/jsmind.svg)](https://www.npmjs.com/package/jsmind)
 ![build-test](https://github.com/hizzgdev/jsmind/actions/workflows/node.js.yml/badge.svg)
 
-jsMind 是一个显示/编辑思维导图的纯 javascript 类库，其基于 html5 canvas (和 svg) 进行设计。jsMind 以 [BSD 协议开源](LICENSE)，在此基础上你可以在你的项目上任意使用。
+jsMind 是一个显示/编辑思维导图的纯 javascript 类库，其基于 html5 canvas 和 svg 进行设计。jsMind 以 [BSD 协议开源](LICENSE)，在此基础上你可以在你的项目上任意使用。
 
 jsMind is mind map library built by javascript, it base on html5 canvas and svg. jsMind is released under [the BSD license](LICENSE), you can embed it in any project as long as you abide by the license.
 

diff --git a/docs/en/1.usage.md b/docs/en/1.usage.md
@@ -1,10 +1,11 @@
 [Table of Contents](index.md)
 
-1. [Usage *](1.usage.md)
-2. [Options](2.options.md)
-3. [Operation](3.operation.md)
-4. [Contribution](4.contribution.md)
-5. [Attached: Development Guide](5.development.md)
+* [1. Usage *](1.usage.md)
+* [2. Options](2.options.md)
+* [3. Operation](3.operation.md)
+* [Experimental Features](experimental-features.md)
+* [Contribution](4.contribution.md)
+* [Development Guide](5.development.md)
 
 1.1. Basic Framework
 ===

diff --git a/docs/en/2.options.md b/docs/en/2.options.md
@@ -1,10 +1,11 @@
 [Table of Contents](index.md)
 
-1. [Usage](1.usage.md)
-2. [Options *](2.options.md)
-3. [Operation](3.operation.md)
-4. [Contribution](4.contribution.md)
-5. [Attached: Development Guide](5.development.md)
+* [1. Usage](1.usage.md)
+* [2. Options *](2.options.md)
+* [3. Operation](3.operation.md)
+* [Experimental Features](experimental-features.md)
+* [Contribution](4.contribution.md)
+* [Development Guide](5.development.md)
 
 
 2.1. Introduction

diff --git a/docs/en/3.operation.md b/docs/en/3.operation.md
@@ -1,10 +1,11 @@
 [Table of Contents](index.md)
 
-1. [Usage](1.usage.md)
-2. [Options](2.options.md)
-3. [Operation *](3.operation.md)
-4. [Contribution](4.contribution.md)
-5. [Attached: Development Guide](5.development.md)
+* [1. Usage](1.usage.md)
+* [2. Options](2.options.md)
+* [3. Operation *](3.operation.md)
+* [Experimental Features](experimental-features.md)
+* [Contribution](4.contribution.md)
+* [Development Guide](5.development.md)
 
 
 jsMind object

diff --git a/docs/en/4.contribution.md b/docs/en/4.contribution.md
@@ -1,12 +1,13 @@
 [Table of Contents](index.md)
 
-1. [Usage](1.usage.md)
-2. [Options](2.options.md)
-3. [Operation](3.operation.md)
-4. [Contribution *](4.contribution.md)
-5. [Attached: Development Guide](5.development.md)
-
-4.1. contribution code
+* [1. Usage](1.usage.md)
+* [2. Options](2.options.md)
+* [3. Operation](3.operation.md)
+* [Experimental Features](experimental-features.md)
+* [Contribution *](4.contribution.md)
+* [Development Guide](5.development.md)
+
+Contribution code
 ===
 
 jsMind still has a lot of room for improvement and optimization. You are welcome to contribute code to jsMind.
@@ -18,14 +19,17 @@ The most convenient way to contribute code is to submit a pull-request to the js
 
 Before submitting a pull-request, be sure to test it well and make a detailed note when submitting the pull-request, including feature descriptions, code change notes.
 
-4.2 ask questions or contribute ideas
+Ask questions or contribute ideas
 ===
 
 Or you can bring up a problem or need you've encountered via an issue for discussion, and hopefully a friend who has the ability and energy to join in and solve the problem together.
 
 For common requirements, it is recommended to implement post-implementation feedback to the open source project, for non-common requirements, you can fork out a separate warehouse for custom development.
 
-It is important to note that open source does not mean free. jsMind itself doesn't restrict commercial use, but it's only right to be paid for custom development.
+Customization
+===
+
+JsMind is an open source library with the BSD license, and can be used in commercial production. If there is a need for customization, please contact the author or other developers you trust.
 
 copyright notice
 ===

diff --git a/docs/en/5.development.md b/docs/en/5.development.md
@@ -1,15 +1,16 @@
 [Table of Contents](index.md)
 
-1. [Usage](1.usage.md)
-2. [Options](2.options.md)
-3. [Operation](3.operation.md)
-4. [Contribution](4.contribution.md)
-5. [Attached: Development Guide *](5.development.md)
+* [1. Usage](1.usage.md)
+* [2. Options](2.options.md)
+* [3. Operation](3.operation.md)
+* [Experimental Features](experimental-features.md)
+* [Contribution](4.contribution.md)
+* [Development Guide *](5.development.md)
 
 
 > First of all, I would like to express my gratitude to you. The open source community is thriving because of you, and jsMind has gained even greater value because of you.
 
-5.1. contributing process
+Contributing process
 ===
 
 The basic process of contributing code to jsMind is:
@@ -21,7 +22,7 @@ The basic process of contributing code to jsMind is:
 5. Waiting for review, you may be asked to modify your code during the review
 6. Merge your pull-request
 
-5.2. preparation
+Preparation
 ===
 
 **Pull-Request and Fork** : read the github [article of pull-request](https://docs.github.com/cn/pull-requests) to learn how to submit your code using fork and pull-request.
@@ -30,7 +31,7 @@ The basic process of contributing code to jsMind is:
 
 **Visual Studio Code** : If your IDE is VS Code, it's recommended to install the plugin `esbenp.prettier-vscode`. In this way, your code will be formatted according to the configuration of jsMind automatically.
 
-5.3. development
+Development
 ===
 
 jsMind is written in ES6 format, source code is in `/src`. Generally, only the code in it needs to be modified.
@@ -41,7 +42,7 @@ Please remember to format the code at any time during the development process. E
 npm run format
 ```
 
-5.4. unit test
+Unit Test
 ===
 
 The code of unit test is in `/tests/unit`. Please add unit test for the code changes, and make sure all unit tests pass.
@@ -52,7 +53,7 @@ Execute the following command to run the unit tests:
 npm run test-es6
 ```
 
-5.5. packaging and compression
+Packaging and compression
 ===
 
 Execute the following command to package the code into a js file that can work in web browsers:
@@ -63,7 +64,7 @@ npm run build
 
 The js file will be generated into `/es6`
 
-5.6. Local running and debugging
+Local running and debugging
 ===
 Execute the following command to start a simple http server
 

diff --git a/docs/en/experimental-features.md b/docs/en/experimental-features.md
@@ -0,0 +1,63 @@
+[Table of Contents](index.md)
+
+* [1. Usage](1.usage.md)
+* [2. Options](2.options.md)
+* [3. Operation](3.operation.md)
+* [Experimental Features *](experimental-features.md)
+* [Contribution](4.contribution.md)
+* [Development Guide](5.development.md)
+
+> Special note: These experimental features are not guaranteed to continue to exist in subsequent versions, nor are their API compatibility guaranteed. If experimental features are used in your project, please upgrade jsmind with caution in the future.
+
+Export Image/Screenshot
+===
+This feature can support to export mind maps as png images.
+
+```html
+
+<!-- style -->
+<link type="text/css" rel="stylesheet" href="https://unpkg.com/[email protected]/style/jsmind.css" />
+
+<!-- jsMind -->
+<script type="text/javascript" src="https://unpkg.com/[email protected]/es6/jsmind.js"></script>
+
+<!-- dependency of screenshot -->
+<script type="text/javascript" src="https://unpkg.com/[email protected]/dist/dom-to-image.min.js" ></script>
+
+<!-- screenshot plugin -->
+<script type="text/javascript" src="https://unpkg.com/[email protected]/es6/jsmind.screenshot.js"></script>
+
+
+<script>
+    var jm = new jsMind(options);
+    jm.show(mind_data);
+    // export current mindmap to an image
+    jm.shoot()
+</script>
+
+```
+
+If you use npm, please install `jsmind` and `dom-to-image`
+
+```bash
+npm install jsmind
+npm install dom-to-image
+```
+
+And then use it the same way on the page.
+
+```html
+<script>
+    import domtoimage from 'dom-to-image';
+    import jsMind from 'jsmind'
+    import 'jsmind/screenshot'
+    import 'jsmind/style/jsmind.css'
+
+    // ...
+
+    var jm = new jsMind(options);
+    jm.show(mind_data);
+    // export current mindmap to an image
+    jm.shoot()
+</script>
+```
diff --git a/docs/en/index.md b/docs/en/index.md
@@ -19,8 +19,9 @@ Table of Contents
   * 3.5 Setting Style
   * 3.6 Access to Data
   * 3.7 Other Operations
-* [4. Contribution](4.contribution.md)
-* [Attached: Development Guide](5.development.md)
+* [Experimental Features](experimental-features.md)
+* [Contribution](4.contribution.md)
+* [Development Guide](5.development.md)
 
 copyright notice
 ======

diff --git a/docs/index.md b/docs/index.md
@@ -4,14 +4,16 @@
 * [1. 基本用法](zh/1.usage.md)
 * [2. 选项](zh/2.options.md)
 * [3. 界面操控](zh/3.operation.md)
-* [4. 参与贡献](zh/4.contribution.md)
-* [附：贡献代码指南](zh/5.development.md)
+* [实验性功能](zh/experimental-features.md)
+* [参与贡献](zh/4.contribution.md)
+* [贡献代码指南](zh/5.development.md)
 
 ## English
 
 * [Table of Contents](en/index.md)
 * [1. Usage](en/1.usage.md)
 * [2. Options](en/2.options.md)
 * [3. API / Operation](en/3.operation.md)
-* [4. Contribution](en/4.contribution.md)
-* [Attached: Development Guide](en/5.development.md)
+* [Experimental Features](en/experimental-features.md)
+* [Contribution](en/4.contribution.md)
+* [Development Guide](en/5.development.md)
diff --git a/docs/zh/1.usage.md b/docs/zh/1.usage.md
@@ -1,10 +1,11 @@
 [目录](index.md)
 
-1. [基本用法 *](1.usage.md)
-2. [选项](2.options.md)
-3. [界面操控](3.operation.md)
-4. [参与贡献](4.contribution.md)
-5. [附：贡献代码指南](5.development.md)
+* [1. 基本用法 *](1.usage.md)
+* [2. 选项](2.options.md)
+* [3. 界面操控](3.operation.md)
+* [实验性功能](experimental-features.md)
+* [参与贡献](4.contribution.md)
+* [贡献代码指南](5.development.md)
 
 1.1. 基本框架
 ===

diff --git a/docs/zh/2.options.md b/docs/zh/2.options.md
@@ -1,10 +1,11 @@
 [目录](index.md)
 
-1. [基本用法](1.usage.md)
-2. [选项 *](2.options.md)
-3. [界面操控](3.operation.md)
-4. [参与贡献](4.contribution.md)
-5. [附：贡献代码指南](5.development.md)
+* [1. 基本用法](1.usage.md)
+* [2. 选项 *](2.options.md)
+* [3. 界面操控](3.operation.md)
+* [实验性功能](experimental-features.md)
+* [参与贡献](4.contribution.md)
+* [贡献代码指南](5.development.md)
 
 2.1. 综述
 ===

diff --git a/docs/zh/3.operation.md b/docs/zh/3.operation.md
@@ -1,10 +1,11 @@
 [目录](index.md)
 
-1. [基本用法](1.usage.md)
-2. [选项](2.options.md)
-3. [界面操控 *](3.operation.md)
-4. [参与贡献](4.contribution.md)
-5. [附：贡献代码指南](5.development.md)
+* [1. 基本用法](1.usage.md)
+* [2. 选项](2.options.md)
+* [3. 界面操控 *](3.operation.md)
+* [实验性功能](experimental-features.md)
+* [参与贡献](4.contribution.md)
+* [贡献代码指南](5.development.md)
 
 jsMind 对象
 ===

diff --git a/docs/zh/4.contribution.md b/docs/zh/4.contribution.md
@@ -1,12 +1,13 @@
 [目录](index.md)
 
-1. [基本用法](1.usage.md)
-2. [选项](2.options.md)
-3. [界面操控](3.operation.md)
-4. [参与贡献 *](4.contribution.md)
-5. [附：贡献代码指南](5.development.md)
-
-4.1. 贡献代码
+* [1. 基本用法](1.usage.md)
+* [2. 选项](2.options.md)
+* [3. 界面操控](3.operation.md)
+* [实验性功能](experimental-features.md)
+* [参与贡献 *](4.contribution.md)
+* [贡献代码指南](5.development.md)
+
+贡献代码
 ===
 
 jsMind 还有很多可以完善及优化的地方，欢迎任何人给 jsMind 贡献代码。
@@ -21,14 +22,14 @@ jsMind 还有很多可以完善及优化的地方，欢迎任何人给 jsMind
 在提交 pull-request 前，请务必做好测试，并在提交 pull-request 时做出详细的说明，包括功能特性介绍、代码变更说明。
 
 
-4.2. 提出问题或贡献想法
+提出问题或贡献想法
 ===
 
 或者您可以将您遇到的问题或想法通过 issue 的方式提出来供大家讨论，希望有能力和精力的朋友共同参与，一起解决问题。
 
 对于共性的需求，建议实现后回馈到开源项目中，对于非共性的需求，可 fork 出独立仓库进行定制开发。
 
-4.3. 需要定制开发
+需要定制开发
 ===
 
 jsMind 以 BSD 协议开源，并不限制商业使用。如果需要定制开发，请单独联系作者或您依赖的其他开发者。