Implement tutorials (#476)

* add required npm packages

* implement tutorials

* add tutorial to preview route

* change default tutorials links

* handle not found tutorial case

* fix linter

* use better example tutorial

* small refactor

packages/backend/package.json

@@ -39,14 +39,17 @@
     "@types/node-fetch": "^2.6.2",
     "@types/pg": "^8.6.5",
     "chalk": "^4.1.2",
+    "cheerio": "^1.0.0-rc.12",
     "dotenv": "^16.0.1",
     "ethers": "^5.6.8",
+    "fs-extra": "^11.1.1",
     "knex": "^2.4.0",
     "koa": "^2.13.4",
     "koa-basic-auth": "^4.0.0",
     "koa-bodyparser": "^4.3.0",
     "koa-static": "^5.0.0",
     "lodash": "^4.17.21",
+    "markdown-it": "^13.0.1",
     "node-fetch": "^2.6.7",
     "object-hash": "^3.0.0",
     "pg": "^8.7.3",
@@ -56,7 +59,10 @@
   },
   "devDependencies": {
     "@sinonjs/fake-timers": "^9.1.2",
+    "@tailwindcss/typography": "^0.5.9",
+    "@types/fs-extra": "^11.0.1",
     "@types/koa-basic-auth": "^2.0.4",
+    "@types/markdown-it": "^13.0.0",
     "@types/object-hash": "^2.2.1",
     "@types/supertest": "^2.0.12",
     "supertest": "^6.2.3",

packages/backend/src/Application.ts

@@ -13,6 +13,7 @@ import { SearchController } from './api/controllers/SearchController'
 import { StateUpdateController } from './api/controllers/StateUpdateController'
 import { TransactionController } from './api/controllers/TransactionController'
 import { TransactionSubmitController } from './api/controllers/TransactionSubmitController'
+import { TutorialController } from './api/controllers/TutorialController'
 import { UserController } from './api/controllers/UserController'
 import { frontendErrorMiddleware } from './api/middleware/frontendErrorMiddleware'
 import { createFrontendMiddleware } from './api/middleware/FrontendMiddleware'
@@ -679,6 +680,8 @@ export class Application {
       config.starkex.contracts.perpetual
     )
 
+    const tutorialController = new TutorialController(pageContextService)
+
     const apiServer = new ApiServer(config.port, logger, {
       routers: [
         createStatusRouter(statusService),
@@ -693,6 +696,7 @@ export class Application {
           searchController,
           l2TransactionController,
           escapeHatchController,
+          tutorialController,
           config
         ),
         createTransactionRouter(

packages/backend/src/api/controllers/TutorialController.ts

@@ -0,0 +1,40 @@
+import { renderTutorialPage } from '@explorer/frontend'
+import { UserDetails } from '@explorer/shared'
+
+import { PageContextService } from '../../core/PageContextService'
+import { getHtmlFromMarkdown } from '../../utils/markdown/getHtmlFromMarkdown'
+import { ControllerResult } from './ControllerResult'
+
+export class TutorialController {
+  constructor(private readonly pageContextService: PageContextService) {}
+
+  async getTutorialPage(
+    givenUser: Partial<UserDetails>,
+    slug: string
+  ): Promise<ControllerResult> {
+    const context = await this.pageContextService.getPageContext(givenUser)
+    let articleContent: string
+    try {
+      const path = this.getTutorialPath(slug)
+      articleContent = getHtmlFromMarkdown(path)
+    } catch {
+      return {
+        type: 'not found',
+        message: 'The tutorial you were looking for does not exist',
+      }
+    }
+
+    return {
+      type: 'success',
+      content: renderTutorialPage({
+        context,
+        articleContent: articleContent,
+        slug,
+      }),
+    }
+  }
+
+  private getTutorialPath(slug: string): string {
+    return `src/content/tutorials/${slug}.md`
+  }
+}

packages/backend/src/api/routers/FrontendRouter.ts

@@ -13,6 +13,7 @@ import { MerkleProofController } from '../controllers/MerkleProofController'
 import { SearchController } from '../controllers/SearchController'
 import { StateUpdateController } from '../controllers/StateUpdateController'
 import { TransactionController } from '../controllers/TransactionController'
+import { TutorialController } from '../controllers/TutorialController'
 import { UserController } from '../controllers/UserController'
 import { addPerpetualTradingRoutes } from './PerpetualFrontendRouter'
 import { addSpotTradingRoutes } from './SpotFrontendRouter'
@@ -30,6 +31,7 @@ export function createFrontendRouter(
   searchController: SearchController,
   l2TransactionController: L2TransactionController,
   escapeHatchController: EscapeHatchController,
+  tutorialController: TutorialController,
   config: Config
 ) {
   const router = new Router()
@@ -472,6 +474,25 @@ export function createFrontendRouter(
     )
   }
 
+  router.get(
+    '/tutorials/:slug',
+    withTypedContext(
+      z.object({
+        params: z.object({
+          slug: z.string(),
+        }),
+      }),
+      async (ctx) => {
+        const givenUser = getGivenUser(ctx)
+        const result = await tutorialController.getTutorialPage(
+          givenUser,
+          ctx.params.slug
+        )
+        applyControllerResult(ctx, result)
+      }
+    )
+  )
+
   if (config.starkex.tradingMode === 'perpetual') {
     if (!forcedTradeOfferController) {
       throw new Error(

packages/backend/src/content/tutorials/example.md

@@ -0,0 +1,112 @@
+<!-- THIS FILE SHOULD BE DELETED AS SOON AS WE ADD REAL TUTORIALS -->
+
+# h1 Heading
+
+## h2 Heading
+
+### h3 Heading
+
+#### h4 Heading
+
+##### h5 Heading
+
+###### h6 Heading
+
+## Horizontal Rules
+
+---
+
+---
+
+---
+
+## Emphasis
+
+**This is bold text**
+
+**This is bold text**
+
+_This is italic text_
+
+_This is italic text_
+
+~~Strikethrough~~
+
+## Blockquotes
+
+> Blockquotes can also be nested...
+>
+> > ...by using additional greater-than signs right next to each other...
+> >
+> > > ...or with spaces between arrows.
+
+## Lists
+
+Unordered
+
+- Create a list by starting a line with `+`, `-`, or `*`
+- Sub-lists are made by indenting 2 spaces:
+  - Marker character change forces new list start:
+    - Ac tristique libero volutpat at
+    * Facilisis in pretium nisl aliquet
+    - Nulla volutpat aliquam velit
+- Very easy!
+
+Ordered
+
+1. Lorem ipsum dolor sit amet
+2. Consectetur adipiscing elit
+3. Integer molestie lorem at massa
+
+4. You can use sequential numbers...
+5. ...or keep all the numbers as `1.`
+
+Start numbering with offset:
+
+57. foo
+1. bar
+
+## Code
+
+Inline `code`
+
+Indented code
+
+    // Some comments
+    line 1 of code
+    line 2 of code
+    line 3 of code
+
+Block code "fences"
+
+```
+Sample text here...
+```
+
+## Tables
+
+| Option | Description                                                               |
+| ------ | ------------------------------------------------------------------------- |
+| data   | path to data files to supply the data that will be passed into templates. |
+| engine | engine to be used for processing templates. Handlebars is the default.    |
+| ext    | extension to be used for dest files.                                      |
+
+Right aligned columns
+
+| Option |                                                               Description |
+| -----: | ------------------------------------------------------------------------: |
+|   data | path to data files to supply the data that will be passed into templates. |
+| engine |    engine to be used for processing templates. Handlebars is the default. |
+|    ext |                                      extension to be used for dest files. |
+
+## Links
+
+[link text](http://dev.nodeca.com)
+
+[link with title](http://nodeca.github.io/pica/demo/ 'title text!')
+
+Autoconverted link https://github.com/nodeca/pica (enable linkify to see)
+
+## Images
+
+![Minion](https://octodex.github.com/images/minion.png)

packages/backend/src/utils/markdown/getHtmlFromMarkdown.ts

@@ -0,0 +1,40 @@
+import { Cheerio, Element, load } from 'cheerio'
+import fsx from 'fs-extra'
+import MarkdownIt from 'markdown-it'
+
+import { renderHeading } from './renderHeading'
+
+export function getHtmlFromMarkdown(filePath: string) {
+  const markdown = MarkdownIt({ html: true })
+  const file = fsx.readFileSync(filePath, 'utf-8')
+  const rendered = markdown.render(file)
+  const $ = load(rendered)
+  $('a').each(function () {
+    const $el = $(this)
+    $el.attr('rel', 'noopener noreferrer')
+    $el.attr('target', '_blank')
+  })
+  $('h1, h2, h3, h4, h5, h6').each(function () {
+    const $el = $(this)
+    const html = renderHeading(
+      //eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      parseInt(this.tagName[1]!),
+      $el.html(),
+      getId($el)
+    )
+    $el.replaceWith($(html))
+  })
+  return $('body').html() ?? ''
+}
+
+function getId($el: Cheerio<Element>) {
+  return (
+    $el.attr('id') ??
+    $el
+      .text()
+      .toLowerCase()
+      .replace(/[^a-z\d]/g, '-')
+      .replace(/-+/g, '-')
+      .replace(/^-+|-+$/g, '')
+  )
+}

packages/backend/src/utils/markdown/renderHeading.tsx

@@ -0,0 +1,29 @@
+import React, { createElement, HTMLAttributes } from 'react'
+import { renderToStaticMarkup } from 'react-dom/server'
+
+export function renderHeading(
+  level: number,
+  content: string | null,
+  id: string
+) {
+  if (content === null) {
+    return
+  }
+
+  return renderToStaticMarkup(
+    <Hx level={level} id={id}>
+      <a
+        className="Heading-Title"
+        href={`#${id}`}
+        dangerouslySetInnerHTML={{ __html: content }}
+      />
+    </Hx>
+  )
+}
+
+function Hx({
+  level,
+  ...props
+}: HTMLAttributes<HTMLHeadingElement> & { level: number }) {
+  return createElement(`h${level}`, props)
+}