feat: when inlining guidebook snippets, rewrite relative image links

Also updates the iter8 tutorial1.md to pull the content from iter8
Also adds support for renaming wizard steps in wizard topmatter

Author: starpit

plugins/plugin-client-common/src/components/Content/Markdown/KuiFrontmatter.ts

@@ -25,7 +25,7 @@ export interface WizardSteps {
      * heading in the markdown source. Optionally, a step description
      * may be overlaid
      */
-    steps: (string | { name: string; description: string })[]
+    steps: (string | { match?: string; name: string; description: string })[]
   }
 }
 

plugins/plugin-client-common/src/components/Content/Markdown/components/code/remark-codeblocks-topmatter.ts

@@ -28,7 +28,9 @@ function isCode(node: Node): node is Code {
 /** Scan and process the `codeblocks` schema of the given `frontmatter` */
 export default function preprocessCodeBlocks(tree /*: Root */, frontmatter: KuiFrontmatter) {
   if (hasCodeBlocks(frontmatter)) {
-    const codeblocks = frontmatter.codeblocks.map(_ => Object.assign({}, _, { match: new RegExp(_.match) }))
+    const codeblocks = frontmatter.codeblocks.map(_ =>
+      Object.assign({}, _, { match: new RegExp(_.match.replace(/\./g, '\\.')) })
+    )
 
     visit(tree, 'code', node => {
       if (isCode(node)) {

plugins/plugin-client-common/src/components/Content/Markdown/frontmatter.tsx

@@ -40,6 +40,11 @@ export function tryFrontmatter(
   }
 }
 
+/** In case you only want the body part of a `markdownText` */
+export function stripFrontmatter(markdownText: string) {
+  return tryFrontmatter(markdownText).body
+}
+
 export function splitTarget(node) {
   if (node.type === 'raw') {
     const match = node.value.match(/<!-- ____KUI__SECTION_START____ (.*)/)
@@ -88,6 +93,15 @@ function preprocessWizardSteps(tree: Root, frontmatter: KuiFrontmatter) {
       frontmatter.layout = 'wizard'
     }
 
+    // since the user defined wizard steps in the topmatter, we need
+    // to remove existing thematicBreaks, for now
+    visitParents(tree, 'thematicBreak', (node, ancestors) => {
+      const parent = ancestors[ancestors.length - 1]
+      const childIdx = parent.children.findIndex(_ => _ === node)
+
+      parent.children.splice(childIdx, 1)
+    })
+
     let nth = 0
     visitParents<Heading>(tree, 'heading', (node, ancestors) => {
       if (ancestors.length > 0 && node.children && node.children[0]) {
@@ -98,7 +112,11 @@ function preprocessWizardSteps(tree: Root, frontmatter: KuiFrontmatter) {
           const childIdx = parent.children.findIndex(_ => _ === node)
 
           const matchingStep = frontmatter.wizard.steps.find(step =>
-            typeof step === 'string' ? step === firstChild.value : step.name === firstChild.value
+            typeof step === 'string'
+              ? step === firstChild.value
+              : step.match
+              ? new RegExp(step.match.replace(/\./g, '\\.')).test(firstChild.value)
+              : step.name === firstChild.value
           )
 
           const headingIdx = nth++
@@ -107,12 +125,14 @@ function preprocessWizardSteps(tree: Root, frontmatter: KuiFrontmatter) {
               if (parent.children[childIdx - 1].type !== 'thematicBreak') {
                 // splice in a ---, which below we use to indicate steps
                 parent.children.splice(childIdx, 0, u('thematicBreak'))
+              }
 
-                // splice in a description? below, this will be parsed
-                // out as Title: Description
-                if (typeof matchingStep !== 'string' && matchingStep.description) {
-                  firstChild.value = firstChild.value + ': ' + matchingStep.description
-                }
+              // splice in a description? below, this will be parsed
+              // out as Title: Description
+              if (typeof matchingStep !== 'string') {
+                firstChild.value =
+                  (matchingStep.name || firstChild.value) +
+                  (matchingStep.description ? ': ' + matchingStep.description : '')
               }
             }
           } else if (childIdx >= 0 && headingIdx === 0 && frontmatter.wizard.description) {

plugins/plugin-client-common/src/controller/snippets.ts

@@ -15,10 +15,12 @@
  */
 
 import Debug from 'debug'
-import { isAbsolute as pathIsAbsolute, join as pathJoin } from 'path'
+import { isAbsolute as pathIsAbsolute, dirname as pathDirname, join as pathJoin } from 'path'
 import { Arguments } from '@kui-shell/core'
 import { loadNotebook } from '@kui-shell/plugin-client-common/notebook'
 
+import { stripFrontmatter } from '../components/Content/Markdown/frontmatter'
+
 const debug = Debug('plugin-client-common/markdown/snippets')
 
 const RE_SNIPPET = /^--(-*)8<--(-*)\s+"([^"]+)"(\s+"([^"]+)")?$/
@@ -27,6 +29,16 @@ function isUrl(a: string) {
   return /^https?:/.test(a)
 }
 
+function dirname(a: string) {
+  if (isUrl(a)) {
+    const url = new URL(a)
+    url.pathname = pathDirname(url.pathname)
+    return url.toString()
+  } else {
+    return pathDirname(a)
+  }
+}
+
 function join(a: string, b: string) {
   if (isUrl(a)) {
     const url = new URL(a)
@@ -45,6 +57,14 @@ function toString(data: string | object) {
   return typeof data === 'string' ? data : JSON.stringify(data)
 }
 
+/** Rewrite any relative image links to use the given basePath */
+function rerouteImageLinks(basePath: string, data: string) {
+  return data.replace(
+    /\[(.+)\]\((.+)\)/g, // e.g. [linky](https://linky.com)
+    (_, p1, p2) => `[${p1}](${join(basePath, p2)})`
+  )
+}
+
 /**
  * Simplistic approximation of
  * https://facelessuser.github.io/pymdown-extensions/extensions/snippets/.
@@ -65,6 +85,13 @@ export default function inlineSnippets(snippetBasePath?: string) {
             return isAbsolute(basePath) ? basePath : srcFilePath ? join(srcFilePath, basePath) : undefined
           }
 
+          // Call ourselves recursively, in case a fetched snippet
+          // fetches other files. We also may need to reroute relative
+          // image links according to the given `basePath`.
+          const recurse = (basePath: string, data: string) => {
+            return inlineSnippets(basePath)(rerouteImageLinks(basePath, toString(data)), snippetFileName, args)
+          }
+
           const candidates = match[5]
             ? [match[5]]
             : snippetBasePath
@@ -73,7 +100,7 @@ export default function inlineSnippets(snippetBasePath?: string) {
 
           const snippetData = isUrl(snippetFileName)
             ? await loadNotebook(snippetFileName, args)
-                .then(data => inlineSnippets(snippetBasePath)(toString(data), snippetFileName, args))
+                .then(data => recurse(snippetBasePath || dirname(snippetFileName), toString(data)))
                 .catch(err => {
                   debug('Warning: could not fetch inlined content', snippetFileName, err)
                   return ''
@@ -85,7 +112,7 @@ export default function inlineSnippets(snippetBasePath?: string) {
                     .filter(Boolean)
                     .map(mySnippetBasePath =>
                       loadNotebook(join(mySnippetBasePath, snippetFileName), args)
-                        .then(data => inlineSnippets(mySnippetBasePath)(toString(data), snippetFileName, args))
+                        .then(data => recurse(mySnippetBasePath, toString(data)))
                         .catch(err => {
                           debug('Warning: could not fetch inlined content', mySnippetBasePath, err)
                           return ''
@@ -98,7 +125,10 @@ export default function inlineSnippets(snippetBasePath?: string) {
             return line
           } else {
             debug('successfully fetched inlined content')
-            return toString(snippetData)
+
+            // for now, we completely strip off the topmatter from
+            // snippets. TODO?
+            return stripFrontmatter(toString(snippetData))
           }
         }
       })

plugins/plugin-client-common/src/test/core/wizards-in-markdown.ts

@@ -62,7 +62,7 @@ const IN3 = {
   description: 'WizardDescriptionInTopmatter',
   expectedSplitCount: 1,
   steps: [
-    { name: 'Before you begin', body: 'Before you can get started', description: '', codeBlocks: [] },
+    { name: 'TestRewritingOfStepName', body: 'Before you can get started', description: '', codeBlocks: [] },
     { name: 'Prepare local Kubernetes cluster', body: 'You can use', description: 'TestDescription2', codeBlocks: [] }
   ]
 }

plugins/plugin-client-common/tests/data/wizard-steps-in-topmatter.md

@@ -2,7 +2,8 @@
 wizard:
     description: WizardDescriptionInTopmatter
     steps:
-        - Before you begin
+        - match: Before you begin
+          name: TestRewritingOfStepName
         - name: Prepare local Kubernetes cluster
           description: TestDescription2
         - Install the Kubernetes CLI

plugins/plugin-iter8/notebooks/tutorial1.md

@@ -1,6 +1,28 @@
 ---
 title: Iter8 — Getting Started
-layout: wizard
+wizard:
+    steps:
+        - Introduction
+        - match: 1. Install Iter8
+          name: Install the CLI
+          description: The iter8 CLI gives you an easy way to manage your experiments
+        - match: 2. Download experiment chart
+          name: Download experiment
+          description: You may craft an experiment by hand, or, as we do here, you may use iter8 to download a previously constructed experiment definition
+        - match: 3. Run experiment
+          name: Run experiment
+          description: Run load against the application, and monitor error rate and response time
+        - match: 4. Assert outcomes
+          name: Assert outcomes
+codeblocks:
+    - match: brew install iter8
+      validate: iter8 -v
+    - match: go install
+      validate: ${GOPATH-~/go}/bin go -v
+    - match: iter8 hub -e load-test
+      validate: "[[ -f /tmp/load-test/values.yaml ]] && [[ -f /tmp/load-test/Chart.yaml ]] || exit 1"
+    - match: iter8 run
+      validate: "[[ -f /tmp/load-test/experiment/values.yaml ]] || exit 1"
 ---
 
 # Iter8: Kubernetes Release Engineering
@@ -13,8 +35,6 @@ release velocity and business value with their apps/ML models while
 protecting end-user experience. Use Iter8 for SLO validation, A/B
 testing and progressive rollouts of K8s apps/ML models.
 
----
-
 ## Introduction
 
 This tutorial uses an [Iter8 experiment](concepts.md#what-is-an-iter8-experiment) to load test https://example.com and validate latency and error-related service level objectives (SLOs).
@@ -23,130 +43,4 @@ This tutorial uses an [Iter8 experiment](concepts.md#what-is-an-iter8-experiment
 >
 > An Iter8 experiment is a sequence of tasks that produce metrics-driven insights for your app/ML model versions, validates them, and optionally performs a rollout. Iter8 provides a set of pre-defined and customizable tasks.
 
----
-
-## Install the CLI: The iter8 CLI gives you an easy way to manage your experiments
-
-=== "Mac"
-
-    On macOS, [Homebrew](https://brew.sh) makes it easy to install the `iter8` CLI.
-
-    ```shell
-    ---
-    id: install-iter8-cli
-    validate: brew info iter8
-    ---
-    brew tap iter8-tools/iter8
-    brew install iter8
-    ```
-    
-=== "Go 1.16+"
-    Install Iter8 using [Go 1.16+](https://golang.org/) as follows.
-
-    ```shell
-    ---
-    id: install-iter8-cli
-    before: export PATH=~/${GOPATH-~/go}/bin:$PATH
-    validate: iter8 -v
-    ---
-    go install github.com/iter8-tools/iter8@latest
-    ```
-
-=== "Binaries"
-    Pre-compiled Iter8 binaries for many platforms are available [here](https://github.com/iter8-tools/iter8/releases). Uncompress the iter8-X-Y.tar.gz archive for your platform, and move the iter8 binary to any folder in your PATH.
-
----
-
-## Download experiment: You may craft an experiment by hand, or, as we do here, you may use iter8 to download a previously constructed experiment definition
-
-Download the `load-test` experiment folder from [Iter8 hub](../user-guide/topics/iter8hub.md) as follows.
-
-```shell
----
-id: download-load-test
-validate: "[[ -f /tmp/load-test/values.yaml ]] && [[ -f /tmp/load-test/Chart.yaml ]] || exit 1"
-status: done
----
-cd /tmp && iter8 hub -e load-test
-```
-
----
-
-## Run experiment: Run load against the application, and monitor error rate and response time
-
-[Iter8 experiments](concepts.md#what-is-an-iter8-experiment) are specified using the `experiment.yaml` file. The `iter8 run` command reads this file, runs the specified experiment, and writes the results of the experiment into the `result.yaml` file.
-
-Run the experiment you downloaded above as follows.
-
-```shell
----
-id: run-experiment
-validate: "[[ -f /tmp/load-test/experiment/values.yaml ]] || exit 1"
----
-cd /tmp/load-test && iter8 run --set url=https://example.com
-```
-
-??? note "Look inside experiment.yaml"
-
-    This experiment contains the [`gen-load-and-collect-metrics` task](../user-guide/tasks/collect.md) for generating load and collecting metrics, and the [`assess-app-versions` task](../user-guide/tasks/assess.md) for validating SLOs.
-
-    ```yaml
-    # task 1: generate HTTP requests for https://example.com and
-    # collect Iter8's built-in latency and error-related metrics
-    - task: gen-load-and-collect-metrics
-      with:
-        versionInfo:
-        - url: https://example.com
-    # task 2: validate if the app (hosted at https://example.com) satisfies 
-    # service level objectives (SLOs)
-    # this task uses the built-in metrics collected by task 1 for validation
-    - task: assess-app-versions
-      with:
-        SLOs:
-          # error rate must be 0
-        - metric: built-in/error-rate
-          upperLimit: 0
-          # 95th percentile latency must be under 100 msec
-        - metric: built-in/p95.0
-          upperLimit: 100
-    ```
-
-??? note "Iter8 and Helm"
-
-    If you are familiar with Helm, you probably noticed that the load-test folder resembles a Helm chart. This is because, Iter8 experiment charts are Helm charts under the covers. The iter8 run command used above combines the experiment chart with values to generate the experiments.yaml file, much like how Helm charts can be combined with values to produce Kubernetes manifests.
-
-## Assert outcomes
-
-Assert that the experiment completed without any failures and SLOs are satisfied
-
-```shell
----
-id: assert-success
----
-cd /tmp/load-test && iter8 assert -c completed -c nofailure -c slos
-```
-
-## Generate report
-
-Generate a report of the experiment in HTML or text formats as follows.
-
-=== "HTML"
-
-    ```shell
-    iter8 report -o html > report.html
-    # open report.html with a browser. In MacOS, you can use the command:
-    # open report.html
-    ```
-
-    ???+ note "The HTML report looks as follows"
-
-        ![HTML report](https://iter8.tools/0.8/getting-started/images/report.html.png)
-
-=== "Text"
-
-    ```shell
-    ---
-    id: generate-text-report
-    ---
-    cd /tmp/load-test && iter8 report -o text
-    ```
+--8<-- "https://raw.githubusercontent.com/iter8-tools/iter8/master/mkdocs/docs/getting-started/your-first-experiment.md"