@stainless-api/docs 0.1.0-beta.4 → 0.1.0-beta.41

package/stl-docs/components/pagination/util.ts

@@ -0,0 +1,71 @@
+import type { StarlightRouteData } from '@astrojs/starlight/route-data';
+import { getCollection } from 'astro:content';
+
+export type SidebarEntry = StarlightRouteData['sidebar'][number];
+export type SidebarLink = Extract<SidebarEntry, { type: 'link' }>;
+export type SidebarGroup = Extract<SidebarEntry, { type: 'group' }>;
+
+export const flattenSidebar = (sidebar: SidebarEntry[]): SidebarLink[] =>
+  sidebar.flatMap((e) => (e.type === 'group' ? flattenSidebar(e.entries) : e));
+
+function findParentOfSidebarEntry(sidebar: SidebarEntry[], targetEntry: SidebarEntry): SidebarGroup | null {
+  for (const entry of sidebar) {
+    if (entry.type === 'group') {
+      if (entry.entries.includes(targetEntry)) {
+        return entry;
+      }
+      const foundInChild = findParentOfSidebarEntry(entry.entries, targetEntry);
+      if (foundInChild) {
+        return foundInChild;
+      }
+    }
+  }
+  return null;
+}
+
+export async function getPrevNextPage(page: StarlightRouteData, paginationEnabled: boolean) {
+  // TODO: respect user `next` / `prev` config from frontmatter the way starlight does
+
+  if (!paginationEnabled) return null;
+
+  const docsContent = await getCollection('docs');
+  const findSidebarLinkInContent = (link: SidebarLink) =>
+    docsContent.find((doc) => {
+      if (doc.id === 'index' && link.href === '/') return true;
+      return doc.id === link.href.replace(/^\//, '').replace(/\/$/, '');
+    });
+
+  const currentSidebar = page.sidebar;
+
+  const paginationSequence: (SidebarLink & { description?: string })[] = flattenSidebar(currentSidebar)
+    // Remove injected stl-mobile-only-sidebar-item links - TODO: better solution for this
+    .filter((link) => !(link.attrs.class ?? '').trim().split(/\s+/).includes('stl-mobile-only-sidebar-item'))
+    // Remove data-stldocs-method links from pagination sequence
+    .filter((link) => !link.attrs['data-stldocs-method'])
+    // Map data-stldocs-overview=readme links so that their name is not just “Overview”
+    .map((link) => {
+      if (link.attrs['data-stldocs-overview'] && link.label === 'Overview') {
+        const parent = findParentOfSidebarEntry(currentSidebar, link);
+        if (parent) return { ...link, label: parent.label };
+      }
+      return link;
+    })
+    .map((link) => {
+      const contentEntry = findSidebarLinkInContent(link);
+      if (contentEntry) return { ...link, description: contentEntry.data.description };
+      return link;
+    });
+
+  const currentIndex = paginationSequence.findIndex((e) => e.isCurrent);
+  if (currentIndex === -1) return null;
+
+  const prevIndex = currentIndex > 0 ? currentIndex - 1 : null;
+  const nextIndex = currentIndex < paginationSequence.length - 1 ? currentIndex + 1 : null;
+  const prevSidebarEntry = prevIndex !== null ? (paginationSequence[prevIndex] ?? null) : null;
+  const nextSidebarEntry = nextIndex !== null ? (paginationSequence[nextIndex] ?? null) : null;
+
+  return {
+    prev: prevSidebarEntry,
+    next: nextSidebarEntry,
+  };
+}

package/stl-docs/components/scripts.ts

@@ -0,0 +1 @@
+export * from '@stainless-api/ui-primitives/scripts';

package/stl-docs/components/{Sidebar.astro → sidebars/BaseSidebar.astro}

@@ -1,11 +1,10 @@
 ---
 import Default from '@astrojs/starlight/components/Sidebar.astro';
-import SDKSelect from '../../plugin/components/SDKSelect.astro';
-import HeaderLinks from './headers/HeaderLinks.astro';
+import HeaderLinks from '../headers/HeaderLinks.astro';
 ---
 
 <div class="stl-sidebar-header-links">
   <HeaderLinks />
 </div>
-<SDKSelect />
+<slot name="sdk-select" />
 <Default><slot /></Default>

package/stl-docs/components/sidebars/SDKSelectSidebar.astro

@@ -0,0 +1,8 @@
+---
+import BaseSidebar from './BaseSidebar.astro';
+import SDKSelect from '../../../plugin/components/SDKSelect.astro';
+---
+
+<BaseSidebar>
+  <SDKSelect slot="sdk-select" />
+</BaseSidebar>

package/stl-docs/disableCalloutSyntax.ts

@@ -0,0 +1,36 @@
+import type { AstroIntegration } from 'astro';
+import type { StarlightPlugin } from '@astrojs/starlight/types';
+
+export const disableCalloutSyntaxAstroIntegration = {
+  name: 'stl-starlight-remove-callout-syntax',
+  hooks: {
+    'astro:config:setup': ({ config: astroConfig }) => {
+      // Remove starlight callout syntax in favor of our own callout component
+      // updateConfig always deeply merges arrays so we need to mutate remarkPlugins directly
+      // in order to remove plugins that starlight added
+      astroConfig.markdown.remarkPlugins = astroConfig.markdown.remarkPlugins.filter((plugin, i, arr) => {
+        if (typeof plugin !== 'function') return true;
+        // remove:
+        // 1. remarkDirective plugin
+        if (plugin.name === 'remarkDirective') return false;
+        // 2. directly followed by remarkAsides plugin (inner function named 'attacher')
+        if (plugin.name === 'attacher') {
+          const prev = arr[i - 1];
+          if (typeof prev === 'function' && prev.name === 'remarkDirective') return false;
+        }
+        // 3. remarkDirectivesRestoration plugin
+        if (plugin.name === 'remarkDirectivesRestoration') return false;
+        return true;
+      });
+    },
+  },
+} satisfies AstroIntegration;
+
+export const disableCalloutSyntaxStarlightPlugin = {
+  name: 'stl-starlight-remove-callout-syntax',
+  hooks: {
+    'config:setup': ({ addIntegration }) => {
+      addIntegration(disableCalloutSyntaxAstroIntegration);
+    },
+  },
+} satisfies StarlightPlugin;

package/stl-docs/index.ts

@@ -1,6 +1,8 @@
 import starlight from '@astrojs/starlight';
 import react from '@astrojs/react';
+import type { StarlightPlugin } from '@astrojs/starlight/types';
 import { stainlessStarlight } from '../plugin';
+import { disableCalloutSyntaxStarlightPlugin } from './disableCalloutSyntax';
 
 import type { AstroIntegration } from 'astro';
 
@@ -16,11 +18,15 @@ import {
   type StarlightSidebarConfig,
 } from './loadStlDocsConfig';
 import { buildVirtualModuleString } from '../shared/virtualModule';
-
-import geistPath from '../plugin/assets/fonts/geist/geist-latin.woff2?url';
+import type * as StlDocsVirtualModule from 'virtual:stl-docs-virtual-module';
+import { resolveSrcFile } from '../resolveSrcFile';
+import { stainlessDocsMarkdownRenderer } from './proseMarkdown/proseMarkdownIntegration';
+import { setSharedLogger } from '../shared/getSharedLogger';
 
 export * from '../plugin';
 
+const COMPONENTS_FOLDER = '/stl-docs/components';
+
 function stainlessDocsStarlightIntegration(config: NormalizedStainlessDocsConfig) {
   // We transform our tabs into a Starlight sidebar
   // This gives them all the built-in features of Starlight (eg. auto-generated entries by directory)
@@ -41,13 +47,34 @@ function stainlessDocsStarlightIntegration(config: NormalizedStainlessDocsConfig
 
   type ComponentOverrides = StarlightConfigDefined['components'];
   const componentOverrides: ComponentOverrides = {
-    Search: '@stainless-api/docs/Search',
-    Sidebar: '@stainless-api/docs/Sidebar',
-    Header: '@stainless-api/docs/Header',
-    ThemeSelect: '@stainless-api/docs/ThemeSelect',
-    ContentPanel: '@stainless-api/docs/ContentPanel',
+    Sidebar: resolveSrcFile(COMPONENTS_FOLDER, './sidebars/BaseSidebar.astro'),
+    Header: resolveSrcFile(COMPONENTS_FOLDER, './Header.astro'),
+    Head: resolveSrcFile(COMPONENTS_FOLDER, './Head.astro'),
+    ThemeSelect: resolveSrcFile(COMPONENTS_FOLDER, './ThemeSelect.astro'),
+    ContentPanel: resolveSrcFile(COMPONENTS_FOLDER, './content-panel/ContentPanel.astro'),
+    TableOfContents: resolveSrcFile(COMPONENTS_FOLDER, './TableOfContents.astro'),
+    PageTitle: resolveSrcFile(COMPONENTS_FOLDER, './PageTitle.astro'),
+    Pagination: resolveSrcFile(COMPONENTS_FOLDER, './pagination/Pagination.astro'),
   };
 
+  const plugins: StarlightPlugin[] = [
+    // Disable starlight callout syntax in favor of our own component
+    disableCalloutSyntaxStarlightPlugin,
+  ];
+
+  if (config.apiReference !== null) {
+    plugins.push(
+      stainlessStarlight({
+        ...config.apiReference,
+        contextMenu: config.contextMenu,
+      }),
+    );
+    componentOverrides.Sidebar = resolveSrcFile(COMPONENTS_FOLDER, './sidebars/SDKSelectSidebar.astro');
+    componentOverrides.Search = resolveSrcFile('/plugin/components/search/Search.astro');
+  }
+
+  plugins.push(...config.starlightCompat.plugins);
+
   // TODO: re-add once we figure out what to do with the client router
   // if (config.enableClientRouter) {
   //   // logger.info(`Client router is enabled`);
@@ -79,33 +106,27 @@ function stainlessDocsStarlightIntegration(config: NormalizedStainlessDocsConfig
         setupNavLinksInitial();
       `,
       },
-      // TODO: for users who are overriding the font stack in their own styles, how can we know that
-      // and preload their font instead of ours?
-      {
-        tag: 'link',
-        attrs: {
-          rel: 'preload',
-          as: 'font',
-          type: 'font/woff2',
-          crossorigin: 'anonymous',
-          href: geistPath,
-        },
-      },
     ],
-    routeMiddleware: [...config.starlightCompat.routeMiddleware, '@stainless-api/docs/tabsMiddleware'],
-    customCss: ['@stainless-api/docs/theme', ...config.customCss],
-    plugins: [stainlessStarlight(config.apiReference), ...config.starlightCompat.plugins],
+    routeMiddleware: [
+      ...config.starlightCompat.routeMiddleware,
+      resolveSrcFile('/stl-docs/tabsMiddleware.ts'),
+    ],
+    customCss: [resolveSrcFile('/theme.css'), ...config.customCss],
+    plugins,
   });
 }
 
-function stainlessDocsIntegration(config: NormalizedStainlessDocsConfig): AstroIntegration {
-  const virtualId = `virtual:stl-stl-starlight-virtual-module`;
+function stainlessDocsIntegration(
+  config: NormalizedStainlessDocsConfig,
+  apiReferenceBasePath: string | null,
+): AstroIntegration {
+  const virtualId = `virtual:stl-docs-virtual-module`;
   // The '\0' prefix tells Vite “this is a virtual module” and prevents it from being resolved again.
   const resolvedId = `\0${virtualId}`;
   let redirects: NormalizedRedirectConfig | null = null;
 
   return {
-    name: 'stl-docs-integration',
+    name: 'stl-docs-astro',
     hooks: {
       'astro:config:setup': ({ updateConfig, command, config: astroConfig }) => {
         // // we only handle redirects for builds
@@ -132,7 +153,12 @@ function stainlessDocsIntegration(config: NormalizedStainlessDocsConfig): AstroI
                       HEADER_LINKS: config.header.links,
                       HEADER_LAYOUT: config.header.layout,
                       ENABLE_CLIENT_ROUTER: config.enableClientRouter,
-                    });
+                      API_REFERENCE_BASE_PATH: apiReferenceBasePath,
+                      ENABLE_PROSE_MARKDOWN_RENDERING: config.enableProseMarkdownRendering,
+                      // TODO: do not duplicate this between both virtual modules
+                      ENABLE_CONTEXT_MENU: config.contextMenu,
+                      RENDER_PAGE_DESCRIPTIONS: config.renderPageDescriptions,
+                    } satisfies typeof StlDocsVirtualModule);
                   }
                 },
               },
@@ -158,6 +184,17 @@ function stainlessDocsIntegration(config: NormalizedStainlessDocsConfig): AstroI
   };
 }
 
+function sharedLoggerIntegration(): AstroIntegration {
+  return {
+    name: 'stainless',
+    hooks: {
+      'astro:config:setup': ({ logger }) => {
+        setSharedLogger(logger);
+      },
+    },
+  };
+}
+
 export function stainlessDocs(config: StainlessDocsUserConfig) {
   const normalizedConfigResult = parseStlDocsConfig(config);
   if (normalizedConfigResult.result === 'error') {
@@ -166,9 +203,21 @@ export function stainlessDocs(config: StainlessDocsUserConfig) {
     process.exit(1);
   }
   const normalizedConfig = normalizedConfigResult.config;
+
+  // TODO: need to refactor this, but this allows us to get the base path for the API reference _if_ it exists
+  // if it doesn't exist, the value of basePath is null.
+  // the stl-starlight virtual module has base path, but it's not available when there's no API reference
+  const hasApiReference = normalizedConfig.apiReference !== null;
+  let apiReferenceBasePath: string | null = null;
+  if (hasApiReference) {
+    apiReferenceBasePath = normalizedConfig.apiReference?.basePath ?? '/api';
+  }
+
   return [
+    sharedLoggerIntegration(), // this **must** be first so it can set the shared logger used by our other integrations
     react(),
     stainlessDocsStarlightIntegration(normalizedConfig),
-    stainlessDocsIntegration(normalizedConfig),
+    stainlessDocsIntegration(normalizedConfig, apiReferenceBasePath),
+    stainlessDocsMarkdownRenderer({ enabled: normalizedConfig.enableProseMarkdownRendering }),
   ];
 }

package/stl-docs/loadStlDocsConfig.ts

@@ -45,7 +45,8 @@ type Tabs = {
   sidebar?: SidebarEntry[];
   /**
    * Whether to hide the tab in the tab bar.
-   * Defaults to `false`.
+   *
+   * @default false
    */
   hidden?: boolean;
 }[];
@@ -58,7 +59,7 @@ export type HeaderLink = {
 };
 
 export type StainlessDocsUserConfig = {
-  apiReference: StainlessStarlightUserConfig;
+  apiReference?: StainlessStarlightUserConfig;
   tabs?: Tabs;
   header?: {
     layout?: HeaderLayout;
@@ -67,7 +68,26 @@ export type StainlessDocsUserConfig = {
   experimental?: {
     starlightCompat?: ExperimentalStarlightCompatibilityConfig;
     enableClientRouter?: boolean;
+    /**
+     * Disable markdown rendering for prose content. Only disable this if it is causing issues.
+     *
+     * @default false
+     */
+    disableProseMarkdownRendering?: boolean;
   };
+  /**
+   * Whether to show the context menu with options like "Copy as Markdown" and "Open in ChatGPT".
+   *
+   * @default true
+   */
+  contextMenu?: boolean;
+
+  /**
+   * Whether to render page descriptions in prose page headers
+   *
+   * @default true
+   */
+  renderPageDescriptions?: boolean;
 } & PassThroughStarlightConfigOptions;
 
 type HeaderLayout = 'default' | 'stacked';
@@ -119,6 +139,12 @@ function normalizeConfig(userConfig: StainlessDocsUserConfig) {
       description: userConfig.description,
       tagline: userConfig.tagline,
       logo: userConfig.logo,
+      favicon: userConfig.favicon,
+      disable404Route: userConfig.disable404Route,
+      editLink: userConfig.editLink,
+      locales: userConfig.locales,
+      lastUpdated: userConfig.lastUpdated,
+      pagination: userConfig.pagination,
     },
     starlightCompat: {
       components: userConfig.experimental?.starlightCompat?.components ?? {},
@@ -126,8 +152,12 @@ function normalizeConfig(userConfig: StainlessDocsUserConfig) {
       routeMiddleware: normalizeRouteMiddleware(userConfig),
     },
     enableClientRouter: userConfig.experimental?.enableClientRouter ?? false,
-    apiReference: userConfig.apiReference,
+    apiReference: userConfig.apiReference ?? null,
     sidebar: userConfig.sidebar,
+    enableProseMarkdownRendering:
+      userConfig.experimental?.disableProseMarkdownRendering === true ? false : true,
+    contextMenu: userConfig.contextMenu ?? true,
+    renderPageDescriptions: userConfig.renderPageDescriptions ?? true,
   };
 
   return configWithDefaults;
@@ -136,11 +166,11 @@ function normalizeConfig(userConfig: StainlessDocsUserConfig) {
 export type NormalizedStainlessDocsConfig = ReturnType<typeof normalizeConfig>;
 
 /*
- The goal of the code in this file is to take a user's config and normalize it. 
+ The goal of the code in this file is to take a user's config and normalize it.
  Specifically: we want a single complete config format used throughout the internals of the plugin.
 
  We've tried to avoid any config values being optional/undefined. To accomplish this:
- - Any optional config values should have their defaults set here: eg. basePath defaults to /api 
+ - Any optional config values should have their defaults set here: eg. basePath defaults to /api
  - If a field is only used in certain contexts, we make each context a discriminated union (see SpecRetrieverConfig)
  - We prefer empty arrays over undefined/null
 */

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;
+}