feat: next -> main

api/package.json

@@ -13,7 +13,6 @@
     "@octokit/graphql": "5.0.0",
     "@octokit/webhooks": "^13.2.7",
     "@shikijs/transformers": "1.12.1",
-    "@shikijs/twoslash": "^1.12.1",
     "@types/express": "^4.17.13",
     "@types/morgan": "^1.9.3",
     "@types/node": "^18.0.0",

api/src/bundler/plugins/rehype-code-blocks.ts

@@ -5,7 +5,6 @@ import {
   transformerNotationHighlight,
   transformerRemoveNotationEscape,
 } from "@shikijs/transformers";
-import { transformerTwoslash } from "@shikijs/twoslash";
 import type { Element } from "hast";
 import { toString } from "mdast-util-to-string";
 import * as shiki from "shiki";
@@ -54,10 +53,6 @@ export default function rehypeCodeBlocks(): (ast: Node) => void {
       transformerMetaHighlight(),
     ];
 
-    if (languageActual === "typescript") {
-      transformers.push(transformerTwoslash());
-    }
-
     parent.properties.html = highlighter.codeToHtml(raw, {
       lang: languageActual,
       theme: "css-variables",

api/src/config/models/favicon.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+
+export default z
+  .union([
+    z
+      .string()
+      .min(1), // Support for a single path
+    z.object({
+      light: z.string().optional(),
+      dark: z.string().optional(),
+    }),
+  ])
+  .optional()
+  .catch(undefined)
+  .transform((value) => {
+    // If a string is provided, use it for both light and dark
+    if (typeof value === "string") {
+      return { light: value, dark: value };
+    }
+
+    return value;
+  });

api/src/config/models/logo.ts

@@ -2,12 +2,10 @@ import { z } from "zod";
 
 export default z
   .object({
-    href: z.string().optional(),
     light: z.string().optional(),
     dark: z.string().optional(),
   })
   .catch({
-    href: undefined,
     light: undefined,
     dark: undefined,
   });

api/src/config/schema.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 
 import anchors from "./models/anchors";
 import content from "./models/content";
+import favicon from "./models/favicon";
 import header from "./models/header";
 import logo from "./models/logo";
 import scripts from "./models/scripts";
@@ -20,13 +21,13 @@ export const ConfigSchema = z
     name: z.string().min(1).optional().catch(undefined),
     // The description of the project
     description: z.string().min(1).optional().catch(undefined),
-    // The favicon of the project
-    favicon: z.string().min(1).optional().catch(undefined),
     // The preview image used in social media - either a path or a URL, or false to disable
     socialPreview: z
       .union([z.string().min(1), z.literal(false)])
       .optional()
       .catch(undefined),
+    // The favicon of the project
+    favicon,
     // The logo of the project, used in the header
     logo,
     // Theme settings

docs.json

@@ -1,8 +1,8 @@
 {
+  "$schema": "https://docs.page/schema.json",
   "name": "docs.page",
   "description": "Ship documentation, like you ship code",
   "logo": {
-    "href": "https://docs.page",
     "light": "https://static.invertase.io/assets/docs.page/docs-page-logo.png"
   },
   "favicon": "https://static.invertase.io/assets/docs.page/docs-page-logo.png",

docs/components/code-blocks.mdx

@@ -102,38 +102,3 @@ console.log('Focused') // [\!code focus]
 console.log('Not focused');
 ```
 ````
-
-### Typescript Support
-
-Out of the box, all code blocks will automatically be enhanced with rich type information when the code area is hovered.
-
-```ts
-type APIResponse<T> = {
-  data: T;
-  status: number;
-};
-
-export async function apiRequest(options: { url: string }) {
-  const response = await fetch(options.url);
-  const data = await response.json() as APIResponse<{ hello: 'world' }>;
-  return data;
-}
-```
-
-To enable this, ensure that the code block is tagged with the `typescript` (or `ts`) language:
-
-````
-```ts
-type APIResponse<T> = {
-  data: T;
-  status: number;
-};
-
-export async function apiRequest(options: { url: string }) {
-  const response = await fetch(options.url);
-  const data = await response.json() as APIResponse<{ hello: 'world' }>;
-  return data;
-}
-```
-````
-

docs/configuration.mdx

@@ -6,6 +6,14 @@ description: Configure your documentation with a docs.json file.
 Add a `docs.json` file to the root of your GitHub repository to configure your documentation.
 Below is a list of all available configuration options, which can be used to modify the logos, theme, analytics and more.
 
+If your IDE supports JSON Schemas, you can add a `$schema` property to your `docs.json` file to enable autocompletion and validation:
+
+```json title="docs.json"
+{
+  "$schema": "https://docs.page/schema.json"
+}
+```
+
 ## Properties
 
 ### Top-level properties
@@ -22,10 +30,24 @@ Below is a list of all available configuration options, which can be used to mod
 
 ---
 
-<Property name="favicon" type="string">
-  The favicon URL for your project.
+<Property name="favicon" type="string | Favicon">
+  Defines the favicon to show in the browser tab.
 
   See [Asset URLs](/assets) for more information on how to add assets to your documentation.
+
+  The favicon can either be a `string` value which will be used for both light and dark modes, or a `Favicon` object to define separate favicons for light and dark modes.
+
+  <Accordion title="Favicon">
+    <Property name="light" type="string">
+      The Asset URL of your favicon to display when the documentation is in light mode.
+    </Property>
+
+    ---
+
+    <Property name="dark" type="string">
+      The Asset URL of your favicon to display when the documentation is in dark mode.
+    </Property>
+  </Accordion>
 </Property>
 
 ---
@@ -45,17 +67,11 @@ Below is a list of all available configuration options, which can be used to mod
 <Property name="logo" type="Logo">
   Configures the logo of your documentation, which will be displayed in the header and used for social preview images.
 
-  The minimum height of the logo should be 24px.
+  The minimum height of the logo should be 24px. Note that if only a light or dark logo is provided, it will be used for both light and dark modes.
 
   See [Asset URLs](/assets) for more information on how to add assets to your documentation.
 
   <Accordion title="Logo">
-    <Property name="href" type="string">
-      If provided, the logo will be a link to this URL. By default, the logo will link to the root of your documentation.
-    </Property>
-
-    ---
-
     <Property name="light" type="string">
       The Asset URL of your logo to display when the documentation is in light mode.
     </Property>
@@ -202,10 +218,19 @@ Below is a list of all available configuration options, which can be used to mod
 
 ### Social Links
 
-<Property name="socialLinks" type="SocialLink[]">
-  An array of `SocialLink` objects to display in the footer of your documentation.
+<Property name="social" type="object">
+  An object of key value pairs where the key is the social platform and the value is the username/ID to link to:
+
+  ```
+  {
+    "social": {
+      "x": "@invertaseio",
+      "github": "invertase"
+    }
+  }
+  ```
 
-  <Accordion title="SocialLink">
+  <Accordion title="object">
     <Property name="website" type="string">
       A generic website URL to link to, such as your homepage or product.
     </Property>

domains.json

@@ -43,9 +43,6 @@
   ["utils.kishormainali.com", "kishormainali/fp_util"],
   ["docs.gazelle-dart.dev", "intales/gazelle"],
   ["docs.lamp-ic.fr", "TeddyVermeulin/lamp-doc"],
-  [	"thermion.dev", "nmfisher/thermion"],
-	[
-		"docs.thabit.ai",
-		"thabit-ai/thabit"
-	]
+  ["thermion.dev", "nmfisher/thermion"],
+  ["docs.thabit.ai", "thabit-ai/thabit"]
 ]

packages/cli/src/commands/init.ts

@@ -127,6 +127,7 @@ const jsonConfigurationSidebar = `[
 
 function jsonConfiguration({ sidebar }: { sidebar: boolean }) {
   return `{
+  "$schema": "https://docs.page/schema.json",
   "name": "My Docs",
   "description": "My documentation site",
   "sidebar": ${sidebar ? jsonConfigurationSidebar : "[]"}

website/app/components/Header.tsx

@@ -1,5 +1,5 @@
 import { SearchIcon } from "lucide-react";
-import { usePageContext, useTabs } from "~/context";
+import { useHref, usePageContext, useTabs } from "~/context";
 import { cn } from "~/utils";
 import { GitHubCard } from "./GitHubCard";
 import { Locale } from "./Locale";
@@ -19,7 +19,7 @@ export function Header(props: Props) {
   const showName = ctx.bundle.config.header?.showName ?? true;
 
   const name = ctx.bundle.config.name;
-  const logo = ctx.bundle.config.logo;
+  const logoHref = useHref("/");
 
   return (
     <header className="max-w-8xl mx-auto px-8 lg:px-10">
@@ -30,17 +30,14 @@ export function Header(props: Props) {
           </div>
         )}
 
-        <a
-          href={logo?.href || "/"}
-          className="flex-1 inline-flex items-center gap-3"
-        >
+        <a href={logoHref} className="flex-1 inline-flex items-center gap-3">
           <Logo />
           {showName && !!name && <span className="font-bold">{name}</span>}
         </a>
         <div className="hidden lg:block flex-1">
           <Search />
         </div>
-        <div className="flex-1 flex items-center justify-end pr-4 gap-8">
+        <div className="flex-1 flex items-center justify-end pr-4 gap-3 lg:gap-6">
           <Links />
           <RefBadge />
           <div className="hidden lg:block">
@@ -76,16 +73,19 @@ function Links() {
   }
 
   return (
-    <ul className="flex flex-row-reverse items-center gap-6">
+    <ul className="flex flex-row-reverse items-center gap-3 lg:gap-6">
       {links.map((link, index) => (
         <li key={index}>
           <a
             href={link.href}
-            className={cn("font-medium transition-all tracking-wide", {
-              "text-sm px-3 py-1 rounded-full bg-primary hover:bg-primary/90 text-white dark:bg-primary/10 border-[0.5px] dark:text-primary border-transparent dark:border-primary/60 hover:dark:border-primary":
-                link.cta,
-              "hover:text-primary": !link.cta,
-            })}
+            className={cn(
+              "font-medium transition-all tracking-wide whitespace-nowrap",
+              {
+                "text-sm px-3 py-1 rounded-full bg-primary hover:bg-primary/90 text-white dark:bg-primary/10 border-[0.5px] dark:text-primary border-transparent dark:border-primary/60 hover:dark:border-primary":
+                  link.cta,
+                "hover:text-primary": !link.cta,
+              },
+            )}
           >
             <span className="text-sm tracking-wide">{link.title}</span>
           </a>

website/app/entry.client.tsx

@@ -66,6 +66,6 @@ startTransition(() => {
     document,
     <StrictMode>
       <RemixBrowser />
-    </StrictMode>
+    </StrictMode>,
   );
 });

website/app/root.tsx

@@ -117,7 +117,7 @@ export default function App() {
       if (states.every((state) => state === "idle")) return "idle";
       return "loading";
     },
-    [navigation.state, fetchers]
+    [navigation.state, fetchers],
   );
 
   useEffect(() => {

website/app/routes/$/route.tsx

@@ -68,7 +68,12 @@ export const loader = async (args: LoaderFunctionArgs) => {
       url += redirectTo;
     }
 
-    console.log('Handling redirect', redirectTo, { owner, repository, ref, vanity, domain, environment }, url);
+    console.log(
+      "Handling redirect",
+      redirectTo,
+      { owner, repository, ref, vanity, domain, environment },
+      url
+    );
 
     throw redirect(url);
   }
@@ -117,13 +122,29 @@ export const meta: MetaFunction<typeof loader> = ({ data: ctx }) => {
     return descriptors;
   }
 
-  descriptors.push({
-    tagName: "link",
-    rel: "icon",
-    href: ctx.bundle.config.favicon
-      ? getAssetSrc(ctx, ctx.bundle.config.favicon)
-      : "/favicon.ico",
-  });
+  if (ctx.bundle.config.favicon?.light) {
+    descriptors.push({
+      tagName: "link",
+      rel: "icon",
+      media: ctx.bundle.config.favicon?.dark
+        ? // If there is a dark favicon, add a media query to prefer light mode only.
+          "(prefers-color-scheme: light)"
+        : undefined,
+      href: getAssetSrc(ctx, ctx.bundle.config.favicon.light),
+    });
+  }
+
+  if (ctx.bundle.config.favicon?.dark) {
+    descriptors.push({
+      tagName: "link",
+      rel: "icon",
+      media: ctx.bundle.config.favicon?.light
+        ? // If there is a light favicon, add a media query to prefer dark mode only.
+          "(prefers-color-scheme: dark)"
+        : undefined,
+      href: getAssetSrc(ctx, ctx.bundle.config.favicon.dark),
+    });
+  }
 
   // Add noindex meta tag if the frontmatter or config has noindex set to true.
   if (

website/app/routes/_layout._index/Demo.tsx

@@ -8,7 +8,12 @@ export function Demo() {
     <section className="max-w-5xl mx-auto pt-12 px-4">
       <div className="outline outline-[6px] md:outline-[12px] outline-white/5 rounded-md bg-black">
         {/* biome-ignore lint/a11y/useMediaCaption: <explanation> */}
-        <video ref={video} controls preload="metadata" className="w-full rounded-xl">
+        <video
+          ref={video}
+          controls
+          preload="metadata"
+          className="w-full rounded-xl"
+        >
           <source src="/docs-page-hero-video.webm#t=1" type="video/webm" />
         </video>
       </div>

website/app/routes/_layout.get-started/route.tsx

@@ -123,7 +123,10 @@ function AddContent() {
       }
       meta={
         <p>
-          <a href="https://use.docs.page/writing-content" className="  underline">
+          <a
+            href="https://use.docs.page/writing-content"
+            className="  underline"
+          >
             Write your documentation
           </a>{" "}
           using Markdown, adding new pages to your `docs` directory.