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,22 @@
 import { defineMarkdocConfig, component } from '@astrojs/markdoc/config';
+import shiki from '@astrojs/markdoc/shiki';
 
 export default defineMarkdocConfig({
+  extends: [
+    shiki({
+      // Choose from Shiki's built-in themes (or add your own)
+      // Default: 'github-dark'
+      // https://github.com/shikijs/shiki/blob/main/docs/themes.md
+      theme: 'github-light',
+      // Enable word wrap to prevent horizontal scrolling
+      // Default: false
+      wrap: true,
+      // Pass custom languages
+      // Note: Shiki has countless langs built-in, including `.astro`!
+      // https://github.com/shikijs/shiki/blob/main/docs/languages.md
+      langs: [],
+    }),
+  ],
   tags: {
     properties: {
       render: component('./src/components/Properties.astro'),
@@ -11,6 +27,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/ProseCode.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/components/Column.astro

@@ -0,0 +1,9 @@
+
+---
+const { sticky = false } = Astro.props;
+const className = sticky ? '[&>:first-child]:mt-0 [&>:last-child]:mb-0 xl:sticky xl:top-24' : '[&>:first-child]:mt-0 [&>:last-child]:mb-0';
+---
+
+<div class=`${className}`>
+  <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=`font-mono text-[0.625rem] font-semibold leading-6 rounded-lg px-1.5 ring-1 ring-inset + ${colorStyles[color]}`>{ method }</span>
+    <span class="h-0.5 w-0.5 rounded-full bg-zinc-300 dark:bg-zinc-600"/>
+    <span class="font-mono text-xs text-zinc-400">{ path }</span>
+  </div>
+
+  <slot />
+
+</div>

src/components/ProseCode.astro

@@ -2,6 +2,6 @@
 import ProseCode from "./ProseCode.vue";
 ---
 
-<ProseCode client:load>
+<ProseCode>
   <slot />
 </ProseCode>

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,92 @@ 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 %}
+### Required Fields
+{% 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 [Request]
+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 [Response]
+{
+  "has_more": false,
+  "data": [
+    {
+      "id": "WAz8eIbvDR60rouK",
+      "username": "FrankMcCallister",
+      "phone_number": "1-800-759-3000",
+      "avatar_url": "https://assets.protocol.chat/avatars/frank.jpg",
+      "display_name": null,
+      "conversation_id": "xgQQXg3hrtjh7AvZ",
+      "last_active_at": 705103200,
+      "created_at": 692233200
+    },
+    {
+      "id": "hSIhXBhNe8X1d8Et"
+      // ...
+    }
+  ]
+}
+```
+{% /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 [Request]
+curl https://service.centrapay.com/api/media-uploads/DKTs3U38hdhfEqwF1JKoT2/location \
+  -H "X-Api-Key: $api_key"
+```
+{% /code %}
+
+{% code %}
+```json [Response]
+{
+  "url": "https://media-upload.centrapay.com/image.png?jhbdsfau67ewejshb=487hsdjhbdgs743"
+}
+```
+{% /code %}
+
+{% /column %}
+{% /row %}
+{% /endpoint %}