feat(remark): migrate remark plugins to TS support

packages/tools/docs-tools/package.json

@@ -27,16 +27,23 @@
     "@kadena-dev/eslint-config": "workspace:^",
     "@kadena-dev/lint-package": "workspace:^",
     "@kadena-dev/shared-config": "workspace:^",
-    "@types/mdast": "^4.0.1",
-    "@types/node": "^18.17.14",
-    "@types/unist": "^3.0.1",
-    "eslint": "^8.48.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/mdast": "^4.0.3",
+    "@types/node": "^20.9.0",
+    "@types/react": "^18.2.15",
+    "@types/unist": "^3.0.2",
+    "acorn": "~8.8.2",
+    "date-fns": "~2.30.0",
+    "eslint": "^8.53.0",
+    "js-yaml": "~4.1.0",
     "mdast": "^3.0.0",
     "prettier": "~3.0.3",
-    "typescript": "5.2.2"
+    "react": "^18.2.0",
+    "typescript": "^5.2.2",
+    "unified": "^11.0.4"
   },
   "dependencies": {
-    "mdast-util-to-string": "~3.2.0",
+    "mdast-util-to-string": "~4.0.0",
     "remark-gfm": "^4.0.0"
   }
 }

packages/tools/docs-tools/src/data/authors.json

@@ -0,0 +1,176 @@
+[
+  {
+    "id": "stuart.popejoy",
+    "name": "Stuart Popejoy",
+    "avatar": "/assets/blog/author/stuart.popejoy.jpg",
+    "description": "Founder & CEO",
+    "twitter": "SirLensALot"
+  },
+  {
+    "id": "will.martino",
+    "name": "Will Martino",
+    "avatar": "/assets/blog/author/will.martino.jpg",
+    "description": "Founder & President",
+    "twitter": "_wjmartino_"
+  },
+  {
+    "id": "doug.beardsley",
+    "name": "Doug Beardsley",
+    "avatar": "/assets/blog/author/doug.beardsley.jpg",
+    "description": "Director of Engineering",
+    "twitter": "BlockchainDoug"
+  },
+  {
+    "id": "albert.g",
+    "name": "Albert Groothedde",
+    "avatar": "/assets/blog/author/albert.groothedde.jpg",
+    "description": "Architect DevEx at Kadena",
+    "twitter": "alber70g"
+  },
+  {
+    "id": "vivienne.chen",
+    "name": "Vivienne Chen",
+    "avatar": "/assets/blog/author/vivienne.chen.jpg",
+    "twitter": "ViviennexChen"
+  },
+  {
+    "id": "john.wiegley",
+    "name": "John Wiegley",
+    "avatar": "/assets/blog/author/john.wiegley.jpg",
+    "description": "Chief Technology Officer",
+    "twitter": "jwiegley"
+  },
+  {
+    "id": "leah.bingham",
+    "name": "Leah Bingham",
+    "avatar": "/assets/blog/author/leah.bingham.jpg"
+  },
+  {
+    "id": "linda.ortega",
+    "name": "Linda Ortega",
+    "avatar": "/assets/blog/author/linda.ortega.jpg",
+    "twitter": "linda_ioc"
+  },
+  {
+    "id": "dan.wiggins",
+    "name": "Dan Wiggins",
+    "avatar": "/assets/blog/author/dan.wiggins.jpg"
+  },
+  {
+    "id": "monica.quaintance",
+    "name": "Monica Quaintance",
+    "avatar": "/assets/blog/author/monica.quaintance.jpg",
+    "twitter": "QuaintM"
+  },
+  {
+    "id": "tyler.benster",
+    "name": "Tyler Benster",
+    "avatar": "/assets/blog/author/tyler.benster.jpg"
+  },
+  {
+    "id": "ben.jessel",
+    "name": "Ben Jessel",
+    "avatar": "/assets/blog/author/ben.jessel.jpg"
+  },
+  {
+    "id": "marie.leaf",
+    "name": "Marie Leaf",
+    "avatar": "/assets/blog/author/marie.leaf.jpg"
+  },
+  {
+    "id": "anagha.mercado",
+    "name": "Anagha Mercado",
+    "avatar": "/assets/blog/author/anagha.mercado.jpg"
+  },
+  {
+    "id": "miguel.angel",
+    "name": "Miguel Angel Romero Jr.",
+    "avatar": "/assets/blog/author/miguel.angel.romero.png"
+  },
+  {
+    "id": "rebecca.rodriguez",
+    "name": "Rebecca Rodriguez",
+    "avatar": "/assets/blog/author/rebecca.rodriguez.jpg"
+  },
+  {
+    "id": "tony.pham",
+    "name": "Tony Pham",
+    "avatar": "/assets/blog/author/tony.pham.jpg"
+  },
+  {
+    "id": "taylor.rolfe",
+    "name": "Taylor Rolfe",
+    "avatar": "/assets/blog/author/taylor.rolfe.jpg"
+  },
+  {
+    "id": "francesco.melpignano",
+    "name": "Francesco Melpignano",
+    "avatar": "/assets/blog/author/francesco.melpignano.jpg",
+    "twitter": "fmelp"
+  },
+  {
+    "id": "andy",
+    "name": "Andy",
+    "avatar": "/assets/blog/author/andy.tang.jpg",
+    "description": "Frontend developer",
+    "twitter": "andortang"
+  },
+  {
+    "id": "jermaine.jong",
+    "name": "Jermaine Jong",
+    "avatar": "/assets/blog/author/jermaine.jong.png",
+    "description": "Frontend developer"
+  },
+  {
+    "id": "randy.daal",
+    "name": "Randy Daal",
+    "avatar": "/assets/blog/author/randy.daal.jpg",
+    "description": "Chief Experience Officer @kadena_io",
+    "twitter": "Randynamic_4"
+  },
+  {
+    "id": "jose.cardona",
+    "name": "Jose Cardona",
+    "avatar": "/assets/blog/author/jose.cardona.jpg",
+    "twitter": "JM0x5C"
+  },
+  {
+    "id": "kadena",
+    "name": "Kadena",
+    "avatar": "/assets/blog/author/kadena.png",
+    "description": "The only layer 1 PoW blockchain that scales.",
+    "twitter": "kadena_io"
+  },
+  {
+    "id": "heekyun",
+    "name": "Heekyun",
+    "avatar": "/assets/blog/author/hee.kyun.yun.jpg",
+    "description": "Dev Experience @kadena_io PactJS and Pact Smart Contract Lead",
+    "twitter": "HeeKyunYun1"
+  },
+  {
+    "id": "robert.soeldner",
+    "name": "Robert Soeldner",
+    "avatar": "/assets/blog/author/robert.soeldner.jpeg",
+    "description": "Software Engineer"
+  },
+  {
+    "id": "emily.pillmore",
+    "name": "Emily Pillmore",
+    "avatar": "/assets/blog/author/emily.pillmore.jpg",
+    "description": "M L E that's me",
+    "twitter": "yandereidiot"
+  },
+  {
+    "id": "ryan.levy",
+    "name": "Ryan Levy",
+    "avatar": "/assets/blog/author/ryan.levy.png",
+    "description": "Business Development"
+  },
+  {
+    "id": "glenn.reyes",
+    "name": "Glenn Reyes",
+    "avatar": "/assets/blog/author/glenn.reyes.jpeg",
+    "description": "Developer Relations"
+  }
+]

packages/tools/docs-tools/src/remarkAdmonition.ts

@@ -0,0 +1,128 @@
+import { Paragraph, PhrasingContent } from "mdast";
+import { DocsRootContent, ITree, Plugin, ChildrenWithValues, typeWithValue } from "./types";
+
+const STARTNOTER_EGEXP = /^:::\s?(\w+)\s?([\w\s]+)?$/;
+const ENDNOTER_EGEXP = /:::\s*$/m;
+
+let STARTELM: Paragraph | undefined;
+
+// check the branch with the start of a notification
+// notifications start with ':::' followed by a label and maybe a title
+const isStart = (branch: DocsRootContent): null | string[] => {
+  if('children' in branch === false) return null;
+
+  if ('children' in branch) {
+    if(branch.children.length === 0) return null;
+    const value = (branch.children as ChildrenWithValues)?.[0].value ?? '';
+    console.log('isStart ', value.match(STARTNOTER_EGEXP));
+    return value.match(STARTNOTER_EGEXP);
+  }
+  return null;
+};
+
+const isEnd = (branch: DocsRootContent): boolean => {
+  if('children' in branch === false) return false;
+  if('children' in branch) {
+    if (branch.children.length === 0) return false;
+
+    const endLeaf = (branch.children as ChildrenWithValues).find((item: typeWithValue) =>
+      item.value?.match(ENDNOTER_EGEXP),
+    );
+
+    if (endLeaf) {
+      endLeaf.value = endLeaf.value?.replace(':::', '');
+      return Boolean(endLeaf);
+    }
+  }
+
+  return false;
+};
+
+// get the props (label and title) for the notification
+const getProps = (branch: DocsRootContent) => {
+  if('children' in branch === false) return {};
+
+  if('children' in branch) {
+    if (branch.children.length === 0) return {};
+    const value = (branch.children as ChildrenWithValues)[0].value ?? '';
+
+    const match = STARTNOTER_EGEXP.exec(value);
+    if (!match) return {};
+
+    return {
+      label: match[1],
+      title: match[2],
+    };
+  }
+};
+
+const getStartElm = () => {
+  return STARTELM;
+};
+
+const setStartElm = (startElm: Paragraph) => {
+  STARTELM = startElm;
+};
+
+const clearStartElm = () => {
+  STARTELM = undefined;
+};
+
+/**
+ * the reduce function will make all the branches between the start and end of a notification a child of the start branch
+ */
+const reduceToNotifications = (acc: DocsRootContent[], branch:DocsRootContent) => {
+  if(branch.type === 'paragraph') {
+    if (isStart(branch)) {
+      setStartElm(branch);
+
+      const props = getProps(branch);
+      // @ts-ignore
+      branch.type = 'element';
+      (branch.children as ChildrenWithValues)[0].value = '';
+      branch.data = {
+        hName: 'kda-notification',
+        hProperties: props,
+      };
+
+      if (isEnd(branch)) {
+        clearStartElm();
+      }
+
+      return [...acc, branch];
+    }
+  } else {
+    return [...acc, branch];
+  }
+
+
+  const startElm = getStartElm();
+  if (startElm) {
+    if (isEnd(branch)) {
+      clearStartElm();
+    }
+    console.log('startElm ', startElm);
+    startElm.children = [
+      ...startElm.children,
+      branch,
+    ] as PhrasingContent[];
+
+    // if in the middle or end of the notification do not return the branch.
+    // the branch is now a child of the startbranch
+    return acc;
+  }
+
+  return [...acc, branch];
+};
+
+const remarkAdmonitions = (): Plugin => {
+  return async (tree): Promise<ITree> => {
+    const newChildren = tree.children
+    .reduce(reduceToNotifications, []);
+
+    tree.children = newChildren;
+    return tree;
+  };
+};
+
+export { remarkAdmonitions as default };

packages/tools/docs-tools/src/remarkCheckForCodeTitle.ts

@@ -1,8 +1,4 @@
-import type { Root, RootContent } from 'mdast';
-
-interface Tree extends Omit<Root, 'children'> {
-  children: RootContent[];
-}
+import { ITree, Plugin } from './types';
 
 const replaceOrConcatString = (str?: string | null): string => {
   if (!str) str = '';
@@ -18,12 +14,12 @@ const replaceOrConcatString = (str?: string | null): string => {
   return str;
 };
 
-const remarkCheckForCodeTitle = () => {
-  return async (tree: Tree) => {
+const remarkCheckForCodeTitle = (): Plugin => {
+  return async (tree: ITree): Promise<ITree> => {
     const children = tree.children.map((node) => {
       const { type } = node;
 
-      if (type == 'code') {
+      if (type === 'code') {
         node.meta = replaceOrConcatString(node.meta);
       }