feat(doc): switch to @kong/markdown TDX-4186 (#546)

Co-authored-by: henri pietila <[email protected]>

cypress/e2e/specs/api_documentation.spec.ts

@@ -1,16 +1,24 @@
 import { product, productVersion } from '../fixtures/consts'
 import childrenApiDocumentationJSON from '../fixtures/dochub_mocks/childrenApiDocumentation.json'
 import documentTreeJSON from '../fixtures/dochub_mocks/documentTree.json'
-
+import { FeatureFlags } from '@/constants/feature-flags'
 describe('Api Documentation Page', () => {
   beforeEach(() => {
     product.document_count = 1
-    cy.mockPrivatePortal()
-    cy.mockProduct(product.id, product)
-    cy.mockGetProductDocumentBySlug(product.id, 'bar')
-    cy.mockGetProductDocuments(product.id)
-    cy.mockProductOperations()
-    cy.mockStylesheetFont()
+
+    cy.mockLaunchDarklyFlags([
+      {
+        name: FeatureFlags.newMarkdownRender,
+        value: false
+      }
+    ]).then(() => {
+      cy.mockPrivatePortal()
+      cy.mockProduct(product.id, product)
+      cy.mockGetProductDocumentBySlug(product.id, 'bar')
+      cy.mockGetProductDocuments(product.id)
+      cy.mockProductOperations()
+      cy.mockStylesheetFont()
+    })
   })
 
   const PARENT_DOCUMENT_URL = `/docs/${product.id}/${documentTreeJSON[0].slug}`

package.json

@@ -35,6 +35,7 @@
     "@kong-ui-public/spec-renderer": "2.2.20",
     "@kong/kong-auth-elements": "2.12.6",
     "@kong/kongponents": "8.127.0",
+    "@kong/markdown": "1.7.8",
     "@kong/sdk-portal-js": "2.14.0",
     "@xstate/vue": "2.0.0",
     "axios": "1.6.7",

src/constants/feature-flags.ts

@@ -1,2 +1,3 @@
 export enum FeatureFlags {
+  newMarkdownRender = 'tdx-4186-new-markdown',
 }

src/views/ApiDocumentationPage.vue

@@ -37,12 +37,20 @@
           :description="helpText.apiDocumentation.error.description"
           :link-text="helpText.apiDocumentation.error.linkText"
         />
+
         <DocumentViewer
-          v-else-if="content"
+          v-if="content && !newMarkdownRenderEnabled"
           data-testid="portal-document-viewer"
           class="portal-document-viewer"
           :document="content"
         />
+
+        <MarkdownUi
+          v-else-if="markdown && newMarkdownRenderEnabled"
+          v-model="markdown"
+          class="documentation-display portal-document-viewer"
+          theme="light"
+        />
       </template>
     </div>
     <aside class="col sidebar sidebar-sections">
@@ -70,13 +78,17 @@ import { findAllNodesOfType, getNodeTextContent } from '@/helpers/document'
 import { ProductWithVersions, useI18nStore, useProductStore } from '@/stores'
 import useToaster from '@/composables/useToaster'
 import DocumentViewer, { HeadingNode, addSlug } from '@kong-ui-public/document-viewer'
-
 import '@kong-ui-public/document-viewer/dist/style.css'
+import { MarkdownUi } from '@kong/markdown'
+import '@kong/markdown/dist/style.css'
 import { DocumentBlock, ProductDocument } from '@kong/sdk-portal-js'
+import useLDFeatureFlag from '@/hooks/useLDFeatureFlag'
+import { FeatureFlags } from '@/constants/feature-flags'
 
 export default defineComponent({
   name: 'ApiDocumentationPage',
   components: {
+    MarkdownUi,
     DocumentViewer,
     DocumentSections,
     ErrorWrapper
@@ -96,6 +108,7 @@ export default defineComponent({
     const errorCode = ref(null)
     const router = useRouter()
     const { portalApiV2 } = usePortalApi()
+    const documentationDisplay = ref()
 
     const breadcrumbs = computed(() => ([
       {
@@ -131,7 +144,9 @@ export default defineComponent({
 
     const title = ref<string>(null)
     const isDocumentLoading = ref<boolean>(true)
+    const markdown = ref<string>(null)
     const content = ref<DocumentBlock>(null)
+    const newMarkdownRenderEnabled = useLDFeatureFlag(FeatureFlags.newMarkdownRender, false)
 
     const sections = computed(() => {
       if (!content.value) {
@@ -146,7 +161,7 @@ export default defineComponent({
       return allHeadings
         .map((node) => {
           const text = getNodeTextContent(node)
-          const { slug } = addSlug(node, slugMap)
+          const { slug } = addSlug(node, slugMap, newMarkdownRenderEnabled.value ? '' : undefined)
           const level = getMaxHeaderLevel(2)
 
           return {
@@ -165,7 +180,15 @@ export default defineComponent({
       errorCode.value = null
       isDocumentLoading.value = true
 
-      await portalApiV2.value.service.documentationApi.getProductDocument({
+      const getMarkdown = portalApiV2.value.service.documentationApi.getProductDocument({
+        productId,
+        documentId: slug
+      })
+        .then((res) => {
+          markdown.value = res.data.content
+        })
+
+      const getDocumentNodes = portalApiV2.value.service.documentationApi.getProductDocument({
         productId,
         documentId: slug
       }, {
@@ -180,9 +203,10 @@ export default defineComponent({
           content.value = data.content
           productStore.setActiveDocumentId(data.id)
         })
-        .finally(() => {
-          isDocumentLoading.value = false
-        })
+
+      await Promise.all([getMarkdown, getDocumentNodes]).finally(() => {
+        isDocumentLoading.value = false
+      })
     }
 
     const handleError = (error) => {
@@ -216,12 +240,15 @@ export default defineComponent({
       helpText,
       title,
       content,
+      markdown,
       isDocumentLoading,
       sections,
       breadcrumbs,
       document,
       errorCode,
-      slug: activeDocumentSlug.value
+      slug: activeDocumentSlug.value,
+      documentationDisplay,
+      newMarkdownRenderEnabled
     }
   }
 })
@@ -316,4 +343,13 @@ export default defineComponent({
     }
   }
 }
+
+.documentation-display {
+   --kui-color-background: var(--section_colors-body);
+   --kui-font-family-text: var(--font-family-sans);
+   --kui-color-text: var(--text_colors-primary);
+   --kui-color-text-primary: var(--text_colors-link);
+   --kui-color-text-primary-stronger: var(--text_colors-accent);
+   --kui-color-background-neutral-weaker: var(--section_colors-accent);
+}
 </style>