Endpoint component with markdoc

This change allows us to document api endpoints using markdoc using the same layout as seen in the [Protocol Tailwind UI Example](https://protocol.tailwindui.com/contacts#list-all-contacts).

There are issues with the styling such as the h2 header but we are just focussed on getting the layout correct then will followup with styling later once we have aligned with the designers.

markdoc.config.mjs

@@ -1,6 +1,14 @@
 import { defineMarkdocConfig, component } from '@astrojs/markdoc/config';
+import shiki from '@astrojs/markdoc/shiki';
 
 export default defineMarkdocConfig({
+  extends: [
+    shiki({
+      theme: 'github-light',
+      wrap: true,
+      langs: [],
+    }),
+  ],
   tags: {
     properties: {
       render: component('./src/components/Properties.astro'),
@@ -11,6 +19,25 @@ export default defineMarkdocConfig({
         name: { type: String, required: true },
         type: { type: String, required: true },
       },
-    }
+    },
+    endpoint: {
+      render: component('./src/components/Endpoint.astro'),
+      attributes: {
+        method: { type: String, required: true },
+        path: { type: String, required: true },
+      },
+    },
+    row: {
+      render: component('./src/components/Row.astro'),
+    },
+    column: {
+      render: component('./src/components/Column.astro'),
+      attributes: {
+        sticky: { type: Boolean },
+      },
+    },
+    code: {
+      render: component('./src/components/Code.astro'),
+    },
   }
 });

package.json

@@ -31,6 +31,7 @@
     "flexsearch": "^0.7.31",
     "glob": "^8.1.0",
     "gray-matter": "^4.0.3",
+    "jsdom": "^22.1.0",
     "linkinator": "^5.0.2",
     "mdast-util-to-string": "^3.1.1",
     "mermaid": "^9.3.0",
@@ -43,7 +44,6 @@
     "unist-util-find-after": "^4.0.1",
     "unist-util-visit": "^4.1.2",
     "vitest": "^0.28.3",
-    "vue": "^3.2.47",
-    "jsdom": "^22.1.0"
+    "vue": "^3.2.47"
   }
 }

src/__tests__/__snapshots__/links.integration.test.js.snap

@@ -302,6 +302,7 @@ exports[`the build should not break any links 1`] = `
   "/api/managed-integrations#paypal-referral",
   "/api/managed-integrations#top",
   "/api/media-uploads",
+  "/api/media-uploads#attributes",
   "/api/media-uploads#contents",
   "/api/media-uploads#create-a-presigned-url-for-media-upload-experimental",
   "/api/media-uploads#get-media-upload-location-experimental",

src/components/Code.astro

@@ -0,0 +1,7 @@
+---
+import ProseCode from "./ProseCode.vue";
+---
+
+<ProseCode>
+  <slot />
+</ProseCode>

src/components/Column.astro

@@ -0,0 +1,8 @@
+
+---
+const { sticky = false } = Astro.props;
+---
+
+<div class=`${sticky ? '[&>:first-child]:mt-0 [&>:last-child]:mb-0 xl:sticky xl:top-24' : '[&>:first-child]:mt-0 [&>:last-child]:mb-0'}`>
+  <slot />
+</div>

src/components/Endpoint.astro

@@ -0,0 +1,28 @@
+
+---
+const { method, path } = Astro.props;
+const valueColorMap = {
+  GET: 'emerald',
+  POST: 'sky',
+  PUT: 'amber',
+  DELETE: 'rose',
+};
+const color = valueColorMap[method] || 'emerald';
+const colorStyles = {
+  emerald: 'ring-emerald-300 dark:ring-emerald-400/30 bg-emerald-400/10 text-emerald-500 dark:text-emerald-400',
+  sky: 'ring-sky-300 bg-sky-400/10 text-sky-500 dark:ring-sky-400/30 dark:bg-sky-400/10 dark:text-sky-400',
+  amber: 'ring-amber-300 bg-amber-400/10 text-amber-500 dark:ring-amber-400/30 dark:bg-amber-400/10 dark:text-amber-400',
+  rose: 'ring-rose-200 bg-rose-50 text-red-500 dark:ring-rose-500/20 dark:bg-rose-400/10 dark:text-rose-400',
+}
+---
+
+<div>
+  <div class="flex items-center gap-x-3">
+    <span class=`${colorStyles[color]} text-[0.625rem] leading-6 rounded-lg px-1.5 ring-1 ring-inset`>{ method }</span>
+    <span class="h-0.5 w-0.5 rounded-full bg-zinc-300 dark:bg-zinc-600"/>
+    <span class="text-xs text-zinc-400">{ path }</span>
+  </div>
+
+  <slot />
+
+</div>

src/components/Row.astro

@@ -0,0 +1,3 @@
+<div class="grid grid-cols-1 items-start gap-x-16 gap-y-10 xl:max-w-none xl:grid-cols-2">
+  <slot />
+</div>

src/content/api/media-uploads.mdoc

@@ -44,3 +44,77 @@ When the Media Upload was updated.
 The User or API Key that updated the Media Upload.
 {% /property %}
 {% /properties %}
+
+{% endpoint method="POST" path="/api/media-uploads" %}
+## Create a presigned URL for Media Upload EXPERIMENTAL
+{% row %}
+{% column %}
+### Attributes
+{% properties %}
+{% property name="accountId" type="string" %}
+The Media Upload's owning Centrapay Account id.
+{% /property %}
+
+{% property name="mimeType" type="string" %}
+The media (MIME) type of the upload.
+{% /property %}
+
+{% property name="fileName" type="string" %}
+The file name of the upload.
+{% /property %}
+{% /properties %}
+{% /column %}
+
+{% column sticky=true %}
+
+{% code %}
+```bash
+curl -X POST https://service.centrapay.com/api/media-uploads \
+  -H "X-Api-Key: $api_key" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "accountId": "Jaim1Cu1Q55uooxSens6yk",
+    "mimeType": "image/png",
+    "fileName": "image.png"
+  }'
+```
+{% /code %}
+
+{% code %}
+```json
+{
+  "id": "DKTs3U38hdhfEqwF1JKoT2",
+  "uploadUrl": "https://media-upload.centrapay.com/image.png?jhbdsfau67ewejshb=487hsdjhbdgs743"
+}
+```
+{% /code %}
+
+{% /column %}
+{% /row %}
+{% /endpoint %}
+
+
+{% endpoint method="GET" path="/api/media-uploads/{mediaUploadId}/location" %}
+## Get Media Upload Location EXPERIMENTAL
+{% row %}
+{% column/ %}
+{% column sticky=true %}
+
+{% code %}
+```bash
+curl https://service.centrapay.com/api/media-uploads/DKTs3U38hdhfEqwF1JKoT2/location \
+  -H "X-Api-Key: $api_key"
+```
+{% /code %}
+
+{% code %}
+```json
+{
+  "url": "https://media-upload.centrapay.com/image.png?jhbdsfau67ewejshb=487hsdjhbdgs743"
+}
+```
+{% /code %}
+
+{% /column %}
+{% /row %}
+{% /endpoint %}