feat: v4 docs

docs/astro.config.mjs

@@ -11,9 +11,6 @@ const BASE_DOCS_PATH = '/core';
 const docsVersion = process.env.DOCS_VERSION ?? 'local';
 const packagesDir = '../packages';
 
-const UPGRADE_BANNER_CONTENT =
-  'Still using <code>@dfinity/agent</code>? Migrate to <a href="/core/latest/upgrading/v4">@icp-sdk/core</a>!';
-
 // https://astro.build/config
 export default defineConfig({
   site: 'https://js.icp.build/',
@@ -37,16 +34,33 @@ export default defineConfig({
             exclude: [
               `${packagesDir}/core`,
               `${packagesDir}/migrate`,
+              `${packagesDir}/assets`,
+              `${packagesDir}/auth-client`,
+              `${packagesDir}/use-auth-client`,
             ],
           },
           frontmatter: {
             editUrl: false,
             next: true,
             prev: true,
-            banner: {
-              content: UPGRADE_BANNER_CONTENT,
-            },
           },
+          prependSidebar: [
+            {
+              label: 'Getting Started',
+              items: [
+                { label: 'Overview', link: '/' },
+                { label: 'Installation', link: '/installation' },
+                { label: 'Quick Start', link: '/quick-start' },
+                { label: 'Typescript', link: '/typescript' },
+              ],
+            },
+          ],
+          appendSidebar: [
+            {
+              label: 'Upgrading',
+              autogenerate: { directory: 'upgrading', collapsed: true },
+            },
+          ],
         }),
         additionalFilesPlugin({
           additionalFiles: [
@@ -58,9 +72,6 @@ export default defineConfig({
                 editUrl: false,
                 next: false,
                 prev: false,
-                banner: {
-                  content: UPGRADE_BANNER_CONTENT,
-                },
               },
             },
           ],
@@ -69,12 +80,6 @@ export default defineConfig({
           versionsJsonPath: `${BASE_DOCS_PATH}/versions.json`,
         }),
       ],
-      sidebar: [
-        {
-          label: 'Upgrading',
-          autogenerate: { directory: 'upgrading', collapsed: true },
-        },
-      ],
     }),
   ],
 });

docs/plugins/src/libs.ts

@@ -1,35 +1,30 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import {
-  Application,
-  ProjectReflection,
-  ReflectionKind,
-  type TypeDocOptions,
-} from "typedoc";
-import type { StarlightPlugin } from "@astrojs/starlight/types";
-import { type PluginOptions as TypeDocMarkdownOptions } from "typedoc-plugin-markdown";
-
-import { DOCS_DIR, TMP_DIR } from "./utils/constants.ts";
-import { type Frontmatter } from "./utils/types.ts";
-import { titleFromFilename, titleFromIdCapitalized } from "./utils/string.ts";
-import { processMarkdown } from "./utils/markdown.ts";
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { Application, ProjectReflection, ReflectionKind, type TypeDocOptions } from 'typedoc';
+import type { StarlightPlugin } from '@astrojs/starlight/types';
+import { type PluginOptions as TypeDocMarkdownOptions } from 'typedoc-plugin-markdown';
+
+import { DOCS_DIR, TMP_DIR } from './utils/constants.ts';
+import type { Frontmatter, Sidebar } from './utils/types.ts';
+import { titleFromFilename, titleFromIdCapitalized } from './utils/string.ts';
+import { processMarkdown } from './utils/markdown.ts';
 
 async function generateApiDocs({
   baseDir,
   typeDoc,
 }: LibsLoaderOptions): Promise<ProjectReflection> {
   const defaultTypeDocOptions: LibsLoaderTypeDocOptions = {
     entryPoints: [`${baseDir}/*`],
-    entryPointStrategy: "packages",
+    entryPointStrategy: 'packages',
     packageOptions: {
-      entryPoints: ["src/index.ts"],
-      tsconfig: "./tsconfig.json",
-      readme: "none",
+      entryPoints: ['src/index.ts'],
+      tsconfig: './tsconfig.json',
+      readme: 'none',
     },
-    plugin: ["typedoc-plugin-markdown", "typedoc-plugin-frontmatter"],
-    tsconfig: "./tsconfig.typedoc.json",
-    outputs: [{ name: "markdown", path: TMP_DIR }],
-    readme: "none",
+    plugin: ['typedoc-plugin-markdown', 'typedoc-plugin-frontmatter'],
+    tsconfig: './tsconfig.typedoc.json',
+    outputs: [{ name: 'markdown', path: TMP_DIR }],
+    readme: 'none',
     hidePageTitle: true,
     hideBreadcrumbs: true,
     hidePageHeader: true,
@@ -42,7 +37,7 @@ async function generateApiDocs({
 
   const project = await app.convert();
   if (!project) {
-    throw new Error("Failed to convert project with TypeDoc");
+    throw new Error('Failed to convert project with TypeDoc');
   }
   await app.generateOutputs(project);
 
@@ -84,25 +79,32 @@ export interface LibsLoaderOptions {
    * Frontmatter applied to every markdown file generated by TypeDoc.
    */
   frontmatter?: Frontmatter;
+
+  /**
+   * Sidebar items to add before the generated sidebar items.
+   */
+  prependSidebar?: Sidebar;
+
+  /**
+   * Sidebar items to add after the generated sidebar items.
+   */
+  appendSidebar?: Sidebar;
 }
 
 export type LibsLoaderTypeDocOptions = TypeDocMarkdownOptions & TypeDocOptions;
 
 export function libsPlugin(opts: LibsLoaderOptions): StarlightPlugin {
   return {
-    name: "@dfinity/starlight/libs",
+    name: '@dfinity/starlight/libs',
     hooks: {
-      async "config:setup"(ctx) {
+      async 'config:setup'(ctx) {
         const site = ctx.astroConfig.site;
         const baseDir = path.resolve(opts.baseDir.toString());
-        const outDir = path.resolve(
-          DOCS_DIR,
-          opts.outDir?.toString() ?? "libs",
-        );
+        const outDir = path.resolve(DOCS_DIR, opts.outDir?.toString() ?? 'libs');
         const clean = opts.clean ?? true;
 
         if (!site) {
-          throw new Error("Site URL is not defined in Astro config");
+          throw new Error('Site URL is not defined in Astro config');
         }
 
         if (clean) {
@@ -115,13 +117,13 @@ export function libsPlugin(opts: LibsLoaderOptions): StarlightPlugin {
         const librarySidebarItems = [];
         const modules = project.getChildrenByKind(ReflectionKind.Module);
         for (const { name } of modules) {
-          const id = name.startsWith("@") ? name.split("/")[1]! : name;
+          const id = name.startsWith('@') ? name.split('/')[1]! : name;
           const outputRootDir = path.resolve(outDir, id);
-          const outputApiDir = path.resolve(outputRootDir, "api");
+          const outputApiDir = path.resolve(outputRootDir, 'api');
           const title = titleFromIdCapitalized(id);
 
           await processMarkdown({
-            inputPath: path.resolve(baseDir, id, "README.md"),
+            inputPath: path.resolve(baseDir, id, 'README.md'),
             outputPath: path.resolve(outputRootDir, `index.md`),
             frontmatter: {
               title,
@@ -135,14 +137,12 @@ export function libsPlugin(opts: LibsLoaderOptions): StarlightPlugin {
             recursive: true,
           });
           for (const file of files) {
-            if (file.isFile() && file.name.endsWith(".md")) {
+            if (file.isFile() && file.name.endsWith('.md')) {
               const prefix = path.relative(apiSrcDir, file.parentPath);
               const inputFileName = file.name;
-              const isReadme = inputFileName.endsWith("README.md");
-              const outputFileName = isReadme ? "index.md" : inputFileName;
-              const title = isReadme
-                ? "Overview"
-                : titleFromFilename(file.name);
+              const isReadme = inputFileName.endsWith('README.md');
+              const outputFileName = isReadme ? 'index.md' : inputFileName;
+              const title = isReadme ? 'Overview' : titleFromFilename(file.name);
 
               await processMarkdown({
                 inputPath: path.resolve(apiSrcDir, prefix, inputFileName),
@@ -160,11 +160,11 @@ export function libsPlugin(opts: LibsLoaderOptions): StarlightPlugin {
             collapsed: true,
             items: [
               {
-                label: "Overview",
+                label: 'Overview',
                 link: `/libs/${id}`,
               },
               {
-                label: "API Reference",
+                label: 'API Reference',
                 collapsed: true,
                 autogenerate: {
                   collapsed: true,
@@ -177,8 +177,12 @@ export function libsPlugin(opts: LibsLoaderOptions): StarlightPlugin {
 
         ctx.updateConfig({
           sidebar: [
-            { label: "Overview", link: "/" },
-            { label: "Libraries", items: librarySidebarItems },
+            ...(opts.prependSidebar || []),
+            {
+              label: 'Modules',
+              items: librarySidebarItems,
+            },
+            ...(opts.appendSidebar || []),
             ...(ctx.config.sidebar || []),
           ],
         });

docs/plugins/src/markdown-urls.ts

@@ -1,90 +1,86 @@
-import { type AstroIntegrationLogger, type RemarkPlugins } from "astro";
-import { visit } from "unist-util-visit";
-import path from "node:path";
-import { type StarlightPlugin } from "@astrojs/starlight/types";
-import { DOCS_DIR } from "./utils/constants.ts";
-import { readdirSync } from "node:fs";
+import { type AstroIntegrationLogger, type RemarkPlugins } from 'astro';
+import { visit } from 'unist-util-visit';
+import path from 'node:path';
+import { type StarlightPlugin } from '@astrojs/starlight/types';
+import { DOCS_DIR } from './utils/constants.ts';
+import { readdirSync } from 'node:fs';
 
 type RemarkPlugin = RemarkPlugins[number];
 
-const markdownUrlsRemarkPlugin: RemarkPlugin = (
-  [logger, docsDir, site, baseUrl, crossPackageUrlRegex]: [
+const markdownUrlsRemarkPlugin: RemarkPlugin =
+  ([logger, docsDir, site, baseUrl, crossPackageUrlRegex]: [
     AstroIntegrationLogger,
     string,
     string,
     string,
     RegExp,
-  ],
-) =>
-(tree, file) => {
-  const currentFileDir = path.dirname(file.path);
+  ]) =>
+  (tree, file) => {
+    const currentFileDir = path.dirname(file.path);
 
-  visit(tree, "link", (node) => {
-    const url = node.url;
+    visit(tree, 'link', node => {
+      const url = node.url;
 
-    // take full URLs to the current site and make them relative
-    if (url.startsWith(site)) {
-      node.url = new URL(url).pathname;
-      return;
-    }
+      // take full URLs to the current site and make them relative
+      if (url.startsWith(site)) {
+        node.url = new URL(url).pathname;
+        return;
+      }
 
-    // skip any other full URLs
-    if (
-      url.startsWith("https://") ||
-      url.startsWith("/") ||
-      url.startsWith("http://") ||
-      url.startsWith("mailto:") ||
-      url.startsWith("#")
-    ) {
-      logger.debug(`Skipping URL: ${url}`);
-      return;
-    }
+      // skip any other full URLs
+      if (
+        url.startsWith('https://') ||
+        url.startsWith('/') ||
+        url.startsWith('http://') ||
+        url.startsWith('mailto:') ||
+        url.startsWith('#')
+      ) {
+        logger.debug(`Skipping URL: ${url}`);
+        return;
+      }
 
-    // if the url is a cross-package link, go back one level and add the api directory
-    const normalizedUrl = url.replace(crossPackageUrlRegex, '../../$1/api');
-    const absoluteLinkedFilePath = path.resolve(currentFileDir, normalizedUrl);
+      // if the url is a cross-package link, go back one level and add the api directory
+      const normalizedUrl = url.replace(crossPackageUrlRegex, '../../$1/api');
+      const absoluteLinkedFilePath = path.resolve(currentFileDir, normalizedUrl);
 
-    // normalize all other relative URLs to the docs directory
-    const relativeToDocs = path.relative(docsDir, absoluteLinkedFilePath);
-    const nodeUrl = `${baseUrl}${
-      relativeToDocs.replace(/(index)?\.mdx?(#.*)?$/, "$2").toLowerCase()
-    }`;
-    logger.debug(`Normalizing URL: ${url} -> ${nodeUrl}`);
+      // normalize all other relative URLs to the docs directory
+      const relativeToDocs = path.relative(docsDir, absoluteLinkedFilePath);
+      const nodeUrl = `${baseUrl}${relativeToDocs
+        .replace(/(index)?\.mdx?(#.*)?$/, '$2')
+        .toLowerCase()}`;
+      logger.debug(`Normalizing URL: ${url} -> ${nodeUrl}`);
 
-    node.url = nodeUrl;
-  });
-};
+      node.url = nodeUrl;
+    });
+  };
 
-interface MarkdownUrlsPluginOptions { 
+interface MarkdownUrlsPluginOptions {
   packagesDir: string;
 }
 
 export function markdownUrlsPlugin({ packagesDir }: MarkdownUrlsPluginOptions): StarlightPlugin {
   return {
-    name: "@dfinity/starlight/markdown-urls",
+    name: '@dfinity/starlight/markdown-urls',
     hooks: {
-      "config:setup": (ctx) => {
+      'config:setup': ctx => {
         const site = ctx.astroConfig.site;
 
         // get all the packages in the packagesDir
         const packages = readdirSync(packagesDir);
-        const crossPackageUrlRegex = new RegExp(`\\.\\.\\/(${packages.join('|')})`);
+        const crossPackageUrlRegex = new RegExp(`\\.\\.\\/(${packages.join('|')})/`);
 
         ctx.addIntegration({
-          name: "libs-astro-plugin",
+          name: 'libs-astro-plugin',
           hooks: {
-            "astro:config:setup": ({ updateConfig, config, logger }) => {
+            'astro:config:setup': ({ updateConfig, config, logger }) => {
               updateConfig({
                 markdown: {
                   remarkPlugins: [
                     ...config.markdown.remarkPlugins,
-                    [markdownUrlsRemarkPlugin, [
-                      logger,
-                      DOCS_DIR,
-                      site,
-                      ctx.astroConfig.base,
-                      crossPackageUrlRegex,
-                    ]],
+                    [
+                      markdownUrlsRemarkPlugin,
+                      [logger, DOCS_DIR, site, ctx.astroConfig.base, crossPackageUrlRegex],
+                    ],
                   ],
                 },
               });

docs/plugins/src/utils/types.ts

@@ -1,6 +1,7 @@
-import { docsSchema } from "@astrojs/starlight/schema";
-import type { z } from "astro/zod";
+import { docsSchema } from '@astrojs/starlight/schema';
+import { type StarlightUserConfig } from '@astrojs/starlight/types';
+import type { z } from 'astro/zod';
 
-export type Frontmatter = Partial<
-  z.infer<ReturnType<ReturnType<typeof docsSchema>>>
->;
+export type Frontmatter = Partial<z.infer<ReturnType<ReturnType<typeof docsSchema>>>>;
+
+export type Sidebar = StarlightUserConfig['sidebar'];