@stainless-api/docs 0.1.0-beta.5 → 0.1.0-beta.51

package/stl-docs/proseMarkdown/proseMarkdownIntegration.ts

@@ -0,0 +1,64 @@
+import type { AstroIntegration } from 'astro';
+import { readFile, writeFile } from 'fs/promises';
+import { toMarkdown } from './toMarkdown';
+import { resolveSrcFile } from '../../resolveSrcFile';
+import { getSharedLogger } from '../../shared/getSharedLogger';
+import { bold } from '../../shared/terminalUtils';
+
+export function stainlessDocsMarkdownRenderer({ enabled }: { enabled: boolean }): AstroIntegration {
+  return {
+    name: 'stl-docs-md',
+    hooks: {
+      'astro:config:setup': ({ addMiddleware }) => {
+        if (enabled) {
+          addMiddleware({
+            entrypoint: resolveSrcFile('/stl-docs/proseMarkdown/proseMarkdownMiddleware.ts'),
+            order: 'post',
+          });
+        }
+      },
+      'astro:build:done': async ({ assets, logger: localLogger, dir }) => {
+        const logger = getSharedLogger({ fallback: localLogger });
+        if (!enabled) {
+          logger.info('Stainless Docs prose Markdown rendering is disabled, skipping...');
+          return;
+        }
+        const starlightPagePatterns = ['/[...slug]'];
+        const pagesToRender = Array.from(assets.entries())
+          .filter(([k]) => {
+            if (starlightPagePatterns.includes(k)) {
+              return true;
+            }
+            return false;
+          })
+          .map(([, v]) => v)
+          .flat()
+          .map((v) => v.pathname);
+
+        logger.info(bold(`Building ${pagesToRender.length} Markdown pages for prose content`));
+
+        const outputBasePath = dir.pathname;
+
+        let completedCount = 0;
+        for (const absHtmlPath of pagesToRender) {
+          const txt = await readFile(absHtmlPath, 'utf-8');
+          const md = await toMarkdown(txt);
+          if (md) {
+            const absMdPath = absHtmlPath.replace('.html', '.md');
+            await writeFile(absMdPath, md, 'utf-8');
+
+            completedCount++;
+
+            const relHtmlPath = absHtmlPath.replace(outputBasePath, '');
+            const relMdPath = absMdPath.replace(outputBasePath, '');
+
+            logger.info(`(${completedCount}/${pagesToRender.length}) ${relHtmlPath} -> ${relMdPath}`);
+          } else {
+            logger.error(`Failed to render ${absHtmlPath} as Markdown`);
+            process.exit(1);
+          }
+        }
+      },
+    },
+  };
+}

package/stl-docs/proseMarkdown/proseMarkdownMiddleware.ts

@@ -0,0 +1,34 @@
+import { defineMiddleware } from 'astro:middleware';
+import { toMarkdown } from './toMarkdown';
+import { API_REFERENCE_BASE_PATH } from 'virtual:stl-docs-virtual-module';
+
+// this is only run in `astro dev` for rendering prose content as Markdown on the fly.
+export const onRequest = defineMiddleware(async (context, next) => {
+  // eslint-disable-next-line turbo/no-undeclared-env-vars
+  if (!import.meta.env.DEV) {
+    return next();
+  }
+
+  if (API_REFERENCE_BASE_PATH && context.url.pathname.startsWith(API_REFERENCE_BASE_PATH)) {
+    // handled by the API reference API route in stl-starlight plugin
+    return next();
+  }
+
+  if (!context.url.pathname.endsWith('/index.md')) {
+    return next();
+  }
+
+  const htmlUrl = new URL(context.url.pathname.replace('index.md', ''), context.url);
+  const resp = await fetch(htmlUrl);
+  if (!resp.ok) {
+    return new Response('Failed to fetch HTML', { status: 400 });
+  }
+  const html = await resp.text();
+  const md = await toMarkdown(html);
+
+  if (!md) {
+    return new Response('Failed to render Markdown', { status: 400 });
+  }
+
+  return new Response(md, { status: 200 });
+});

package/stl-docs/proseMarkdown/toMarkdown.ts

@@ -0,0 +1,158 @@
+import { unified } from 'unified';
+import rehypeParse from 'rehype-parse';
+import rehypeRemark from 'rehype-remark';
+import remarkGfm from 'remark-gfm';
+import remarkStringify from 'remark-stringify';
+import { HTMLElement, parse } from 'node-html-parser';
+
+type PaginationLink = {
+  href: string;
+  label: string;
+};
+
+type PaginationItems = {
+  prev: PaginationLink | null;
+  next: PaginationLink | null;
+};
+
+function parsePaginationLink(footer: HTMLElement, rel: 'next' | 'prev'): PaginationLink | null {
+  const link = footer.querySelector(`.pagination-links a[rel="${rel}"]`);
+  if (!link) {
+    return null;
+  }
+
+  const title = link.querySelector('.link-title');
+  if (!title) {
+    return null;
+  }
+
+  const href = link.getAttribute('href');
+  if (!href) {
+    return null;
+  }
+
+  return {
+    href,
+    label: title.text,
+  };
+}
+
+function isRelativeLink(href: string) {
+  return href.startsWith('/');
+}
+
+function hasExtension(href: string) {
+  return href.includes('.');
+}
+
+function removeTrailingSlash(href: string) {
+  return href.replace(/\/$/, '');
+}
+
+function makeMarkdownLinks(el: HTMLElement) {
+  el.querySelectorAll('a').forEach((a) => {
+    const href = a.getAttribute('href');
+    if (!href) {
+      return a;
+    }
+
+    if (isRelativeLink(href) && !hasExtension(href)) {
+      if (href === '/') {
+        a.setAttribute('href', '/index.md');
+      } else {
+        a.setAttribute('href', `${removeTrailingSlash(href)}/index.md`);
+      }
+    }
+    return a;
+  });
+}
+
+function removeHiddenElements(el: HTMLElement) {
+  const hiddenSelectors = ['.sl-anchor-link'];
+  for (const selector of hiddenSelectors) {
+    const hiddenElements = el.querySelectorAll(selector);
+    for (const hiddenElement of hiddenElements) {
+      hiddenElement.remove();
+    }
+  }
+}
+
+export async function toMarkdown(html: string) {
+  const root = parse(html);
+
+  const mainEl = root.querySelector('main');
+
+  if (!mainEl) {
+    return null;
+  }
+
+  makeMarkdownLinks(mainEl);
+
+  const footer = mainEl.querySelector('footer');
+
+  const markdownContentEl = mainEl.querySelector('.sl-markdown-content');
+  if (!markdownContentEl) {
+    return null;
+  }
+
+  removeHiddenElements(markdownContentEl);
+
+  const articleContent = markdownContentEl.innerHTML;
+
+  const paginationLinks: PaginationItems = {
+    prev: null,
+    next: null,
+  };
+
+  if (footer) {
+    paginationLinks.prev = parsePaginationLink(footer, 'prev');
+    paginationLinks.next = parsePaginationLink(footer, 'next');
+  }
+
+  let md = (
+    await unified()
+      .use(rehypeParse, { fragment: true }) // parse HTML
+      .use(rehypeRemark) // rehype (HTML) -> remark (MD AST)
+      .use(remarkGfm) // tables, strikethrough, autolinks, etc.
+      .use(remarkStringify, {
+        fences: true,
+        bullet: '-',
+        listItemIndent: 'one',
+        rule: '-',
+      })
+      .process(articleContent)
+  ).toString();
+
+  const title = root.querySelector('title')?.textContent;
+  const description = root.querySelector('meta[name="description"]')?.attributes.content;
+  const lastUpdated = root.querySelector('.meta time')?.attributes.datetime;
+
+  // let htmlUrl = url.toString().replace('.md', '');
+  // if (htmlUrl.endsWith('/index')) {
+  //   htmlUrl = htmlUrl.replace('/index', '');
+  // }
+
+  md = [
+    '---',
+    `title: ${title}`,
+    description ? `description: ${description}` : [],
+    lastUpdated ? `lastUpdated: ${lastUpdated}` : [],
+    // `source_url:`,
+    // `  html: ${htmlUrl}`,
+    // `  md: ${url.toString()}`,
+    '---\n',
+    md,
+  ]
+    .flat()
+    .join('\n');
+
+  if (paginationLinks.prev) {
+    md += `\n\n[Previous](${paginationLinks.prev.href})`;
+  }
+
+  if (paginationLinks.next) {
+    md += `\n\n[Next](${paginationLinks.next.href})`;
+  }
+
+  return md;
+}

package/stl-docs/tabsMiddleware.ts

@@ -1,7 +1,7 @@
 import type { StarlightRouteData } from '@astrojs/starlight/route-data';
 import { defineRouteMiddleware } from '@astrojs/starlight/route-data';
 
-import { SPLIT_TABS_ENABLED, TABS } from 'virtual:stl-stl-starlight-virtual-module';
+import { SPLIT_TABS_ENABLED, TABS } from 'virtual:stl-docs-virtual-module';
 import clsx from 'clsx';
 
 // this fn is loaded in the plugin via addRouteMiddleware
@@ -58,7 +58,7 @@ function getTabIndexForSlug(
   match: 'exact' | 'prefix';
 } | null {
   // ↓ exact match eg. slug = "/blog" and there is a link containing "/blog"
-  let tab = linksByTab.get(slug);
+  const tab = linksByTab.get(slug)!;
   if (typeof tab === 'string') {
     return {
       match: 'exact',
@@ -88,13 +88,19 @@ function getNonSplitLinksByTab() {
   const linksByTab = new Map<string, string>();
 
   for (let i = 0; i < TABS.length; i++) {
-    const tab = TABS[i];
+    const tab = TABS[i]!;
     linksByTab.set(tab.link, String(i));
   }
 
   return linksByTab;
 }
 
+export interface StarlightRouteWithStlDocs extends StarlightRouteData {
+  _stlDocs?: {
+    activeTabIndex: number;
+  };
+}
+
 export const onRequest = defineRouteMiddleware(async (context) => {
   // if using content collection schema, use: context.locals.starlightRoute.entry.data.stainlessStarlight
   // this worked without collections but relied on hijacking starlightRoute: context.props.frontmatter.stainlessStarlight
@@ -143,7 +149,8 @@ export const onRequest = defineRouteMiddleware(async (context) => {
   }
 
   // We store the active tab index so we can use it in our nav tabs component
-  context.locals.starlightRoute._stlStarlight = {
+  const routeData: StarlightRouteWithStlDocs = context.locals.starlightRoute;
+  routeData._stlDocs = {
     activeTabIndex: activeTabIndex.index,
   };
 
@@ -179,5 +186,6 @@ export const onRequest = defineRouteMiddleware(async (context) => {
 
   matchingGroup?.entries.unshift(...mobileLinks);
 
+  (context.locals._stlStarlightPage ??= {}).fullSidebar = context.locals.starlightRoute.sidebar;
   context.locals.starlightRoute.sidebar = matchingGroup.entries;
 });

package/styles/code.css

@@ -1,72 +1,90 @@
-@layer stainless {
-  .expressive-code {
-    .frame {
-      --code-background: var(--sl-color-bg-inline-code);
-    }
+.expressive-code {
+  .frame {
+    --code-background: var(--stl-color-faint-background);
+  }
+
+  figure.frame {
+    box-shadow: none;
+  }
 
-    figure.frame {
-      box-shadow: none;
+  figure,
+  pre {
+    border-radius: var(--sl-button-border-radius);
+    border-color: var(--stl-color-border);
+  }
+
+  .frame.has-title:not(.is-terminal),
+  .frame.is-terminal {
+    figcaption {
+      border-radius: var(--sl-button-border-radius) var(--sl-button-border-radius) 0 0;
+      border-color: var(--stl-color-border);
     }
 
-    figure,
     pre {
-      border-radius: var(--sl-button-border-radius);
-      border-color: var(--sl-color-hairline);
+      border-radius: 0 0 var(--sl-button-border-radius) var(--sl-button-border-radius);
+      border-color: var(--stl-color-border);
     }
+  }
 
-    .frame.has-title:not(.is-terminal),
-    .frame.is-terminal {
-      figcaption {
-        border-radius: var(--sl-button-border-radius) var(--sl-button-border-radius) 0 0;
-        border-color: var(--sl-color-hairline);
-      }
-
-      pre {
-        border-radius: 0 0 var(--sl-button-border-radius) var(--sl-button-border-radius);
-        border-color: var(--sl-color-hairline);
-      }
+  .frame.has-title:not(.is-terminal) {
+    figcaption span:first-child {
+      border-top-left-radius: var(--sl-button-border-radius);
     }
 
-    .frame.has-title:not(.is-terminal) {
-      figcaption span:first-child {
-        border-top-left-radius: var(--sl-button-border-radius);
-      }
-
-      .header::before {
-        border-color: var(--sl-color-hairline);
-      }
+    .header::before {
+      border-color: var(--stl-color-border);
+    }
 
-      .title::after {
-        bottom: -1px;
-        top: unset;
-      }
+    .title::after {
+      bottom: -1px;
+      top: unset;
     }
   }
+}
 
-  .astro-code {
-    border-radius: var(--sl-button-border-radius);
-    border-color: var(--sl-color-hairline);
-  }
+.astro-code {
+  border-radius: var(--sl-button-border-radius);
+  border-color: var(--stl-color-border);
+}
 
-  .stl-snippet-request-container {
-    position: relative;
+.stl-snippet-request-container {
+  position: relative;
+}
+
+.stl-snippet-expand-button {
+  display: none;
+
+  position: relative;
+  left: 50%;
+  transform: translateX(-50%);
+  bottom: 12px;
+  cursor: pointer;
+  height: auto;
+}
+
+.stl-snippet-code-is-expanded {
+  .ellipsis {
+    display: none;
   }
+}
 
+.stl-snippet-collapsible {
   .stl-snippet-expand-button {
-    display: none;
+    display: block;
+    margin-bottom: -23px;
+    /* Prevent clipping of the button with the container below */
+    z-index: 100;
+  }
+
+  .stl-snippet-code-is-collapsed {
+    .hidden {
+      display: none;
+      opacity: 0;
+    }
 
-    position: relative;
-    left: 50%;
-    transform: translateX(-50%);
-    bottom: 12px;
-    background-color: var(--stldocs-color-bg-inline-code);
-    cursor: pointer;
-    font-weight: 500;
-    line-height: 100%;
-    font-size: var(--stldocs-font-size-body-sm);
-    font-family: var(--stldocs-font);
-    padding: 4px 7px 4px 7px;
-    height: auto;
+    .leading-ws {
+      display: none;
+    }
   }
 
   .stl-snippet-code-is-expanded {
@@ -74,116 +92,61 @@
       display: none;
     }
   }
+}
 
-  .stl-snippet-collapsible {
-    .stl-snippet-expand-button {
-      display: block;
-      margin-bottom: -23px;
-      /* Prevent clipping of the button with the container below */
-      z-index: 100;
+.stldocs-root {
+  .stl-snippets-non-collapsible {
+    .shiki {
+      counter-reset: codeblock-line 0 !important;
     }
 
-    .stl-snippet-code-is-collapsed {
+    .stldocs-snippet {
       .hidden {
-        display: none;
-        opacity: 0;
+        display: inline;
+        opacity: 1;
       }
 
       .leading-ws {
-        display: none;
+        display: inline;
       }
-    }
 
-    .stl-snippet-code-is-expanded {
       .ellipsis {
         display: none;
       }
     }
   }
+}
 
-  .stldocs-root {
-    .stl-snippets-non-collapsible {
-      .shiki {
-        counter-reset: codeblock-line 0 !important;
-      }
-
-      .stldocs-snippet {
-        .hidden {
-          display: inline;
-          opacity: 1;
-        }
-
-        .leading-ws {
-          display: inline;
-        }
-
-        .ellipsis {
-          display: none;
-        }
-      }
-    }
-  }
-
-  .stl-snippet-dropdown-button-text {
-    font-weight: 500;
-    font-style: normal;
-    font-family: var(--stldocs-font);
-    line-height: 100%;
-    font-size: var(--sl-text-body-sm);
-    color: var(--sl-color-text);
-    text-transform: capitalize;
-
-    &.http {
-      text-transform: uppercase;
-    }
-  }
-
-  :root[data-theme='light'] {
-    .astro-code,
-    .astro-code span {
-      background-color: var(--sl-color-bg-inline-code) !important;
-    }
+.stldocs-root .stl-snippet-dropdown-button-text,
+.stl-snippet-dropdown-button-text {
+  font-weight: 500;
+  font-style: normal;
+  font-family: var(--stl-typography-font);
+  line-height: 100%;
+  font-size: var(--stl-typography-scale-sm);
+  color: var(--stl-color-foreground);
+}
 
-    .stldocs-snippet-response-pane {
-      .shiki,
-      .shiki span,
-      .astro-code,
-      .astro-code span {
-        background-color: var(--sl-color-bg-inline-code) !important;
-      }
-    }
-  }
+.shiki,
+.astro-code,
+.stldocs-snippet-response-pane {
+  background-color: var(--shiki-background, var(--stl-color-faint-background)) !important;
+}
 
-  :root[data-theme='dark'] {
-    /* 
+:root[data-theme='dark'] {
+  /*
     Need to use important to override inline variables. This is the
     recommended pattern in the shiki docs.
 
     https://shiki.style/guide/dual-themes#query-based-dark-mode
    */
-    .shiki,
-    .shiki span,
-    .astro-code,
-    .astro-code span {
-      color: var(--shiki-dark) !important;
-      background-color: var(--sl-color-bg) !important;
-      font-style: var(--shiki-dark-font-style) !important;
-      font-weight: var(--shiki-dark-font-weight) !important;
-      text-decoration: var(--shiki-dark-text-decoration) !important;
-    }
-
-    .astro-code,
-    .astro-code span {
-      background-color: var(--sl-color-bg-inline-code) !important;
-    }
-
-    .stldocs-snippet-response-pane {
-      .shiki,
-      .shiki span,
-      .astro-code,
-      .astro-code span {
-        background-color: var(--sl-color-bg-inline-code) !important;
-      }
-    }
+  .shiki,
+  .shiki span,
+  .astro-code,
+  .astro-code span {
+    color: var(--shiki-dark) !important;
+    font-style: var(--shiki-dark-font-style) !important;
+    font-weight: var(--shiki-dark-font-weight) !important;
+    text-decoration: var(--shiki-dark-text-decoration) !important;
   }
 }