@raystack/chronicle 0.11.3 → 0.12.1

package/dist/cli/index.js

@@ -71,6 +71,29 @@ var init_image_utils = () => {};
 // src/lib/remark-resolve-images.ts
 import path4 from "node:path";
 import { visit } from "unist-util-visit";
+function parseImageParams(src) {
+  const qIdx = src.indexOf("?");
+  if (qIdx === -1)
+    return { base: src, params: {} };
+  const base = src.slice(0, qIdx);
+  const search = new URLSearchParams(src.slice(qIdx + 1));
+  const params = {};
+  if (search.has("w"))
+    params.w = Number.parseInt(search.get("w"), 10);
+  if (search.has("q"))
+    params.q = Number.parseInt(search.get("q"), 10);
+  return { base, params };
+}
+function appendParams(url, params) {
+  if (!params.w && !params.q)
+    return url;
+  const qs = new URLSearchParams;
+  if (params.w)
+    qs.set("w", String(params.w));
+  if (params.q)
+    qs.set("q", String(params.q));
+  return `${url}?${qs}`;
+}
 function resolveUrl(src, dir) {
   const normalized = src.replace(/\\/g, "/");
   if (/^[a-z][a-z0-9+\-.]*:/i.test(normalized))
@@ -86,9 +109,12 @@ function resolveUrl(src, dir) {
   return `/_content/${path4.posix.normalize(path4.posix.join(dir, normalized))}`;
 }
 function optimizeUrl(url, optimize) {
-  if (optimize && isLocalImage(url) && !isSvg(url))
-    return buildOptimizedUrl(url, DEFAULT_WIDTH);
-  return url;
+  const { base, params } = parseImageParams(url);
+  const width = params.w || DEFAULT_WIDTH;
+  const quality = params.q;
+  if (optimize && isLocalImage(base) && !isSvg(base))
+    return buildOptimizedUrl(base, width, quality);
+  return base;
 }
 var remarkResolveImages = (options) => {
   const optimize = options?.optimize ?? true;
@@ -112,15 +138,17 @@ var remarkResolveImages = (options) => {
     visit(tree, "image", (node) => {
       if (!node.url)
         return;
-      node.url = resolveUrl(node.url, dir);
-      collect(node.url);
-      node.url = optimizeUrl(node.url, optimize);
+      const { base, params } = parseImageParams(node.url);
+      const resolved = resolveUrl(base, dir);
+      collect(resolved);
+      node.url = optimizeUrl(appendParams(resolved, params), optimize);
     });
     visit(tree, "html", (node) => {
       node.value = node.value.replace(/(<img\b[^>]*\bsrc=["'])([^"']+)(["'])/gi, (_, before, src, after) => {
-        const resolved = resolveUrl(src, dir);
+        const { base, params } = parseImageParams(src);
+        const resolved = resolveUrl(base, dir);
         collect(resolved);
-        return `${before}${optimizeUrl(resolved, optimize)}${after}`;
+        return `${before}${optimizeUrl(appendParams(resolved, params), optimize)}${after}`;
       });
     });
     visit(tree, (node) => {
@@ -132,9 +160,10 @@ var remarkResolveImages = (options) => {
       const srcAttr = jsx.attributes.find((a) => a.type === "mdxJsxAttribute" && a.name === "src");
       if (!srcAttr?.value || typeof srcAttr.value !== "string")
         return;
-      srcAttr.value = resolveUrl(srcAttr.value, dir);
-      collect(srcAttr.value);
-      srcAttr.value = optimizeUrl(srcAttr.value, optimize);
+      const { base: jsxBase, params: jsxParams } = parseImageParams(srcAttr.value);
+      const jsxResolved = resolveUrl(jsxBase, dir);
+      collect(jsxResolved);
+      srcAttr.value = optimizeUrl(appendParams(jsxResolved, jsxParams), optimize);
     });
     visit(tree, "element", (node) => {
       if (node.tagName !== "img")
@@ -142,9 +171,10 @@ var remarkResolveImages = (options) => {
       const src = node.properties?.src;
       if (typeof src !== "string")
         return;
-      node.properties.src = resolveUrl(src, dir);
-      collect(node.properties.src);
-      node.properties.src = optimizeUrl(node.properties.src, optimize);
+      const { base: elBase, params: elParams } = parseImageParams(src);
+      const elResolved = resolveUrl(elBase, dir);
+      collect(elResolved);
+      node.properties.src = optimizeUrl(appendParams(elResolved, elParams), optimize);
     });
     file.data.images = images;
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raystack/chronicle",
-  "version": "0.11.3",
+  "version": "0.12.1",
   "description": "Config-driven documentation framework",
   "license": "Apache-2.0",
   "type": "module",

package/src/components/api/api-code-snippet.module.css

@@ -3,6 +3,7 @@
   border-radius: var(--rs-radius-2);
   overflow: hidden;
   width: 100%;
+  max-width: 100%;
 }
 
 .header {
@@ -20,4 +21,5 @@
 
 .body {
   background: var(--rs-color-background-base-primary);
+  overflow-x: auto;
 }

package/src/components/api/api-overview.module.css

@@ -60,6 +60,16 @@
 
   .left,
   .right {
+    min-width: 0;
+    max-width: 100%;
     width: 100%;
   }
 }
+
+@media (max-width: 768px) {
+  .layout {
+    gap: var(--rs-space-5);
+    padding-left: var(--rs-space-5);
+    padding-right: var(--rs-space-5);
+  }
+}

package/src/lib/remark-resolve-images.ts

@@ -7,6 +7,30 @@ import type { MdxJsxFlowElement, MdxJsxTextElement, MdxJsxAttribute } from 'mdas
 import { MdxNodeType } from './mdx-utils'
 import { isLocalImage, isSvg, buildOptimizedUrl, DEFAULT_WIDTH } from './image-utils'
 
+interface ImageParams {
+  w?: number
+  q?: number
+}
+
+function parseImageParams(src: string): { base: string; params: ImageParams } {
+  const qIdx = src.indexOf('?')
+  if (qIdx === -1) return { base: src, params: {} }
+  const base = src.slice(0, qIdx)
+  const search = new URLSearchParams(src.slice(qIdx + 1))
+  const params: ImageParams = {}
+  if (search.has('w')) params.w = Number.parseInt(search.get('w')!, 10)
+  if (search.has('q')) params.q = Number.parseInt(search.get('q')!, 10)
+  return { base, params }
+}
+
+function appendParams(url: string, params: ImageParams): string {
+  if (!params.w && !params.q) return url
+  const qs = new URLSearchParams()
+  if (params.w) qs.set('w', String(params.w))
+  if (params.q) qs.set('q', String(params.q))
+  return `${url}?${qs}`
+}
+
 function resolveUrl(src: string, dir: string): string {
   const normalized = src.replace(/\\/g, '/')
   if (/^[a-z][a-z0-9+\-.]*:/i.test(normalized)) return normalized
@@ -23,8 +47,11 @@ interface RemarkResolveImagesOptions {
 }
 
 function optimizeUrl(url: string, optimize: boolean): string {
-  if (optimize && isLocalImage(url) && !isSvg(url)) return buildOptimizedUrl(url, DEFAULT_WIDTH)
-  return url
+  const { base, params } = parseImageParams(url)
+  const width = params.w || DEFAULT_WIDTH
+  const quality = params.q
+  if (optimize && isLocalImage(base) && !isSvg(base)) return buildOptimizedUrl(base, width, quality)
+  return base
 }
 
 const remarkResolveImages: Plugin<[RemarkResolveImagesOptions?]> = (options) => {
@@ -50,18 +77,20 @@ const remarkResolveImages: Plugin<[RemarkResolveImagesOptions?]> = (options) =>
 
     visit(tree, 'image', (node: Image) => {
       if (!node.url) return
-      node.url = resolveUrl(node.url, dir)
-      collect(node.url)
-      node.url = optimizeUrl(node.url, optimize)
+      const { base, params } = parseImageParams(node.url)
+      const resolved = resolveUrl(base, dir)
+      collect(resolved)
+      node.url = optimizeUrl(appendParams(resolved, params), optimize)
     })
 
     visit(tree, 'html', (node: Html) => {
       node.value = node.value.replace(
         /(<img\b[^>]*\bsrc=["'])([^"']+)(["'])/gi,
         (_, before, src, after) => {
-          const resolved = resolveUrl(src, dir)
+          const { base, params } = parseImageParams(src)
+          const resolved = resolveUrl(base, dir)
           collect(resolved)
-          return `${before}${optimizeUrl(resolved, optimize)}${after}`
+          return `${before}${optimizeUrl(appendParams(resolved, params), optimize)}${after}`
         }
       )
     })
@@ -72,18 +101,20 @@ const remarkResolveImages: Plugin<[RemarkResolveImagesOptions?]> = (options) =>
       if (jsx.name !== 'img') return
       const srcAttr = jsx.attributes.find((a): a is MdxJsxAttribute => a.type === 'mdxJsxAttribute' && a.name === 'src')
       if (!srcAttr?.value || typeof srcAttr.value !== 'string') return
-      srcAttr.value = resolveUrl(srcAttr.value, dir)
-      collect(srcAttr.value)
-      srcAttr.value = optimizeUrl(srcAttr.value, optimize)
+      const { base: jsxBase, params: jsxParams } = parseImageParams(srcAttr.value)
+      const jsxResolved = resolveUrl(jsxBase, dir)
+      collect(jsxResolved)
+      srcAttr.value = optimizeUrl(appendParams(jsxResolved, jsxParams), optimize)
     })
 
     visit(tree, 'element', (node: Element) => {
       if (node.tagName !== 'img') return
       const src = node.properties?.src
       if (typeof src !== 'string') return
-      node.properties.src = resolveUrl(src, dir)
-      collect(node.properties.src as string)
-      node.properties.src = optimizeUrl(node.properties.src as string, optimize)
+      const { base: elBase, params: elParams } = parseImageParams(src)
+      const elResolved = resolveUrl(elBase, dir)
+      collect(elResolved)
+      node.properties.src = optimizeUrl(appendParams(elResolved, elParams), optimize)
     })
 
     file.data.images = images

package/src/server/api/image.test.ts

@@ -48,6 +48,12 @@ describe('cacheKey', () => {
     expect(a).not.toBe(b);
   });
 
+  test('returns different keys for different mtime', () => {
+    const a = cacheKey('/_content/img.png', 640, 75, 'webp', 1000);
+    const b = cacheKey('/_content/img.png', 640, 75, 'webp', 2000);
+    expect(a).not.toBe(b);
+  });
+
   test('key ends with format extension', () => {
     expect(cacheKey('/_content/img.png', 640, 75, 'webp')).toMatch(/\.webp$/);
     expect(cacheKey('/_content/img.png', 640, 75, 'avif')).toMatch(/\.avif$/);

package/src/server/api/image.ts

@@ -6,10 +6,9 @@ import { useStorage } from 'nitro/storage'
 import sharp from 'sharp'
 import { StatusCodes } from 'http-status-codes'
 import { safePath } from '@/server/utils/safe-path'
-import { ALLOWED_WIDTHS, ALLOWED_QUALITIES, DEFAULT_QUALITY } from '@/lib/image-utils'
+import { ALLOWED_WIDTHS, ALLOWED_QUALITIES, DEFAULT_WIDTH, DEFAULT_QUALITY, isLocalImage, isSvg } from '@/lib/image-utils'
 
-const STORAGE_KEY = 'image-cache'
-const MAX_CACHE_ENTRIES = 500
+export const STORAGE_KEY = 'image-cache'
 
 const inflight = new Map<string, Promise<Buffer>>()
 
@@ -29,8 +28,8 @@ export const MIME: Record<string, string> = {
   '.webp': 'image/webp',
 }
 
-export function cacheKey(url: string, w: number, q: number, format: OutputFormat): string {
-  const hash = crypto.createHash('sha256').update(`${url}:${w}:${q}:${format}`).digest('hex').slice(0, 16)
+export function cacheKey(url: string, w: number, q: number, format: OutputFormat, mtime?: number): string {
+  const hash = crypto.createHash('sha256').update(`${url}:${w}:${q}:${format}:${mtime ?? 0}`).digest('hex').slice(0, 16)
   return `${hash}.${format}`
 }
 
@@ -42,11 +41,17 @@ function snapQuality(q: number): number {
   return closest;
 }
 
-async function evictIfNeeded(storage: ReturnType<typeof useStorage>) {
-  const keys = await storage.getKeys()
-  if (keys.length <= MAX_CACHE_ENTRIES) return
-  const toRemove = keys.slice(0, keys.length - MAX_CACHE_ENTRIES)
-  await Promise.all(toRemove.map(k => storage.removeItem(k)))
+export async function optimizeImage(
+  filePath: string,
+  w: number,
+  q: number,
+  format: OutputFormat,
+): Promise<Buffer> {
+  const source = await fs.readFile(filePath);
+  const pipeline = sharp(source).resize({ width: w, withoutEnlargement: true });
+  if (format === 'avif') return pipeline.avif({ quality: q }).toBuffer();
+  if (format === 'webp') return pipeline.webp({ quality: q }).toBuffer();
+  return pipeline.toBuffer();
 }
 
 export default defineHandler(async event => {
@@ -90,7 +95,11 @@ export default defineHandler(async event => {
   const originalMime = MIME[ext] ?? 'application/octet-stream'
   const contentType = format === 'original' ? originalMime : `image/${format}`
 
-  const key = cacheKey(url, w, q, format)
+  const stat = await fs.stat(filePath).catch(() => null)
+  if (!stat) {
+    throw new HTTPError({ status: StatusCodes.NOT_FOUND, message: 'Not Found' })
+  }
+  const key = cacheKey(url, w, q, format, stat.mtimeMs)
 
   const cached = await storage.getItemRaw<Buffer>(key)
   if (cached) {
@@ -116,16 +125,8 @@ export default defineHandler(async event => {
   }
 
   const work = (async () => {
-    const source = await fs.readFile(filePath)
-    const pipeline = sharp(source).resize({ width: w, withoutEnlargement: true })
-    const optimized = format === 'avif'
-      ? await pipeline.avif({ quality: q }).toBuffer()
-      : format === 'webp'
-        ? await pipeline.webp({ quality: q }).toBuffer()
-        : await pipeline.toBuffer()
-
+    const optimized = await optimizeImage(filePath, w, q, format)
     await storage.setItemRaw(key, optimized)
-    await evictIfNeeded(storage)
     return optimized
   })()
 
@@ -154,3 +155,45 @@ export default defineHandler(async event => {
     inflight.delete(key)
   }
 })
+
+export async function warmupImageCache() {
+  const { getPages, getPageImages } = await import('@/lib/source');
+  // biome-ignore lint/correctness/useHookAtTopLevel: useStorage is a Nitro DI accessor, not a React hook
+  const storage = useStorage(STORAGE_KEY);
+  const contentDir = __CHRONICLE_CONTENT_DIR__;
+  const format = 'webp' as const;
+  const w = DEFAULT_WIDTH;
+  const q = DEFAULT_QUALITY;
+
+  const pages = await getPages();
+  const seen = new Set<string>();
+  let warmed = 0;
+
+  for (const page of pages) {
+    for (const url of getPageImages(page)) {
+      if (!isLocalImage(url) || isSvg(url) || seen.has(url)) continue;
+      seen.add(url);
+
+      const relativePath = url.replace(/^\/_content\//, '');
+      const filePath = safePath(contentDir, `/${relativePath}`);
+      if (!filePath) continue;
+
+      const stat = await fs.stat(filePath).catch(() => null);
+      if (!stat) continue;
+
+      const key = cacheKey(url, w, q, format, stat.mtimeMs);
+      const cached = await storage.getItemRaw(key);
+      if (cached) continue;
+
+      try {
+        const optimized = await optimizeImage(filePath, w, q, format);
+        await storage.setItemRaw(key, optimized);
+        warmed++;
+      } catch { /* skip unprocessable */ }
+    }
+  }
+
+  if (warmed > 0) {
+    console.log(`[image-warmup] cached ${warmed} images as webp@${w}w`);
+  }
+}

package/src/server/api/ready.ts

@@ -1,9 +1,11 @@
 import { defineHandler } from 'nitro';
 import { ensureIndex, isSearchReady } from './search';
+import { warmupImageCache } from './image';
 import { LATEST_CONTEXT } from '@/lib/version-source';
 
 export default defineHandler(async () => {
   ensureIndex(LATEST_CONTEXT).catch(e => console.error('[search:index]', e));
+  warmupImageCache().catch(e => console.error('[image-warmup]', e));
 
   if (!isSearchReady()) {
     return new Response(JSON.stringify({ status: 'not_ready', search: false }), {

package/src/themes/default/Layout.module.css

@@ -76,7 +76,9 @@
 
 .topLinks {
   width: 100%;
-  margin-bottom: var(--rs-space-7);
+  display: flex;
+  flex-direction: column;
+  gap: 0;
 }
 
 .topLinkItem {
@@ -135,7 +137,7 @@
 .cardWrapper {
   flex: 1;
   display: flex;
-  padding: 0 0 var(--rs-space-2) 0;
+  padding: 0;
   min-height: 0;
   background: var(--rs-color-background-base-secondary);
 }
@@ -154,7 +156,7 @@
   align-items: center;
   justify-content: space-between;
   height: var(--navbar-height);
-  padding: var(--rs-space-4) var(--rs-space-7);
+  padding: var(--rs-space-4) var(--rs-space-8);
   background: var(--rs-color-background-base-primary);
   border-bottom: 0.5px solid var(--rs-color-border-base-primary);
   backdrop-filter: blur(1px);
@@ -172,7 +174,7 @@
 
 .groupItems {
   padding-left: 0;
-  padding-bottom: var(--rs-space-3);
+  padding-bottom: 0;
   gap: 0;
 }
 
@@ -190,6 +192,9 @@
 
 .navGroup .navGroupHeader {
   margin: 0;
+  margin-bottom: 0;
+  padding-top: 0;
+  padding-bottom: 0;
 }
 
 .navGroup[data-depth='1'] .navGroupHeader {
@@ -283,3 +288,121 @@
   line-height: var(--rs-line-height-mini);
   flex-shrink: 0;
 }
+
+.mobileMenuBtn {
+  display: none;
+  align-items: center;
+  justify-content: center;
+  background: none;
+  border: none;
+  cursor: pointer;
+  padding: var(--rs-space-1);
+  color: var(--rs-color-foreground-base-primary);
+}
+
+.mobileHeader {
+  display: none;
+  align-items: center;
+  justify-content: space-between;
+  height: var(--navbar-height);
+  padding: 0 var(--rs-space-5);
+  background: var(--rs-color-background-base-primary);
+  border-bottom: 0.5px solid var(--rs-color-border-base-primary);
+  backdrop-filter: blur(1px);
+}
+
+.mobileMenu {
+  display: none;
+  position: fixed;
+  top: var(--navbar-height);
+  left: 0;
+  right: 0;
+  bottom: 0;
+  z-index: 100;
+  background: var(--rs-color-background-base-primary);
+  overflow-y: auto;
+  padding: var(--rs-space-7) var(--rs-space-5);
+}
+
+.mobileMenuFooter {
+  margin-top: var(--rs-space-7);
+  padding-top: var(--rs-space-5);
+  border-top: 0.5px solid var(--rs-color-border-base-primary);
+}
+
+.mobileNav {
+  display: none;
+}
+
+@media (max-width: 768px) {
+  .sidebar {
+    display: none;
+  }
+
+  .mobileHeader {
+    display: flex;
+  }
+
+  .mobileMenuBtn {
+    display: flex;
+  }
+
+  .mobileMenu[data-open='true'] {
+    display: block;
+  }
+
+  .subNav {
+    display: none;
+  }
+
+  .content {
+    padding: var(--rs-space-10) var(--rs-space-5);
+  }
+
+  .card {
+    width: 100%;
+    border-left: none;
+    box-shadow: none;
+  }
+
+  .cardWrapper {
+    padding: 0;
+  }
+
+  .mobileNav {
+    display: flex;
+    gap: var(--rs-space-10);
+    padding: var(--rs-space-3) var(--rs-space-5);
+    background: var(--rs-color-background-base-primary);
+  }
+
+  .mobileNavLink {
+    flex: 1;
+    display: flex;
+    align-items: center;
+    gap: var(--rs-space-3);
+    padding: var(--rs-space-4) var(--rs-space-3);
+    border: 0.5px solid var(--rs-color-border-base-primary);
+    border-radius: var(--rs-radius-4);
+    text-decoration: none;
+    font-family: var(--rs-font-body);
+    font-size: var(--rs-font-size-regular);
+    font-weight: var(--rs-font-weight-medium);
+    line-height: var(--rs-line-height-regular);
+    letter-spacing: var(--rs-letter-spacing-regular);
+    color: var(--rs-color-foreground-base-tertiary);
+    min-width: 0;
+  }
+
+  .mobileNavLink[data-direction='next'] {
+    justify-content: flex-end;
+    background: var(--rs-color-background-base-secondary);
+    color: var(--rs-color-foreground-base-primary);
+  }
+
+  .mobileNavLabel {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+}

package/src/themes/default/Layout.tsx

@@ -4,7 +4,9 @@ import {
   CodeBracketSquareIcon,
   RectangleStackIcon,
   DocumentTextIcon,
-  Squares2X2Icon
+  Squares2X2Icon,
+  Bars3Icon,
+  XMarkIcon
 } from '@heroicons/react/24/outline';
 import { Flex, IconButton, Button, Sidebar } from '@raystack/apsara';
 import { PlayIcon } from '@radix-ui/react-icons';
@@ -60,8 +62,6 @@ function renderConfigIcon(
   return <img src={icon} alt={alt} className={styles.configIcon} />;
 }
 
-let savedScrollTop = 0;
-
 export function Layout({
   children,
   config,
@@ -73,6 +73,7 @@ export function Layout({
   const navigate = useNavigate();
   const { page, version } = usePageContext();
   const scrollRef = useRef<HTMLDivElement>(null);
+  const [mobileSidebarOpen, setMobileSidebarOpen] = useState(false);
   const isApiRoute = pathname === '/apis' || pathname.startsWith('/apis/');
   const isApiBase = (basePath: string) =>
     pathname === basePath || pathname.startsWith(`${basePath}/`);
@@ -94,25 +95,95 @@ export function Layout({
   );
 
   useEffect(() => {
-    const el = scrollRef.current;
-    if (!el) return;
-    const onScroll = () => {
-      savedScrollTop = el.scrollTop;
-    };
-    el.addEventListener('scroll', onScroll);
-    return () => el.removeEventListener('scroll', onScroll);
-  }, []);
-
-  useEffect(() => {
-    const el = scrollRef.current;
-    if (el)
-      requestAnimationFrame(() => {
-        el.scrollTop = savedScrollTop;
-      });
+    const timer = setTimeout(() => {
+      const container = document.querySelector<HTMLElement>(`.${styles.sidebarMain}`);
+      if (!container) return;
+      const allActive = container.querySelectorAll<HTMLElement>('[data-active="true"]');
+      const activeItem = allActive[allActive.length - 1];
+      if (!activeItem) return;
+      const containerRect = container.getBoundingClientRect();
+      const itemRect = activeItem.getBoundingClientRect();
+      if (itemRect.top < containerRect.top || itemRect.bottom > containerRect.bottom) {
+        container.scrollTop += itemRect.top - containerRect.top - containerRect.height / 2 + itemRect.height / 2;
+      }
+    }, 100);
+    setMobileSidebarOpen(false);
+    return () => clearTimeout(timer);
   }, [pathname]);
 
   return (
     <Flex direction='column' className={cx(styles.layout, classNames?.layout)}>
+      <div className={styles.mobileHeader}>
+        <SidebarLogo config={config} />
+        <Flex align='center' gap={3}>
+          {config.search?.enabled && <Search />}
+          <ClientThemeSwitcher size={16} />
+          {!hideSidebar && (
+            <button
+              type='button'
+              className={styles.mobileMenuBtn}
+              onClick={() => setMobileSidebarOpen(o => !o)}
+              aria-label={mobileSidebarOpen ? 'Close menu' : 'Open menu'}
+              aria-expanded={mobileSidebarOpen}
+              aria-controls='mobile-menu'
+            >
+              {mobileSidebarOpen
+                ? <XMarkIcon width={16} height={16} />
+                : <Bars3Icon width={16} height={16} />}
+            </button>
+          )}
+        </Flex>
+      </div>
+      <div id='mobile-menu' className={styles.mobileMenu} data-open={!hideSidebar && mobileSidebarOpen}>
+        {showTopLinks ? (
+          <div className={styles.topLinks}>
+            {contentEntries.map(entry => (
+              <Sidebar.Item
+                key={entry.href}
+                href={entry.href}
+                active={activeContentDir === entry.contentDir}
+                leadingIcon={renderConfigIcon(entry.icon, entry.label, <DocumentTextIcon width={16} height={16} />)}
+                classNames={{ root: styles.topLinkItem, text: styles.topLinkText }}
+                render={<RouterLink to={entry.href} />}
+              >
+                {entry.label}
+              </Sidebar.Item>
+            ))}
+            {apiEntries.map(api => (
+              <Sidebar.Item
+                key={`${api.basePath}-${api.name}`}
+                href={api.basePath}
+                active={isApiBase(api.basePath)}
+                leadingIcon={renderConfigIcon(api.icon, api.name, <CodeBracketSquareIcon width={16} height={16} />)}
+                classNames={{ root: styles.topLinkItem, text: styles.topLinkText }}
+                render={<RouterLink to={api.basePath} />}
+              >
+                {api.name} API
+              </Sidebar.Item>
+            ))}
+          </div>
+        ) : null}
+        {tree.children.map((item, i) => (
+          isApiRoute ? (
+            <ApiSidebarNode
+              key={item.type === 'page' ? item.url : (item.name?.toString() ?? i)}
+              item={item}
+              pathname={pathname}
+            />
+          ) : (
+            <SidebarNode
+              key={item.type === 'page' ? item.url : (item.name?.toString() ?? i)}
+              item={item}
+              pathname={pathname}
+            />
+          )
+        ))}
+        {config.versions?.length ? (
+          <div className={styles.mobileMenuFooter}>
+            <VersionSwitcher />
+          </div>
+        ) : null}
+      </div>
       <Flex className={cx(styles.body, classNames?.body)}>
         {hideSidebar ? null : (
           <Sidebar
@@ -221,6 +292,20 @@ export function Layout({
               <main className={cx(styles.content, classNames?.content)}>
                 {children}
               </main>
+              <div className={styles.mobileNav}>
+                {prev ? (
+                  <RouterLink to={prev.url} className={styles.mobileNavLink}>
+                    <ArrowLeftIcon width={16} height={16} />
+                    <span className={styles.mobileNavLabel}>{prev.title}</span>
+                  </RouterLink>
+                ) : <div />}
+                {next ? (
+                  <RouterLink to={next.url} className={styles.mobileNavLink} data-direction='next'>
+                    <span className={styles.mobileNavLabel}>{next.title}</span>
+                    <ArrowRightIcon width={16} height={16} />
+                  </RouterLink>
+                ) : <div />}
+              </div>
             </div>
           </div>
         </Flex>
@@ -347,6 +432,7 @@ function ApiSidebarNode({ item, pathname }: { item: Node; pathname: string }) {
       align='center'
       gap={3}
       className={`${styles.apiItem} ${isActive ? styles.apiItemActive : ''}`}
+      data-active={isActive}
       render={<RouterLink to={href} />}
     >
       <span className={styles.apiItemName}>{item.name}</span>

package/src/themes/default/Page.module.css

@@ -184,3 +184,17 @@
 .headerLoader {
   margin-bottom: var(--rs-space-5);
 }
+
+@media (max-width: 768px) {
+  .page {
+    gap: var(--rs-space-5);
+  }
+
+  .article {
+    max-width: 100%;
+  }
+
+  .title {
+    margin-bottom: var(--rs-space-5);
+  }
+}