docs: update orchestration docs

packages/website/package.json

@@ -21,7 +21,10 @@
     "react-dom": "^19.1.4",
     "react-markdown": "^10.1.0",
     "rehype-autolink-headings": "^7.1.0",
+    "rehype-pretty-code": "^0.14.3",
     "rehype-slug": "^6.0.0",
+    "remark-gfm": "^4.0.1",
+    "shiki": "^4.0.2",
     "wrangler": "^4.59.1"
   },
   "devDependencies": {

packages/website/src/components/docs-source-footer.tsx

@@ -0,0 +1,15 @@
+import type { Doc } from "~/docs";
+
+const GITHUB_BASE_URL = "https://github.com/getpaseo/paseo/blob/main";
+
+export function DocsSourceFooter({ doc }: { doc: Doc }) {
+  const sourceUrl = `${GITHUB_BASE_URL}/${doc.sourcePath}`;
+
+  return (
+    <footer className="docs-source-footer">
+      <a href={sourceUrl} target="_blank" rel="noreferrer">
+        View this page on GitHub
+      </a>
+    </footer>
+  );
+}

packages/website/src/docs-rehype.ts

@@ -1,8 +1,52 @@
 import rehypeAutolinkHeadings from "rehype-autolink-headings";
+import { rehypePrettyCode } from "rehype-pretty-code";
 import rehypeSlug from "rehype-slug";
+import remarkGfm from "remark-gfm";
+import { createHighlighterCore, type HighlighterCore } from "shiki/core";
+import { createJavaScriptRegexEngine } from "shiki/engine/javascript";
 import type { PluggableList } from "unified";
 
+export const docsRemarkPlugins: PluggableList = [remarkGfm];
+
+let docsHighlighter: Promise<HighlighterCore> | undefined;
+
+function getDocsHighlighter(): Promise<HighlighterCore> {
+  docsHighlighter ??= Promise.all([
+    import("shiki/themes/catppuccin-mocha.mjs"),
+    import("shiki/langs/bash.mjs"),
+    import("shiki/langs/json.mjs"),
+    import("shiki/langs/javascript.mjs"),
+    import("shiki/langs/typescript.mjs"),
+    import("shiki/langs/tsx.mjs"),
+    import("shiki/langs/yaml.mjs"),
+    import("shiki/langs/markdown.mjs"),
+  ]).then(([theme, bash, json, javascript, typescript, tsx, yaml, markdown]) =>
+    createHighlighterCore({
+      themes: [theme.default],
+      langs: [
+        bash.default,
+        json.default,
+        javascript.default,
+        typescript.default,
+        tsx.default,
+        yaml.default,
+        markdown.default,
+      ],
+      engine: createJavaScriptRegexEngine(),
+    }),
+  );
+  return docsHighlighter;
+}
+
 export const docsRehypePlugins: PluggableList = [
+  [
+    rehypePrettyCode,
+    {
+      theme: "catppuccin-mocha",
+      keepBackground: false,
+      getHighlighter: getDocsHighlighter,
+    },
+  ],
   rehypeSlug,
   [
     rehypeAutolinkHeadings,

packages/website/src/docs.ts

@@ -8,6 +8,7 @@ interface DocFrontmatter {
 export interface Doc {
   slug: string;
   href: string;
+  sourcePath: string;
   frontmatter: DocFrontmatter;
   content: string;
 }
@@ -43,6 +44,10 @@ function pathToSlug(path: string): string {
   return noExt === "index" ? "" : noExt;
 }
 
+function pathToSourcePath(path: string): string {
+  return path.split("/public-docs/")[1] ?? path;
+}
+
 function loadDocs(): Doc[] {
   const docs: Doc[] = [];
 
@@ -55,6 +60,7 @@ function loadDocs(): Doc[] {
     docs.push({
       slug,
       href,
+      sourcePath: `public-docs/${pathToSourcePath(path)}`,
       frontmatter: {
         title: data.title ?? "",
         description: data.description ?? "",

packages/website/src/routes/docs/$.tsx

@@ -1,7 +1,8 @@
 import { createFileRoute } from "@tanstack/react-router";
-import ReactMarkdown from "react-markdown";
+import { MarkdownAsync } from "react-markdown";
+import { DocsSourceFooter } from "~/components/docs-source-footer";
 import { getDoc } from "~/docs";
-import { docsRehypePlugins } from "~/docs-rehype";
+import { docsRehypePlugins, docsRemarkPlugins } from "~/docs-rehype";
 import { pageMeta } from "~/meta";
 
 export const Route = createFileRoute("/docs/$")({
@@ -19,11 +20,22 @@ export const Route = createFileRoute("/docs/$")({
 function DocsPage() {
   const { _splat } = Route.useParams();
   const slug = _splat ?? "";
+  return <RenderedDoc slug={slug} />;
+}
+
+async function RenderedDoc({ slug }: { slug: string }) {
   const doc = getDoc(slug);
 
   if (!doc) {
     return <p className="text-muted-foreground">Doc not found.</p>;
   }
 
-  return <ReactMarkdown rehypePlugins={docsRehypePlugins}>{doc.content}</ReactMarkdown>;
+  return (
+    <>
+      <MarkdownAsync remarkPlugins={docsRemarkPlugins} rehypePlugins={docsRehypePlugins}>
+        {doc.content}
+      </MarkdownAsync>
+      <DocsSourceFooter doc={doc} />
+    </>
+  );
 }

packages/website/src/routes/docs/index.tsx

@@ -1,7 +1,8 @@
 import { createFileRoute } from "@tanstack/react-router";
-import ReactMarkdown from "react-markdown";
+import { MarkdownAsync } from "react-markdown";
+import { DocsSourceFooter } from "~/components/docs-source-footer";
 import { getDoc } from "~/docs";
-import { docsRehypePlugins } from "~/docs-rehype";
+import { docsRehypePlugins, docsRemarkPlugins } from "~/docs-rehype";
 import { pageMeta } from "~/meta";
 
 export const Route = createFileRoute("/docs/")({
@@ -15,8 +16,15 @@ export const Route = createFileRoute("/docs/")({
   component: DocsIndex,
 });
 
-function DocsIndex() {
+async function DocsIndex() {
   const doc = getDoc("");
   if (!doc) return <p className="text-muted-foreground">Doc not found.</p>;
-  return <ReactMarkdown rehypePlugins={docsRehypePlugins}>{doc.content}</ReactMarkdown>;
+  return (
+    <>
+      <MarkdownAsync remarkPlugins={docsRemarkPlugins} rehypePlugins={docsRehypePlugins}>
+        {doc.content}
+      </MarkdownAsync>
+      <DocsSourceFooter doc={doc} />
+    </>
+  );
 }

packages/website/src/styles.css

@@ -17,6 +17,7 @@
 /* Inline code styling - scoped to prose content */
 .prose :not(pre) > code {
   background-color: var(--color-muted);
+  color: var(--color-foreground);
   padding: 0.125rem 0.375rem;
   border-radius: 0.25rem;
   font-size: 0.875em;
@@ -110,7 +111,7 @@
   line-height: 1.25;
   font-weight: 500;
   margin-top: 0;
-  margin-bottom: 1rem;
+  margin-bottom: 2rem;
 }
 
 .docs-prose h2 {
@@ -171,8 +172,11 @@
 
 .docs-prose a {
   color: var(--color-foreground);
+  font-weight: 500;
   text-decoration: underline;
-  text-underline-offset: 2px;
+  text-decoration-thickness: 1px;
+  text-decoration-color: var(--color-primary);
+  text-underline-offset: 3px;
 }
 
 .docs-prose a:hover {
@@ -222,6 +226,32 @@
   margin-bottom: 0;
 }
 
+.docs-prose table {
+  width: 100%;
+  border-collapse: collapse;
+  margin-top: 1rem;
+  margin-bottom: 1rem;
+  font-size: 0.875rem;
+}
+
+.docs-prose th,
+.docs-prose td {
+  border: 1px solid var(--color-border);
+  padding: 0.625rem 0.75rem;
+  text-align: left;
+  vertical-align: top;
+}
+
+.docs-prose th {
+  background-color: var(--color-muted);
+  color: var(--color-foreground);
+  font-weight: 600;
+}
+
+.docs-prose tbody tr:nth-child(even) {
+  background-color: rgba(255, 255, 255, 0.02);
+}
+
 .docs-prose pre {
   background-color: var(--color-card);
   border: 1px solid var(--color-border);
@@ -235,6 +265,11 @@
   color: var(--color-foreground);
 }
 
+.docs-prose pre [data-line] {
+  display: inline-block;
+  min-width: 100%;
+}
+
 .docs-prose pre code {
   background: transparent;
   padding: 0;
@@ -244,6 +279,7 @@
 
 .docs-prose :not(pre) > code {
   background-color: var(--color-muted);
+  color: var(--color-foreground);
   padding: 0.125rem 0.375rem;
   border-radius: 0.25rem;
   font-size: 0.875em;
@@ -255,6 +291,23 @@
   margin-bottom: 2rem;
 }
 
+.docs-source-footer {
+  border-top: 1px solid var(--color-border);
+  margin-top: 3rem;
+  padding-top: 1.25rem;
+  font-size: 0.875rem;
+}
+
+.docs-source-footer a {
+  color: rgba(255, 255, 255, 0.5);
+  font-weight: 500;
+  text-decoration: none;
+}
+
+.docs-source-footer a:hover {
+  color: var(--color-foreground);
+}
+
 /* Blog post prose styles — adapted from moboudra.com */
 .blog-prose {
   color: rgba(250, 250, 250, 0.82);
@@ -364,11 +417,11 @@
 @theme {
   --color-background: #101615;
   --color-foreground: #fafafa;
-  --color-muted: #252b2a;
+  --color-muted: #1a1f1e;
   --color-muted-foreground: #a8adac;
   --color-card: #171d1c;
   --color-border: #252b2a;
-  --color-primary: #3b82f6;
+  --color-primary: #239956;
   --color-primary-foreground: #ffffff;
   --color-secondary: #252b2a;
   --color-secondary-foreground: #fafafa;