feat: Map Inline Comments with best effort

.github/workflows/docs.yml

@@ -1,4 +1,4 @@
-name: Deploy
+name: Docs
 on:
   push:
     branches:
@@ -34,11 +34,14 @@ jobs:
         mkdir mdbook
         curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.27/mdbook-v0.4.27-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
         echo `pwd`/mdbook >> $GITHUB_PATH
+        cargo install mdbook-mermaid
     - name: Deploy GitHub Pages
       run: |
         # This assumes your book is in the root of your repository.
         # Just add a `cd` here if you need to change to another directory.
+        cp CHANGELOG.md docs/src/CHANGELOG.md
         cd docs
+        mdbook-mermaid install .
         mdbook build
     - name: Setup Pages
       uses: actions/configure-pages@f156874f8191504dae5b037505266ed5dda6c382 # v3.0.6

docs/book.toml

@@ -6,10 +6,12 @@ src = "src"
 title = "Obsidian Confluence Integration"
 create-missing = false
 
+[preprocessor.mermaid]
+command = "mdbook-mermaid"
 
 [output.html]
 git-repository-url = "https://github.com/obsidian-confluence/obsidian-confluence"
 git-repository-icon = "fa-github"
 edit-url-template = "https://github.com/obsidian-confluence/obsidian-confluence/edit/main/docs/{path}"
 cname = "obsidian-confluence.com"
-
+additional-js = ["mermaid.min.js", "mermaid-init.js"]

docs/src/SUMMARY.md

@@ -6,6 +6,7 @@
 	- [Installation](./getting-started/installation.md)
 	- [Installation - BRAT](./getting-started/installation-brat.md)
 - [Supported Features](./features/index.md)
+    - [Comments](./features/comment-handling.md)
 	- [Supported Markdown](./features/supported-markdown.md)
 	- [Folder Note](./features/folder-note.md)
 	- [Folder Structure](./features/folder-structure.md)
@@ -14,4 +15,5 @@
 	- [YAML Frontmatter](./features/yaml-frontmatter.md)
 	- [Callouts](./features/callouts.md)
 	- [Wikilinks](./features/wikilinks.md)
-- [Thanks](thanks.md)
+- [Thanks](thanks.md)
+- [Changelog](CHANGELOG.md)

docs/src/features/comment-handling.md

@@ -0,0 +1,51 @@
+# Comment Handling
+
+This plugin attempts to find the original location of a comment and reattach it. If it cannot determine the correct location, it will add a section to the bottom of the page and place the comment there.
+
+# Comment Matching Process
+
+## No matches found
+If no matches for the text the comment was attached to are found, the comment is moved to the unmatched comment section.
+
+## Exact Match
+The plugin first tries to find an exact match for the comment by comparing the text before and after the comment. If an exact match is found, the comment is attached at that location.
+
+## Distance of whole before and after 
+If an exact match is not found, the plugin calculates the "distance" between the text before and after the comment in the original location and each potential new location. This distance is calculated using the Levenshtein distance algorithm, which measures the number of changes (insertions, deletions, or substitutions) required to transform one string into another. If there are more than 40 changes before and after the comment text the node is excluded from being a viable option. The potential matches are sorted based on the calculated distances, and the match with the smallest distance is chosen.
+
+## Distance of 2 words before and after
+If there are still multiple matches with similar distances, the plugin narrows down the selection by comparing only the words immediately surrounding the comment. The Levenshtein distance is calculated again, and the best match is chosen based on the smallest distance.
+
+## No ability to match
+If no suitable match is found, the function returns undefined.
+
+## Flow chart
+```mermaid
+flowchart TD
+    Start --> DoesCommentTextExist{Does comment text exist on page?}
+    DoesCommentTextExist -->|Yes| DoesExactMatchExist{Does exact match before and after comment text?}
+    DoesCommentTextExist -->|No| UnmatchedCommentSection[Unmatched Comment Section]
+    DoesExactMatchExist -->|Yes| AttachComment[Attach Comment To This ADF Node]
+    DoesExactMatchExist -->|No| CalculateLevenshtein
+
+    subgraph WholeBeforeAfter
+        CalculateLevenshtein[Calculate Levenshtein Distance Between Before and After text] --> SortByMinimumDistance[Sort by minimum distance]
+        SortByMinimumDistance --> IsFirstItemMinimumDistanceUnder40{Is first item minimum distance under 40 changes?}
+    end
+
+    IsFirstItemMinimumDistanceUnder40 -->|Yes| AttachComment
+    IsFirstItemMinimumDistanceUnder40 -->|No| GetXWordsBeforeAfterComment[Get X Words before and after comment]
+
+    subgraph WordsBeforeAfter
+        GetXWordsBeforeAfterComment --> TrimBeforeAndAfterToSameLength
+        TrimBeforeAndAfterToSameLength --> CalculateWordsLevenshtein
+        CalculateWordsLevenshtein --> IsDistanceLessThan50percentCharacters{IsDistanceLessThan50percentCharacters}
+        IsDistanceLessThan50percentCharacters -->|Yes| AddToChecks
+        IsDistanceLessThan50percentCharacters -->|Yes| CalculateWordsLevenshtein
+        IsDistanceLessThan50percentCharacters -->|No| CalculateWordsLevenshtein
+        AddToChecks --> SortByWordsMinimumDistance
+        SortByWordsMinimumDistance --> IsThereAnyItems{IsThereAnyItems}
+    end
+
+    IsThereAnyItems -->|Yes| AttachComment
+    IsThereAnyItems -->|No| UnmatchedCommentSection

packages/lib/package.json

@@ -26,6 +26,7 @@
         "@types/prosemirror-transform": "^1.4.2",
         "@types/prosemirror-view": "^1.23.1",
         "@types/spark-md5": "^3.0.2",
+        "@types/uuid": "^9.0.0",
         "jest": "^29.5.0",
         "markdown-it": "^13.0.1"
     },
@@ -43,7 +44,8 @@
         "prosemirror-markdown": "^1.10.1",
         "prosemirror-model": "1.14.3",
         "sort-any": "^4.0.5",
-        "spark-md5": "^3.0.2"
+        "spark-md5": "^3.0.2",
+        "uuid": "^9.0.0"
     },
     "resolutions": {
         "prosemirror-model": "1.14.3"

packages/lib/src/AdfEqual.ts

@@ -1,8 +1,7 @@
 import sortAny from "sort-any";
 import { mapValues } from "lodash";
 import { traverse } from "@atlaskit/adf-utils/traverse";
-import { JSONDocNode } from "@atlaskit/editor-json-transformer";
-import { ADFEntityMark } from "@atlaskit/adf-utils/types";
+import { ADFEntity, ADFEntityMark } from "@atlaskit/adf-utils/types";
 import { isEqual } from "./isEqual";
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -25,7 +24,7 @@ const sortDeep = (object: unknown): any => {
 	return sortAny(object.map(sortDeep));
 };
 
-export function orderMarks(adf: JSONDocNode) {
+export function orderMarks(adf: ADFEntity) {
 	return traverse(adf, {
 		any: (node, __parent) => {
 			if (node.marks) {
@@ -36,7 +35,7 @@ export function orderMarks(adf: JSONDocNode) {
 	});
 }
 
-export function adfEqual(first: JSONDocNode, second: JSONDocNode): boolean {
+export function adfEqual(first: ADFEntity, second: ADFEntity): boolean {
 	return isEqual(orderMarks(first), orderMarks(second));
 }