@stainless-api/docs 0.1.0-beta.7 → 0.1.0-beta.70

package/plugin/routes/Docs.astro

@@ -1,24 +1,10 @@
 ---
-import StarlightPage from "@astrojs/starlight/components/StarlightPage.astro";
-import { cmsClient } from "../cms/client";
-
-import "@stainless-api/docs-ui/src/styles/resets.css";
-import "@stainless-api/docs-ui/src/styles/primitives.css";
-import "@stainless-api/docs-ui/src/styles/main.css";
-import "@stainless-api/docs-ui/src/styles/snippets.css";
-// TODO: fix variables.css import
-// import "./variables.css";
-
-import {
-  getReadmeContent,
-  generateDocsRoutes,
-  buildPageNavigation,
-  RenderSpec,
-  astroMarkdownRender,
-} from "../react/Routing";
-import { getResourceFromSpec } from "@stainless-api/docs-ui/src/utils";
-import { BASE_PATH, CONTENT_PANEL_LAYOUT,MIDDLEWARE } from "virtual:stl-starlight-virtual-module";
-
+import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
+import { cmsClient } from '../cms/client';
+import { getReadmeContent, buildPageNavigation, RenderSpec, astroMarkdownRender } from '../react/Routing';
+import { getResourceFromSpec } from '@stainless-api/docs-ui/utils';
+import { BASE_PATH, CONTENT_PANEL_LAYOUT, MIDDLEWARE } from 'virtual:stl-starlight-virtual-module';
+import { generateDocsRoutes } from '../helpers/generateDocsRoutes';
 
 const spec = await cmsClient.getSpec();
 const routes = generateDocsRoutes(spec);
@@ -26,62 +12,52 @@ const routes = generateDocsRoutes(spec);
 const route = routes.find((r) => r.params.slug === Astro.params.slug);
 
 if (!route) {
-  throw new Error("No such route");
+  throw new Error(`Could not find a route for slug '${Astro.params.slug}'`);
 }
 
+// PageTitle override will skip rendering the default Starlight title
+Astro.locals._stlStarlightPage = {
+  skipRenderingStarlightTitle: route.props.kind === 'readme' ? false : true,
+};
+
 const readmeContent = await getReadmeContent(spec, route.props.language);
-const readme =
-  route.props.kind === "readme"
-    ? await astroMarkdownRender(readmeContent ?? "")
-    : null;
+const readme = route.props.kind === 'readme' ? await astroMarkdownRender(readmeContent ?? '') : null;
 
-const resource = route.props.stainlessPath
-  ? getResourceFromSpec(route.props.stainlessPath, spec)
-  : null;
+const resource = route.props.stainlessPath ? getResourceFromSpec(route.props.stainlessPath, spec) : null;
 
 const pageNav =
-  route.props.kind === "resource" && resource
+  route.props.kind === 'resource' && resource
     ? buildPageNavigation(resource)
-    : route.props.kind === "readme" && readme?.metadata
+    : route.props.kind === 'readme' && readme?.metadata
       ? readme?.metadata.headings
       : [];
 
 const props = route.props;
+Astro.locals.language = props.language;
 
 if (readme) {
   const repo = spec.metadata?.[props.language]?.code_url;
-  readme.code = readme.code.replace(
-    /<a href="(?!(?:https?:\/\/|\/\/))([^"]+)"/g,
-    `<a href="${repo}/$1"`);
-  props.title = readme.metadata.headings[0].text ?? "Overview";
+  readme.code = readme.code.replace(/<a href="(?!(?:https?:\/\/|\/\/))([^"]+)"/g, `<a href="${repo}/$1"`);
+  props.title = readme.metadata.headings[0]!.text ?? 'Overview';
 }
-
 ---
 
-
 <StarlightPage
   headings={pageNav}
   frontmatter={{
     title: props?.title,
     head: [
       {
-        tag: "link",
+        tag: 'link',
         attrs: {
-          rel: "alternate",
-          type: "text/markdown",
-          href: `${BASE_PATH}/${Astro.params.slug}.md`
-        }
-      }
+          rel: 'alternate',
+          type: 'text/markdown',
+          href: `${BASE_PATH}/${Astro.params.slug}.md`,
+        },
+      },
     ],
     pagefind: false,
-    tableOfContents: ["resource", "readme"].includes(props.kind)
-      ? { maxHeadingLevel: 6 }
-      : false,
-    // @ts-ignore
-    stainlessStarlight: {
-      basePath: BASE_PATH,
-      ...props,
-    },
+    tableOfContents: ['resource', 'readme'].includes(props.kind) ? { maxHeadingLevel: 6 } : false,
   }}
 >
   {
@@ -97,7 +73,9 @@ if (readme) {
           transformRequestSnippet={MIDDLEWARE.transformRequestSnippet}
         />
 
-        <style is:inline>
+        <style
+          is:inline
+          set:text={`
           #stldocs-snippet-title {
             display: flex;
             gap: 5px;
@@ -105,59 +83,53 @@ if (readme) {
 
           .stldocs-snippet-code:not(.stldocs-snippet-response .stldocs-snippet-code) {
             padding: 0 !important;
-            
+
             .astro-code {
               padding: 1rem;
             }
           }
 
-
           [data-has-sidebar]:not([data-has-toc]) .sl-container {
             max-width: 1428px;
           }
-
-          .content-panel:nth-of-type(1) {
-            display: none;
-          }
-
-          .content-panel:nth-of-type(2) {
-            border: none;
-            padding: 0;
-          }
-        </style>
+        `}
+        />
       </div>
     ) : (
       <>
         <Fragment set:html={readme?.code} />
-        <style is:inline>
-          .sl-markdown-content h1:first-of-type {
-            display: none;
-          }
+        <style
+          is:inline
+          set:text={`
+            .sl-markdown-content h1:first-of-type {
+              display: none;
+            }
 
-          .sl-markdown-content img {
-            display: inline-block;
-            vertical-align: text-bottom;
-          }
+            .sl-markdown-content img {
+              display: inline-block;
+              vertical-align: text-bottom;
+            }
 
-          .sl-markdown-content .octicon {
-            margin-right: 0.2rem;
-            overflow: visible !important;
-            -webkit-mask: var(--oct-icon) no-repeat;
-            mask: var(--oct-icon) no-repeat;
-            -webkit-mask-size: 100% 100%;
-            mask-size: 100% 100%;
-            background-color: currentColor;
-            color: inherit;
-            display: inline-block;
-            vertical-align: text-bottom;
-            width: 1em;
-            height: 1em;
-          }
+            .sl-markdown-content .octicon {
+              margin-right: 0.2rem;
+              overflow: visible !important;
+              -webkit-mask: var(--oct-icon) no-repeat;
+              mask: var(--oct-icon) no-repeat;
+              -webkit-mask-size: 100% 100%;
+              mask-size: 100% 100%;
+              background-color: currentColor;
+              color: inherit;
+              display: inline-block;
+              vertical-align: text-bottom;
+              width: 1em;
+              height: 1em;
+            }
 
-          .sl-markdown-content code {
-            white-space: pre-wrap;
-          }
-        </style>
+            .sl-markdown-content code {
+              white-space: pre-wrap;
+            }
+          `}
+        />
       </>
     )
   }
@@ -167,3 +139,4 @@ if (readme) {
 <script src="../globalJs/copy.ts"></script>
 <script src="../globalJs/tooltip.ts"></script>
 <script src="../globalJs/code-snippets.ts"></script>
+<script src="../globalJs/method-descriptions.ts"></script>

package/plugin/routes/DocsStatic.astro

@@ -2,7 +2,7 @@
 import type { GetStaticPaths } from 'astro';
 import Docs from './Docs.astro';
 import { cmsClient } from '../cms/client';
-import { generateDocsRoutes } from '../react/Routing';
+import { generateDocsRoutes } from '../helpers/generateDocsRoutes';
 
 export const getStaticPaths = (async () => {
   const spec = await cmsClient.getSpec();

package/plugin/routes/Overview.astro

@@ -1,24 +1,22 @@
 ---
 import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
-import { BASE_PATH, EXCLUDE_LANGUAGES } from 'virtual:stl-starlight-virtual-module';
+import { EXCLUDE_LANGUAGES } from 'virtual:stl-starlight-virtual-module';
 import { cmsClient } from '../cms/client';
-import type { DocsLanguage } from '@stainless-api/docs-ui/src/routing';
-
-import '@stainless-api/docs-ui/src/styles/resets.css';
-import '@stainless-api/docs-ui/src/styles/primitives.css';
-import '@stainless-api/docs-ui/src/styles/main.css';
-import '@stainless-api/docs-ui/src/styles/snippets.css';
-// TODO: fix variables.css import
-// import '../components/variables.css';
+import type { DocsLanguage } from '@stainless-api/docs-ui/routing';
 import { RenderLibraries, RenderSpecOverview, type SpecMetadata } from '../react/Routing';
 
 const spec = await cmsClient.getSpec();
 
 const languages: DocsLanguage[] = spec.docs!.languages ?? ['http'];
-const metadata = languages
+const metadata: SpecMetadata = languages
   .filter((language) => !['http', 'terraform'].includes(language) && spec.metadata[language])
   .filter((language) => !EXCLUDE_LANGUAGES.includes(language))
-  .map((language) => [language, spec.metadata[language]]) as SpecMetadata;
+  .map<SpecMetadata[number]>((language) => [language, spec.metadata[language]!]);
+
+// PageTitle override will skip rendering the default Starlight title
+Astro.locals._stlStarlightPage = {
+  hasMarkdownRoute: false,
+};
 ---
 
 <StarlightPage
@@ -26,15 +24,11 @@ const metadata = languages
     title: 'API Reference',
     pagefind: false,
     tableOfContents: false,
-    stainlessStarlight: {
-      basePath: BASE_PATH,
-      language: 'http',
-    },
   }}
 >
   <h3>Libraries</h3>
 
-  <div class="stldocs-root language-blocks stl-ui-not-prose">
+  <div class="stldocs-root language-blocks stl-ui-not-prose not-content">
     <RenderLibraries metadata={metadata} />
   </div>
 

package/plugin/routes/markdown.ts

@@ -1,13 +1,14 @@
 import type { APIRoute, GetStaticPaths } from 'astro';
 import { cmsClient } from '../cms/client';
-import { generateDocsRoutes, getReadmeContent } from '../react/Routing';
-import { getResourceFromSpec } from '@stainless-api/docs-ui/src/utils';
+import { getReadmeContent } from '../react/Routing';
+import { getResourceFromSpec } from '@stainless-api/docs-ui/utils';
 
-import { renderMarkdown } from '@stainless-api/docs-ui/src/markdown';
+import { renderMarkdown } from '@stainless-api/docs-ui/markdown';
 
-import { parseStainlessPath, type DocsLanguage } from '@stainless-api/docs-ui/src/routing';
-import type { EnvironmentType } from '@stainless-api/docs-ui/src/markdown/utils';
+import { parseStainlessPath, type DocsLanguage } from '@stainless-api/docs-ui/routing';
+import type { EnvironmentType } from '@stainless-api/docs-ui/markdown/utils';
 import { PROPERTY_SETTINGS, MIDDLEWARE } from 'virtual:stl-starlight-virtual-module';
+import { generateDocsRoutes } from '../helpers/generateDocsRoutes';
 
 type RouteProps = {
   stainlessPath: string;
@@ -26,7 +27,7 @@ export const GET: APIRoute<RouteProps> = async ({ props }) => {
   if (props.kind === 'readme') {
     const readmeContent = await getReadmeContent(spec, props.language);
     return new Response(readmeContent, {
-      headers: { 'Content-Type': 'text/markdown' },
+      headers: { 'Content-Type': 'text/plain' },
     });
   }
 
@@ -47,11 +48,11 @@ export const GET: APIRoute<RouteProps> = async ({ props }) => {
     },
   };
 
-  const target = props.kind === 'http_method' && parsed?.method ? resource.methods[parsed.method] : resource;
+  const target = props.kind === 'http_method' && parsed?.method ? resource.methods[parsed.method]! : resource;
   const output = renderMarkdown(env, target);
 
   return new Response(output, {
-    headers: { 'Content-Type': 'text/markdown' },
+    headers: { 'Content-Type': 'text/plain' },
   });
 };