From a748e26166e25f825477071673f362abaedd8624 Mon Sep 17 00:00:00 2001
From: elmaester <54346168+elmaester@users.noreply.github.com>
Date: Sat, 15 Jan 2022 20:04:40 +0200
Subject: [PATCH] Integrating Remark42 with Gatsby (documentation) (#1222)

* add sample Gatsby/React component with comments md

* fix typo

* remove semicolons

* add link to gatsby doc in nav.json

* fix typo

* make comment actually a comment in the return

* improve comment syntax

Co-authored-by: Ben <BenRoe@users.noreply.github.com>
---
 .../integration-with-gatsby/index.md          | 98 +++++++++++++++++++
 site/src/docs/nav.json                        |  4 +
 2 files changed, 102 insertions(+)
 create mode 100644 site/src/docs/getting-started/integration-with-gatsby/index.md

diff --git a/site/src/docs/getting-started/integration-with-gatsby/index.md b/site/src/docs/getting-started/integration-with-gatsby/index.md
new file mode 100644
index 00000000..bf62c6b2
--- /dev/null
+++ b/site/src/docs/getting-started/integration-with-gatsby/index.md
@@ -0,0 +1,98 @@
+# Using Remark42 in Gatsby projects
+## Sample Comments.js React component:
+
+```js
+
+import * as React from "react"
+
+// This function will insert the usual <script> tag of
+// Remark42 into the specified DOM location (parentElement)
+const insertScript = (id, parentElement) => {
+  const script = window.document.createElement("script")
+  script.type = "text/javascript"
+  script.async = true
+  script.id = id
+  /* For Gatsby it's important to manually provide the URL
+  and make sure it does not contain a trailing slash ("/").
+  Because otherwise the comments for paths with/without 
+  the trailing slash are stored separately in the BoltDB database.
+  When following a Gatsby Link a page is loaded without the trailing slash,
+  but when refreshing the page (F5) it is loaded with the trailing slash.
+  So essentially every URL can become duplicated in the DB and you may not see
+  your comments from the inverse URL at your present URL.
+  Making sure url is provided without the trailing slash
+  in the remark42 config solves this. */
+  let url = window.location.origin + window.location.pathname
+  if(url.endsWith("/")) {
+    url = url.slice(0, -1)
+  }
+  // Now the actual config and script-fetching function:
+  script.innerHTML = `
+    var remark_config = {
+      host: "https://remark42.example.com",
+      site_id: "example-name",
+      url: "${url}",
+      theme: "dark",
+      components: ["embed"],
+    };
+    !function(e,n){for(var o=0;o<e.length;o++){var r=n.createElement("script"),c=".js",d=n.head||n.body;"noModule"in r?(r.type="module",c=".mjs"):r.async=!0,r.defer=!0,r.src=remark_config.host+"/web/"+e[o]+c,d.appendChild(r)}}(remark_config.components||["embed"],document);`
+  parentElement.appendChild(script)
+}
+
+/* This function removes the previously added script from the DOM.
+Might be necessary when page transitions happen, to make sure a new instance 
+is created, pointing to the current URL. Although this might actually 
+not be necessary, please do your own testing.*/
+const removeScript = (id, parentElement) => {
+  const script = window.document.getElementById(id)
+  if (script) {
+    parentElement.removeChild(script)
+  }
+}
+
+// This function will be provided to useEffect and will insert the script
+// when the component is mounted and remove it when it unmounts
+const manageScript = () => {
+  if (!window) {
+    return
+  }
+  const document = window.document
+  if (document.getElementById("remark42")) {
+    insertScript("comments-script", document.body)
+  }
+  return () => removeScript("comments-script", document.body)
+}
+
+/* Another function for another useEffect - this is the most crucial part for
+Gatsby compatibility. It will ensure that each page loads its own appropriate
+comments, and that comments will be properly loaded */
+const recreateRemark42Instance = () => {
+    if (!window) {
+      return
+    }
+    const remark42 = window.REMARK42
+    if (remark42) {
+      remark42.destroy()
+      remark42.createInstance(window.remark_config)
+    }
+}
+
+// The location prop is {props.location.pathname} from the parent component.
+// I.e. invoke the component like this in the parent: <Comments location={props.location.pathname} />
+const Comments = ({ location }) => {
+  // Insert the two useEffect hooks. Maybe you can combine them into one? Feel free if you want to.
+  React.useEffect(manageScript, [location])
+  React.useEffect(recreateRemark42Instance, [location])
+
+  return (
+    <>
+      <h2>Comments</h2>
+      { /* This div is the target for actual comments insertion */ }
+      <div id="remark42"></div>
+    </>
+  )
+}
+
+export default Comments
+
+```
diff --git a/site/src/docs/nav.json b/site/src/docs/nav.json
index 17b97461..09b8ae08 100644
--- a/site/src/docs/nav.json
+++ b/site/src/docs/nav.json
@@ -9,6 +9,10 @@
 	  {
 		"title": "System Requirements",
 		"href": "/getting-started/system-requirements/"
+	  },
+	  {
+		"title": "Integration With Gatsby",
+		"href": "/getting-started/integration-with-gatsby/"
 	  }
 	]
   },