Arc-2030 convert markdown to html (#23)

rachellerathbone · mboudreau · web-flow · commit 8cf60afce15c · 2023-03-20T13:27:35.000+11:00
Co-authored-by: Michel Boudreau &lt;michelboudreau@gmail.com&gt;
diff --git a/package.json b/package.json
@@ -22,9 +22,12 @@
   },
   "dependencies": {
     "@commonify/lowdb": "^3.0.0",
+    "@types/marked": "^4.0.8",
     "atlassian-jwt": "^2.0.2",
     "express": "^4.18.2",
     "lodash": "^4.17.21",
+    "marked": "^4.2.12",
+    "sanitize-html": "^2.10.0",
     "squirrelly": "^8.0.8",
     "uuid": "^9.0.0"
   },
diff --git a/src/content/api-requests.md b/src/content/api-requests.md
@@ -1,12 +1,12 @@
-### Making API requests
+# Making API requests
 
 If you need to make API requests, this can be easily achieved via any HTTP client library or API designed
 for making API requests. The key to successfully making API requests from your Connect add-on is ensuring
 you create a JWT token, based on the `sharedSecret`, and include this token in your header. Please refer
 to our documentation for more information on 
 [JWTs for Connect app](https://developer.atlassian.com/cloud/jira/platform/understanding-jwt-for-connect-apps/).
 
-#### Jira and Confluence REST APIs
+## Jira and Confluence REST APIs
 Both [Jira](https://developer.atlassian.com/cloud/jira/software/rest/intro/#introduction) 
 and [Confluence](https://developer.atlassian.com/cloud/confluence/using-the-rest-api/) provide an extensive 
 REST API to build add-ons. 
diff --git a/src/content/authentication.md b/src/content/authentication.md
@@ -1,4 +1,4 @@
-### Auth with JWT and Storage
+# Auth with JWT and Storage
 
 Atlassian Connect authenticates apps using JWT tokens. At installation time, the Connect app and the Atlassian host 
 product exchange a security context containing an installation secret used to create and validate JWT tokens for use 
@@ -12,7 +12,7 @@ were altered in transit (integrity).
 
 - **_JWT requires installed lifecycle event:_** For veritification of the JWT token to work, you need to have included the lifecycle event `installed` in your app descriptor.
 
-#### How to leverage Atlassian Connect's authentication feature:
+## How to leverage Atlassian Connect's authentication feature:
 
 1. Declare that the app uses JWT as the authentication mechanism in the app descriptor e.g.
 ```
@@ -27,7 +27,7 @@ were altered in transit (integrity).
 > If you have no security on your endpoints you have the option to set the authentication type to 'none' in your app descriptor. However, we strongly recommend you do not do this and instead set the type to 'jwt' as referenced above.
 
 
-#### Installation handshake
+### Installation handshake
 
 When an administrator installs the app in an Atlassian cloud instance, Connect initiates an "installation handshake" -  a way for 
 the Atlassian application and the app to exchange keys stored on both sides for future API calls. 
@@ -40,7 +40,7 @@ contained in this security context include:
 
 > **_NOTE:_**  The installation handshake only occurs when you are using the optional [lifecycle event](https://developer.atlassian.com/platform/forge/events-reference/life-cycle/) `installed`.
 
-#### Signing of the Lifecycle Callbacks
+### Signing of the Lifecycle Callbacks
 
 When JWT authentication is used the lifecycle callbacks are signed using a shared secret.
 
@@ -51,7 +51,7 @@ When JWT authentication is used the lifecycle callbacks are signed using a share
 | Uninstall, Enable and Disable | The shared secret sent in the preceding `installed` callback. |
 | First install after being uninstalled | The shared secret sent in the preceding installed callback. This allows apps to allow the new installation to access previous tenant data (if any exists). A valid signature demonstrates that the sender is in possession of the shared secret from when the old tenant data was accessed. |
 
-#### Authentication how-to
+### Authentication how-to
 
 **Creating the app descriptor**
 
@@ -82,7 +82,7 @@ For example:
 
 **Installation data**
 When the app is installed, the Atlassian application invokes a callback endpoint exposed by the app. The request 
-contains a payload with important tenant information that you will need to store in your app in order to sign 
+contains a payload with important tenant information that you will need to store in your app in order to sign
 and verify future requests e.g.
 
 ```
@@ -129,7 +129,7 @@ These steps must be executed before processing the request, and the request must
 For more details on how to decode and validate a JWT token, see [Decoding and Verifying a JWT Token](https://developer.atlassian.com/cloud/bitbucket/understanding-jwt-for-apps/#decoding-and-verifying-a-jwt-token), 
 which also provides a comprehensive list of claims supported by Atlassian products that you need to validate.
 
-#### Atlassian JWT libraries
+### Atlassian JWT libraries
 
 In this sample app, we use the [atlassian-jwt](https://www.npmjs.com/package/atlassian-jwt) library to create a middleware 
 called `connectIframeJWTMiddleware`, which decodes the JWT token from Jira, verifies it and sets the `clientKey` in `res.locals`.
@@ -142,10 +142,10 @@ The tenant (Jira site) for each instance of the app is recognized based on this
 - verify the query string hash
 - save the jiraTenant to `res.locals` to be used later if all verifications pass
 
-#### Customer Specific Storage
+## Customer Specific Storage
 
 When it comes to storing data for your authenticated Connect add-on, you have a couple of options:
 - use the [add-on properties REST API](https://developer.atlassian.com/cloud/confluence/app-properties-api/)
 - storing data with entity properties
   - [Jira](https://developer.atlassian.com/cloud/jira/platform/storing-data-with-entity-properties/)
-  - [Confluence](https://developer.atlassian.com/cloud/confluence/confluence-entity-properties/)
+  - [Confluence](https://developer.atlassian.com/cloud/confluence/confluence-entity-properties/)
diff --git a/src/content/config.md b/src/content/config.md
@@ -1,4 +1,4 @@
-### Atlassian Connect JSON
+# Atlassian Connect JSON
 
 When you create a Connect app you'll need to include an app descriptor JSON file. This is what you'll use to
 provide information to Atlassian about your application, also known as an add-on. In this sample app you'll find 
@@ -37,6 +37,6 @@ more detail in **Lifecycle Events**
     [Confluence](https://marketplace.atlassian.com/apps/1215092/web-fragment-finder-for-confluence?hosting=cloud&tab=overview)
     - `name`: a human-readable name for the page
 
-Please refer to our [documentation](https://developer.atlassian.com/cloud/jira/platform/connect-app-descriptor/#authentication) 
+Please see below for the app descriptor used in this example. Additionally, refer to our [documentation](https://developer.atlassian.com/cloud/jira/platform/connect-app-descriptor/#authentication) 
 for more Connect app description information.
 
diff --git a/src/content/connect-js.md b/src/content/connect-js.md
@@ -1,4 +1,4 @@
-### Connect JavaScript API
+# Connect JavaScript API
 
 Connect apps extend Jira and Confluence by adding a custom iframe into the products' web pages. This iframe instance is 
 on a different domain or hostname from the parent page and so is a 
@@ -14,8 +14,6 @@ iframe to interact with the underlying platform APIs.
 
 > **_iframes and 3rd party cookies:_** Since the app is sandboxed in an iframe, and most browsers are now blocking 3rd party cookies, you shouldn't rely on cookies within your app.
 
-#### How to use the Connect JS API
-
 You'll need to include the following in any JS file you wish to have access to the API:
 
 ```
diff --git a/src/content/introduction.md b/src/content/introduction.md
@@ -1,15 +1,17 @@
-### Introduction
+# Introduction
 
 Welcome to the Node.js Connect sample app! This sample app has been built to help you and your team get up-and-running faster
 by providing examples of the key features, functionality and things you'll need to create a
 [Connect](https://developer.atlassian.com/cloud/bitbucket/faqs/#:~:text=Atlassian%20Connect%20is%20a%20distributed,wherever%2C%20whenever%2C%20and%20however)
 app. In this sample app you'll find information about the following:
 
-- **Atlassian Connect JSON**: what it is, an example of an Atlassian Connect JSON file, and a link to where you can get more information
-- **Lifecycle Events**: outline of what lifecycle events are supported, an example of how to use them, and a link to documentation
-- **Connect Modules**: we'll explain how you can use these modules to extend to functionality of the Jira platform or a Jira application
-- **Auth with JWT and Storage**: this section will provide information about the iFrame (where your app will render), verification, and the JWT library
-- **Making Jira API requests**: we'll provide some examples and give you a link to documentation
-- **Connect JS library**: what it is, why you need it
-- **How to list your app in Marketplace**: we'll give you a rundown of how to get your app into our Marketplace
+- [**Atlassian Connect JSON**](/acn-config): what it is, an example of an Atlassian Connect JSON file, and a link to where you can get more information
+- [**Lifecycle Events**](/acn-lifecycle-events): outline of what lifecycle events are supported, an example of how to use them, and a link to documentation
+- [**Webhooks**](/acn-logs-webhooks): you'll get an overview of what needs to be included when working with webhooks and find links on how to register webhooks,
+and what webhooks are available.
+- [**Connect Modules**](/acn-modules): we'll explain how you can use these modules to extend to functionality of the Jira platform or a Jira application
+- [**Auth with JWT and Storage**](/acn-authentication): this section will provide information about the iFrame (where your app will render), verification, and the JWT library
+- [**Making Jira API requests**](/acn-api-requests): we'll provide some examples and give you a link to documentation
+- [**Connect JS library**](/acn-js-library): what it is and why you need it
+- [**How to list your app in Marketplace**](/acn-marketplace): we'll give you a rundown of how to get your app into our Marketplace
 
diff --git a/src/content/lifecycle-events.md b/src/content/lifecycle-events.md
@@ -1,4 +1,4 @@
-### Lifecycle Events
+# Lifecycle Events
 
 As outlined in **Atlassian Connect JSON**, lifecycle events allow an app to register callbacks for events that occur 
 in the lifecycle of an installation. These include:
@@ -12,7 +12,7 @@ in the lifecycle of an installation. These include:
 }
 ```
 
-#### A brief overview of the 4 lifecycle events
+## A brief overview of the 4 lifecycle events
 - `installed`: the installed lifecycle callback is an integral part of the installation process of an app, whereas the 
 remaining lifecycle events are essentially webhooks. This event is triggered when an app is installed or upgraded, 
 you rotate your shared secret, the baseUrl is changed (site rename), or after a site import. This is the only lifecycle
@@ -24,7 +24,7 @@ or upgrade. This event will not be triggered for any other type of installed lif
 
 For more information on lifecycle events, please refer to our [documentation](https://developer.atlassian.com/cloud/jira/platform/connect-app-descriptor/#lifecycle).
 
-#### Validating installation lifecycle requests
+## Validating installation lifecycle requests
 An installation secret will be exchanged every time your app is installed or updated. To secure this key exchange 
 process, the `install` and `uninstall` lifecycle events include JWT tokens in the Authorization header. This JWT token 
 will be signed with a private key using the RS256(RSA-SHA256) algorithm.
@@ -33,4 +33,4 @@ To retrieve the publicKey, make a request to the CDN with the kid parameter supp
 example, `https://connect-install-keys.atlassian.com/kid`
 
 The best way to see how JWT tokens work with your lifecycle events is to use the [Connect inspector](http://go.atlassian.com/connect-inspector) 
-to create a temporary app, install it in your cloud development environment and watch the lifecycle events.
+to create a temporary app, install it in your cloud development environment and watch the lifecycle events.
diff --git a/src/content/marketplace.md b/src/content/marketplace.md
@@ -1,4 +1,4 @@
-### Marketplace
+# Marketplace
 
 Congratulations! You've finished building your app and unleash it into the wild. But before it goes public you'll need to
 ensure you meet our [approval guidelines](https://developer.atlassian.com/platform/marketplace/app-approval-guidelines/).
diff --git a/src/content/modules.md b/src/content/modules.md
@@ -1,4 +1,4 @@
-### Connect Modules for Jira
+# Connect Modules for Jira
 
 As mentioned in our **Introduction**, modules can be used to extend the functionality of the Jira/Confluence platform or a Jira/Confluence 
 application. They are commonly used to extend the user interface by adding links, panels, or pages, or to extend 
@@ -23,9 +23,9 @@ To use a Connect module you can either declare it in your app descriptor e.g.
 or, for some modules, you can register them dynamically using the 
 [REST API](https://developer.atlassian.com/cloud/jira/platform/dynamic-modules).
 
-#### iframes
+## iframes
 
-Atlassian Connect creates an iframe, which it reuses across modules, and passes information to the app using query parameters in 
+Atlassian Connect creates an iframe, which it reuses across modules, and passes information to the app using query parameters in
 the iframe URL. Here is a simplified example of this:
 
 ```
@@ -36,7 +36,7 @@ the iframe URL. Here is a simplified example of this:
 
 Please refer to our documentation for information about [Opting in to cacheable iframes](https://developer.atlassian.com/cloud/confluence/cacheable-app-iframes-for-connect-apps/#opting-in-to-cacheable-iframes).
 
-#### Jira modules
+## Jira modules
 
 For Jira, there are 2 types of modules: 
 - **basic iFrames** these include [location-based modules](https://developer.atlassian.com/cloud/jira/platform/about-connect-modules-for-jira/#location-based-modules), 
@@ -47,15 +47,15 @@ these allow you to extend specific Jira features such as the issue tab panel and
 items.
 
 Please refer to our documentation for more information on [Jira modules](https://developer.atlassian.com/cloud/jira/platform/about-connect-modules-for-jira/.
-
-#### Connect modules
+Connect modules
+## 
 
 Connect modules allow Connect apps to extend the Confluence user interface, create custom Macros or content, handle event 
 listening (webhooks), and even run scripts or other code. For more information, please refer to our 
 [Confluence modules](https://developer.atlassian.com/cloud/confluence/about-connect-modules-for-confluence/#add-modules-to-your-connect-app) 
 documentation.
 
-#### A Module Example
+## A Module Example
 
 One module that you may find valuable is the [Security Information module](https://developer.atlassian.com/cloud/jira/platform/modules/security-information/).
 This module makes it possible to turn unplanned vulnerabilities into planned and tracked work.
diff --git a/src/content/webhooks.md b/src/content/webhooks.md
@@ -1,4 +1,4 @@
-### Webhooks
+# Webhooks
 
 A webhook is an HTTP request, triggered by an event in a source system and sent to a destination system, often with a 
 payload of data. Webhooks are automated, in other words they are automatically sent out when their event is fired in the 
@@ -12,11 +12,13 @@ use the HTTPS protocol. There is a limit of 5 redirects per url.
 - the **scope** of the webhook (optional): for example either "all issues" or a limited set of issues specified by JQL 
 ("project = TEST and fixVersion = future")
 
-#### Registering a webhook
+## Registering a webhook
 Webhooks can be manually created in 
 [Jira administration](https://support.atlassian.com/jira-cloud-administration/docs/manage-webhooks/), via
 [registered by]() `/rest/webhooks/1.0/webhook`, or by declaring a 
 [webhook module](https://developer.atlassian.com/cloud/jira/platform/modules/webhook/) in the app description.
 
 For more information about webhooks, and for a full list of available webhooks, please refer to our
-[documentation](https://developer.atlassian.com/cloud/jira/platform/webhooks/#registering-a-webhook-using-the-jira-rest-api--other-integrations-).
+[documentation](https://developer.atlassian.com/cloud/jira/platform/webhooks/#registering-a-webhook-using-the-jira-rest-api--other-integrations-).
+
+## Example logs:
diff --git a/src/routes/atlassian-connect.ts b/src/routes/atlassian-connect.ts
@@ -178,6 +178,30 @@ export const connectAppDescriptor = {
 				name: {
 					"value": "Creating modules with Connect"
 				}
+			},
+			{
+				url: "/lifecycle-events",
+				key: "acn-lifecycle-events",
+				location: "none",
+				name: {
+					"value": "Lifecycle events"
+				}
+			},
+			{
+				url: "/making-api-requests",
+				key: "acn-api-requests",
+				location: "none",
+				name: {
+					"value": "Making API requests"
+				}
+			},
+			{
+				url: "/marketplace",
+				key: "acn-marketplace",
+				location: "none",
+				name: {
+					"value": "Atlassian Marketplace"
+				}
 			}
 		]
 	}
diff --git a/src/routes/router.ts b/src/routes/router.ts
@@ -1,5 +1,8 @@
 import path from "path";
-import { Router, static as Static } from "express";
+import * as fs from "fs";
+import { Router, static as Static, Request, Response } from "express";
+import sanitizeHtml from "sanitize-html";
+import { marked } from "marked";
 import { connectAppDescriptor, connectDescriptorGet } from "./atlassian-connect";
 import { eventsRouter } from "./events";
 import { webhooksRouter } from "./webhooks";
@@ -23,25 +26,53 @@ RootRouter.use("/events", eventsRouter);
 // Jira webhooks we listen to as specified in the Connect JSON above
 RootRouter.use("/webhooks", webhooksRouter);
 
-// Below are the Connect Module routes which need to pass the JWT check to continue
+const renderer = new marked.Renderer();
+
+renderer.link = (href: string, _, text: string): string => {
+	if (href?.includes("https" || href?.includes("http"))) {
+		return `<a target="_blank" href="${href}">${text}</a>`;
+	} else {
+		const page = href?.substring(1);
+		return `<span class="link-span" id="${page}" data-connect-module-key="${page}">${text}</span>`;
+	}
+};
+
+const getMarkdownAndConvertToHtml = (fileName: string): string => {
+	const filePath = path.join(__dirname, "..", "content", fileName);
+	const contents = fs.readFileSync(filePath);
+	// TODO - see if there's a way to modify the way we are using marked.js so we can pass data directly to HTML elements
+	const markdownToHtml = marked.parse(contents.toString(), { renderer: renderer });
+
+	return sanitizeHtml(markdownToHtml, {
+		allowedAttributes: {
+			span: [ "class", "id", "data-connect-module-key" ],
+			a: [ "href", "target" ]
+		}
+	});
+};
+
 RootRouter.use(connectIframeJWTMiddleware);
 
-RootRouter.get("/", (_req, res) => {
-	res.render("introduction");
+RootRouter.get("/", (_req: Request, res: Response): void => {
+	res.render("introduction", {
+		pageContent: getMarkdownAndConvertToHtml("introduction.md")
+	});
 });
 
-RootRouter.get("/config", async (_req, res) => {
+RootRouter.get("/config", async (_req: Request, res: Response): Promise<void> => {
 	res.render("config", {
-		config: JSON.stringify(connectAppDescriptor, undefined, 2)
+		config: JSON.stringify(connectAppDescriptor, undefined, 2),
+		pageContent: getMarkdownAndConvertToHtml("config.md")
 	});
 });
 
-RootRouter.get("/logs/webhooks", async (_req, res) => {
+RootRouter.get("/logs/webhooks", async (_req: Request, res: Response): Promise<void> => {
 	const clientKey = res.locals.jiraTenant?.clientKey;
 	if (!clientKey) {
 		res.status(404).send("Missing clientKey");
 		return;
 	}
+
 	const tenant = await database.findJiraTenant({ clientKey });
 	const logs = await database.findLogsForJiraTenant(tenant.url);
 
@@ -50,6 +81,7 @@ RootRouter.get("/logs/webhooks", async (_req, res) => {
 			const clonedLog = { ...log };
 			clonedLog.data = JSON.stringify(log.data);
 			return clonedLog;
-		})
+		}),
+		pageContent: getMarkdownAndConvertToHtml("webhooks.md")
 	});
 });
diff --git a/src/views/config.squirrelly b/src/views/config.squirrelly
@@ -7,8 +7,8 @@
     <button class="aui-button" data-connect-module-key="acn-introduction">Home</button>
     <br/>
     <br/>
-    <h3>Atlassian Connect Config:</h3>
-    <hr>
+    <div id="atlassianConnectJson" data-page-content="{{ it.pageContent.toString() }}""></div>
+    <br/>
     <pre class="config-container">{{ it.config }}</pre>
     <br/>
     <br/>
diff --git a/src/views/introduction.squirrelly b/src/views/introduction.squirrelly
diff --git a/src/views/layout.squirrelly b/src/views/layout.squirrelly
diff --git a/src/views/webhook-logs.squirrelly b/src/views/webhook-logs.squirrelly
diff --git a/static/css/main.css b/static/css/main.css
diff --git a/static/js/index.js b/static/js/index.js
diff --git a/yarn.lock b/yarn.lock

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-### Marketplace`
	`1`	`+# Marketplace`
`2`	`2`
`3`	`3`	`Congratulations! You've finished building your app and unleash it into the wild. But before it goes public you'll need to`
`4`	`4`	`ensure you meet our [approval guidelines](https://developer.atlassian.com/platform/marketplace/app-approval-guidelines/).`