astro-better-cards 0.2.6 → 1.0.1

package/CardGrid.astro

@@ -0,0 +1,17 @@
+---
+interface Props {
+  columns?: 1 | 2 | 3 | 4;
+}
+
+const { columns = 2 } = Astro.props;
+const colClasses: Record<number, string> = {
+  1: 'grid-cols-1',
+  2: 'grid-cols-1 lg:grid-cols-2',
+  3: 'grid-cols-1 md:grid-cols-2 lg:grid-cols-3',
+  4: 'grid-cols-1 md:grid-cols-2 lg:grid-cols-4',
+};
+const colClass = colClasses[columns] ?? colClasses[2];
+---
+<div class={`gap-6 mt-6 mb-6 grid ${colClass} not-prose`} xmlns="http://www.w3.org/1999/xhtml">
+  <slot />
+</div>

package/ChildCards.astro

@@ -6,23 +6,27 @@ import Card from './Card.astro';
 interface Props {
   collection?: string;
   folder?: string;
-  depth?: 1 | 2;
+  depth?: 1 | 2 | 3 | 4;
+  columns?: 1 | 2 | 3 | 4;
+  variant?: 'full' | 'compact' | 'quickstart';
 }
 
-const { collection = 'docs', folder, depth = 1 } = Astro.props;
+const { collection = 'docs', folder, variant = 'full' } = Astro.props;
+// coerce so depth={2} and depth="2" both work
+const depth = Number(Astro.props.depth ?? 1) as 1 | 2 | 3 | 4;
+const columns = Number(Astro.props.columns ?? 2) as 1 | 2 | 3 | 4;
 
 const pages = await getCollection(collection as any);
 
-// Compute collection-relative prefix (no leading/trailing slashes, no extension)
 let prefix: string;
 if (folder !== undefined) {
   if (folder.startsWith('/')) {
     const noSlash = folder.replace(/^\/+/, '');
     prefix = noSlash.startsWith(`${collection}/`) ? noSlash.slice(collection.length + 1) : noSlash;
   } else if (folder.startsWith('./') || folder.startsWith('../')) {
-    const pathname = Astro.url.pathname.replace(/^\/+|\/+\(/g, '').replace(/\.html\)/, '');
+    const pathname = Astro.url.pathname.replace(/^\/+|\/+$/g, '').replace(/\.html$/, '');
     const pagePrefix = pathname.startsWith(`${collection}/`) ? pathname.slice(collection.length + 1) : pathname;
-    const pageFolder = pagePrefix.includes('/') ? pagePrefix.replace(/\/[^/]+\$/, '') : '';
+    const pageFolder = pagePrefix.includes('/') ? pagePrefix.replace(/\/[^/]+$/, '') : '';
     const parts = pageFolder ? pageFolder.split('/') : [];
     for (const seg of folder.split('/')) {
       if (seg === '..') parts.pop();
@@ -33,48 +37,56 @@ if (folder !== undefined) {
     prefix = folder;
   }
 } else {
-  const pathname = Astro.url.pathname.replace(/^\/+|\/+\(/g, '').replace(/\.html\)/, '');
+  const pathname = Astro.url.pathname.replace(/^\/+|\/+$/g, '').replace(/\.html$/, '');
   if (pathname === '' || pathname === collection) {
     prefix = '';
   } else {
     prefix = pathname.startsWith(`${collection}/`) ? pathname.slice(collection.length + 1) : pathname;
   }
 }
-prefix = prefix.replace(/^\/+|\/+\$/g, '');
+prefix = prefix.replace(/^\/+|\/+$/g, '');
+
+const remark = new Marked();
+const md = (s: string) => remark.parseInline(s) as Promise<string>;
+
+const valid = (pages as any[]).filter(p => !p.data.excludeFromNav && p.data.route !== false);
 
 function stripExt(id: string): string {
-  return id.replace(/\.(md|mdx)\$/i, '');
+  return id.replace(/\.(md|mdx)$/i, '');
 }
 
-function isDirectChild(id: string): boolean {
+// returns path segments relative to prefix, or null if not under prefix
+function getRem(id: string): string[] | null {
   const cid = stripExt(id);
-  if (!prefix) return !cid.includes('/') && cid !== 'index';
-  if (!cid.startsWith(`${prefix}/`)) return false;
-  const rem = cid.slice(prefix.length + 1);
-  return rem.length > 0 && !rem.includes('/') && rem !== 'index';
+  const rem = prefix ? (cid.startsWith(`${prefix}/`) ? cid.slice(prefix.length + 1) : null) : cid;
+  if (!rem) return null;
+  return rem.split('/');
 }
 
-function isGrandchildPage(id: string): boolean {
-  const cid = stripExt(id);
-  if (!prefix) {
-    const parts = cid.split('/');
-    return parts.length === 2 && parts[1] !== 'index';
-  }
-  if (!cid.startsWith(`${prefix}/`)) return false;
-  const rem = cid.slice(prefix.length + 1);
-  const parts = rem.split('/');
-  return parts.length === 2 && parts[1] !== 'index';
+function isAtDepth(id: string, d: number): boolean {
+  const parts = getRem(id);
+  if (!parts) return false;
+  return parts.length === d && parts[parts.length - 1] !== 'index';
 }
 
-function getSubfolder(id: string): string {
-  if (!prefix) return stripExt(id).split('/')[0];
-  return stripExt(id).slice(prefix.length + 1).split('/')[0];
+function findIndexPage(relPath: string) {
+  return (pages as any[]).find(p => {
+    const cid = stripExt(p.id);
+    const target = prefix ? `${prefix}/${relPath}` : relPath;
+    return cid === target || cid === `${target}/index`;
+  });
 }
 
-const remark = new Marked();
-const md = (s: string) => remark.parseInline(s) as Promise<string>;
+async function getGroupTitle(relPath: string, fallback: string): Promise<string> {
+  const entry = findIndexPage(relPath);
+  return entry
+    ? (await md(entry.data.title) as string)
+    : fallback.replace(/-/g, ' ').replace(/\b\w/g, (c: string) => c.toUpperCase());
+}
 
-const valid = (pages as any[]).filter(p => !p.data.excludeFromNav && p.data.route !== false);
+function getGroupOrder(relPath: string): number {
+  return findIndexPage(relPath)?.data.order ?? 1000;
+}
 
 type NavItem = {
   href: string;
@@ -87,58 +99,103 @@ type NavItem = {
   badges?: string[];
 };
 
-type NavGroup = { title: string; order: number; items: NavItem[] };
+type Group = {
+  key: string;
+  title: string;
+  order: number;
+  items: NavItem[];
+  subgroups: Group[];
+};
 
-let items: NavItem[] = [];
-let groups: NavGroup[] = [];
+const colClasses: Record<number, string> = {
+  1: 'grid-cols-1',
+  2: 'grid-cols-1 lg:grid-cols-2',
+  3: 'grid-cols-1 md:grid-cols-2 lg:grid-cols-3',
+  4: 'grid-cols-1 md:grid-cols-2 lg:grid-cols-4',
+};
+const colClass = colClasses[columns] ?? colClasses[2];
 
-if (depth === 1) {
-  const children = valid.filter(p => isDirectChild(p.id));
-  children.sort((a, b) => (a.data.order ?? 1000) - (b.data.order ?? 1000) || a.data.title.localeCompare(b.data.title));
-  items = await Promise.all(children.map(async p => ({
-    // FIX: Replaced `/${collection}/` with a single `/`
-    href: `/${stripExt(p.id).replace(/\/index$/, '')}`,
-    title: await md(p.data.title),
+async function pageToItem(p: any): Promise<NavItem> {
+  return {
+    href: `/${collection}/${stripExt(p.id).replace(/\/index$/, '')}`,
+    title: await md(p.data.title) as string,
     description: p.data.description,
     icon: p.data.icon ?? null,
     darkIcon: p.data.darkIcon,
     cardImage: p.data.cardImage,
     version: p.data.version,
     badges: p.data.badges,
-  })));
+  };
+}
+
+let items: NavItem[] = [];
+let groups: Group[] = [];
+
+if (depth === 1) {
+  const children = valid.filter(p => isAtDepth(p.id, 1));
+  children.sort((a, b) => (a.data.order ?? 1000) - (b.data.order ?? 1000) || a.data.title.localeCompare(b.data.title));
+  items = await Promise.all(children.map(pageToItem));
 } else {
-  const grandchildren = valid.filter(p => isGrandchildPage(p.id));
-  const subfolderNames = [...new Set(grandchildren.map(p => getSubfolder(p.id)))];
-
-  groups = await Promise.all(subfolderNames.map(async sf => {
-    const indexId = prefix ? `${prefix}/${sf}` : sf;
-    const indexEntry = (pages as any[]).find(p => {
-      const cid = stripExt(p.id);
-      return cid === indexId || cid === `${indexId}/index`;
-    });
-    const sectionTitle: string = indexEntry
-      ? await md(indexEntry.data.title)
-      : sf.replace(/-/g, ' ').replace(/\b\w/g, (c: string) => c.toUpperCase());
-    const sectionOrder: number = indexEntry?.data.order ?? 1000;
-
-    const sfItems = grandchildren.filter(p => getSubfolder(p.id) === sf);
-    sfItems.sort((a, b) => (a.data.order ?? 1000) - (b.data.order ?? 1000) || a.data.title.localeCompare(b.data.title));
-
-    return {
-      title: sectionTitle,
-      order: sectionOrder,
-      items: await Promise.all(sfItems.map(async p => ({
-        // FIX: Replaced `/${collection}/` with a single `/`
-        href: `/${stripExt(p.id)}`,
-        title: await md(p.data.title),
-        description: p.data.description,
-        icon: p.data.icon ?? null,
-        darkIcon: p.data.darkIcon,
-        cardImage: p.data.cardImage,
-        version: p.data.version,
-        badges: p.data.badges,
-      }))),
-    };
+  const pagesAtDepth = valid.filter(p => isAtDepth(p.id, depth));
+
+  const topMap = new Map<string, any[]>();
+  for (const p of pagesAtDepth) {
+    const topKey = getRem(p.id)![0];
+    if (!topMap.has(topKey)) topMap.set(topKey, []);
+    topMap.get(topKey)!.push(p);
+  }
+
+  groups = await Promise.all([...topMap.keys()].map(async topKey => {
+    const topTitle = await getGroupTitle(topKey, topKey);
+    const topOrder = getGroupOrder(topKey);
+    const topPages = topMap.get(topKey)!;
+
+    if (depth === 2) {
+      topPages.sort((a, b) => (a.data.order ?? 1000) - (b.data.order ?? 1000) || a.data.title.localeCompare(b.data.title));
+      return { key: topKey, title: topTitle, order: topOrder, items: await Promise.all(topPages.map(pageToItem)), subgroups: [] };
+    }
+
+    const midMap = new Map<string, any[]>();
+    for (const p of topPages) {
+      const midKey = getRem(p.id)![1];
+      if (!midMap.has(midKey)) midMap.set(midKey, []);
+      midMap.get(midKey)!.push(p);
+    }
+
+    const subgroups: Group[] = await Promise.all([...midMap.keys()].map(async midKey => {
+      const midRelPath = `${topKey}/${midKey}`;
+      const midTitle = await getGroupTitle(midRelPath, midKey);
+      const midOrder = getGroupOrder(midRelPath);
+      const midPages = midMap.get(midKey)!;
+
+      if (depth === 3) {
+        midPages.sort((a, b) => (a.data.order ?? 1000) - (b.data.order ?? 1000) || a.data.title.localeCompare(b.data.title));
+        return { key: midKey, title: midTitle, order: midOrder, items: await Promise.all(midPages.map(pageToItem)), subgroups: [] };
+      }
+
+      // depth === 4
+      const botMap = new Map<string, any[]>();
+      for (const p of midPages) {
+        const botKey = getRem(p.id)![2];
+        if (!botMap.has(botKey)) botMap.set(botKey, []);
+        botMap.get(botKey)!.push(p);
+      }
+
+      const subsubgroups: Group[] = await Promise.all([...botMap.keys()].map(async botKey => {
+        const botRelPath = `${topKey}/${midKey}/${botKey}`;
+        const botTitle = await getGroupTitle(botRelPath, botKey);
+        const botOrder = getGroupOrder(botRelPath);
+        const botPages = botMap.get(botKey)!;
+        botPages.sort((a, b) => (a.data.order ?? 1000) - (b.data.order ?? 1000) || a.data.title.localeCompare(b.data.title));
+        return { key: botKey, title: botTitle, order: botOrder, items: await Promise.all(botPages.map(pageToItem)), subgroups: [] };
+      }));
+      subsubgroups.sort((a, b) => a.order - b.order);
+
+      return { key: midKey, title: midTitle, order: midOrder, items: [], subgroups: subsubgroups };
+    }));
+
+    subgroups.sort((a, b) => a.order - b.order);
+    return { key: topKey, title: topTitle, order: topOrder, items: [], subgroups };
   }));
 
   groups.sort((a, b) => a.order - b.order);
@@ -146,26 +203,72 @@ if (depth === 1) {
 ---
 
 {depth === 1 ? (
-  <div class="gap-6 mt-6 mb-6 grid grid-cols-1 not-prose lg:grid-cols-2" xmlns="http://www.w3.org/1999/xhtml">
+  // xmlns prevents Astro's MDX renderer from treating children as markdown
+  <div class={`gap-6 mt-6 mb-6 grid ${colClass} not-prose`} xmlns="http://www.w3.org/1999/xhtml">
     {items.map(item => (
       <Card href={item.href} title={item.title} description={item.description}
         icon={item.icon} darkIcon={item.darkIcon} cardImage={item.cardImage}
-        version={item.version} badges={item.badges} variant="full" />
+        version={item.version} badges={item.badges} variant={variant} />
     ))}
   </div>
-) : (
+) : depth === 2 ? (
   <div class="mb-6">
     {groups.map(group => (
       <Fragment>
         <h2 class="mt-10 mb-2 text-xl font-semibold not-prose" set:html={group.title} />
-        <div class="gap-6 grid grid-cols-1 not-prose lg:grid-cols-2" xmlns="http://www.w3.org/1999/xhtml">
+        <div class={`gap-6 grid ${colClass} not-prose`} xmlns="http://www.w3.org/1999/xhtml">
           {group.items.map(item => (
             <Card href={item.href} title={item.title} description={item.description}
               icon={item.icon} darkIcon={item.darkIcon} cardImage={item.cardImage}
-              version={item.version} badges={item.badges} variant="full" />
+              version={item.version} badges={item.badges} variant={variant} />
           ))}
         </div>
       </Fragment>
     ))}
   </div>
+) : depth === 3 ? (
+  <div class="mb-6">
+    {groups.map(group => (
+      <Fragment>
+        <h2 class="mt-10 mb-2 text-xl font-semibold not-prose" set:html={group.title} />
+        {group.subgroups.map(sub => (
+          <Fragment>
+            <h3 class="mt-6 mb-2 text-lg font-semibold not-prose" set:html={sub.title} />
+            <div class={`gap-6 grid ${colClass} not-prose`} xmlns="http://www.w3.org/1999/xhtml">
+              {sub.items.map(item => (
+                <Card href={item.href} title={item.title} description={item.description}
+                  icon={item.icon} darkIcon={item.darkIcon} cardImage={item.cardImage}
+                  version={item.version} badges={item.badges} variant={variant} />
+              ))}
+            </div>
+          </Fragment>
+        ))}
+      </Fragment>
+    ))}
+  </div>
+) : (
+  <div class="mb-6">
+    {groups.map(group => (
+      <Fragment>
+        <h2 class="mt-10 mb-2 text-xl font-semibold not-prose" set:html={group.title} />
+        {group.subgroups.map(sub => (
+          <Fragment>
+            <h3 class="mt-6 mb-2 text-lg font-semibold not-prose" set:html={sub.title} />
+            {sub.subgroups.map(subsub => (
+              <Fragment>
+                <h4 class="mt-4 mb-2 text-base font-semibold not-prose" set:html={subsub.title} />
+                <div class={`gap-6 grid ${colClass} not-prose`} xmlns="http://www.w3.org/1999/xhtml">
+                  {subsub.items.map(item => (
+                    <Card href={item.href} title={item.title} description={item.description}
+                      icon={item.icon} darkIcon={item.darkIcon} cardImage={item.cardImage}
+                      version={item.version} badges={item.badges} variant={variant} />
+                  ))}
+                </div>
+              </Fragment>
+            ))}
+          </Fragment>
+        ))}
+      </Fragment>
+    ))}
+  </div>
 )}

package/PageNav.astro

@@ -4,26 +4,39 @@ import { Marked } from 'marked';
 
 interface Props {
   collection?: string;
-  currentId: string;
-  nextPage?: string;
-  lastPage?: string;
+  prev?: string;
+  next?: string;
 }
 
-const { collection = 'docs', currentId, nextPage, lastPage } = Astro.props;
+const { collection = 'docs', prev: prevProp, next: nextProp } = Astro.props;
 
 const pages = await getCollection(collection as any);
 const remark = new Marked();
 
-const currentClean = currentId.replace(/\.(md|mdx)$/i, '');
-const currentFolder = currentClean.includes('/') ? currentClean.replace(/\/[^/]+$/, '') : '';
-
 function stripExt(id: string): string {
   return id.replace(/\.(md|mdx)$/i, '');
 }
 
+const pathname = Astro.url.pathname.replace(/^\/+|\/+$/g, '').replace(/\.html$/, '');
+// strip the collection URL prefix so the remainder matches bare entry IDs
+const pathnameRelative = pathname.startsWith(`${collection}/`)
+  ? pathname.slice(collection.length + 1)
+  : pathname;
+const currentFolder = pathnameRelative.includes('/')
+  ? pathnameRelative.replace(/\/[^/]+$/, '')
+  : '';
+
+const currentEntry = (pages as any[]).find(p => {
+  const cid = stripExt(p.id);
+  return cid === pathnameRelative || cid === `${pathnameRelative}/index`;
+});
+
+const prevPath = prevProp ?? currentEntry?.data.prev;
+const nextPath = nextProp ?? currentEntry?.data.next;
+
 function findPage(href: string) {
   const target = href.startsWith('/')
-    ? href.replace(new RegExp(`^\\/${collection}\\/`), '')
+    ? href.replace(new RegExp(`^\\/${collection}\\/`), '').replace(/^\//, '')
     : currentFolder ? `${currentFolder}/${href}` : href;
   return (pages as any[]).find(p => {
     const cid = stripExt(p.id);
@@ -36,36 +49,61 @@ function makeHref(href: string): string {
   return `/${collection}/${currentFolder ? `${currentFolder}/` : ''}${href}`;
 }
 
-const nextEntry = nextPage ? findPage(nextPage) : null;
-const lastEntry = lastPage ? findPage(lastPage) : null;
+let prevEntry = prevPath ? findPage(prevPath) : null;
+let prevHref: string | null = prevPath ? makeHref(prevPath) : null;
 
-const nextTitle: string | null = nextEntry ? await remark.parseInline(nextEntry.data.title) as string : null;
-const lastTitle: string | null = lastEntry ? await remark.parseInline(lastEntry.data.title) as string : null;
+let nextEntry = nextPath ? findPage(nextPath) : null;
+let nextHref: string | null = nextPath ? makeHref(nextPath) : null;
 
-const nextHref = nextPage ? makeHref(nextPage) : null;
-const lastHref = lastPage ? makeHref(lastPage) : null;
+// fall back to sibling order when prev/next not specified via prop or frontmatter
+if (!prevEntry || !nextEntry) {
+  const siblings = (pages as any[])
+    .filter(p => {
+      if (p.data.excludeFromNav || p.data.route === false) return false;
+      const cid = stripExt(p.id);
+      const pFolder = cid.includes('/') ? cid.replace(/\/[^/]+$/, '') : '';
+      const lastSeg = cid.split('/').pop()!;
+      return pFolder === currentFolder && lastSeg !== 'index';
+    })
+    .sort((a, b) => (a.data.order ?? 1000) - (b.data.order ?? 1000) || a.data.title.localeCompare(b.data.title));
+
+  const idx = siblings.findIndex(p => stripExt(p.id) === pathname);
+  if (idx > 0 && !prevEntry) {
+    prevEntry = siblings[idx - 1];
+    prevHref = `/${collection}/${stripExt(prevEntry.id).replace(/\/index$/, '')}`;
+  }
+  if (idx >= 0 && idx < siblings.length - 1 && !nextEntry) {
+    nextEntry = siblings[idx + 1];
+    nextHref = `/${collection}/${stripExt(nextEntry.id).replace(/\/index$/, '')}`;
+  }
+}
+
+const prevTitle: string | null = prevEntry ? await remark.parseInline(prevEntry.data.title) as string : null;
+const nextTitle: string | null = nextEntry ? await remark.parseInline(nextEntry.data.title) as string : null;
 ---
 
 <nav class="not-prose mt-10 pt-6 border-t border-slate-200 dark:border-slate-700" aria-label="Page navigation">
   <div class="grid grid-cols-2 gap-4">
-    {lastEntry ? (
-      <a href={lastHref}
-        class="group flex flex-col gap-1 rounded-lg border border-slate-200 dark:border-slate-700 p-4 no-underline hover:border-indigo-500 dark:hover:border-indigo-400 transition-colors">
-        <span class="flex items-center gap-1 text-xs font-semibold uppercase tracking-wide text-slate-400 dark:text-slate-500">
-          <span aria-hidden="true">&larr;</span> Previous
-        </span>
-        <span class="text-sm font-medium text-slate-800 dark:text-slate-200 group-hover:text-indigo-600 dark:group-hover:text-indigo-400"
-          set:html={lastTitle} />
+    {prevEntry ? (
+      <a href={prevHref}
+        class="group flex items-center gap-3 rounded-lg border border-slate-200 dark:border-slate-700 px-4 py-3 no-underline hover:border-indigo-500 dark:hover:border-indigo-400 transition-colors">
+        <span class="text-2xl leading-none text-slate-300 dark:text-slate-600 group-hover:text-indigo-500 dark:group-hover:text-indigo-400 transition-colors shrink-0" aria-hidden="true">&larr;</span>
+        <div class="min-w-0">
+          <div class="text-xs font-semibold uppercase tracking-wide text-slate-400 dark:text-slate-500">Previous</div>
+          <div class="text-sm font-medium text-slate-800 dark:text-slate-200 group-hover:text-indigo-600 dark:group-hover:text-indigo-400 truncate"
+            set:html={prevTitle} />
+        </div>
       </a>
     ) : <div />}
     {nextEntry ? (
       <a href={nextHref}
-        class="group flex flex-col gap-1 rounded-lg border border-slate-200 dark:border-slate-700 p-4 text-right no-underline hover:border-indigo-500 dark:hover:border-indigo-400 transition-colors">
-        <span class="flex items-center justify-end gap-1 text-xs font-semibold uppercase tracking-wide text-slate-400 dark:text-slate-500">
-          Next <span aria-hidden="true">&rarr;</span>
-        </span>
-        <span class="text-sm font-medium text-slate-800 dark:text-slate-200 group-hover:text-indigo-600 dark:group-hover:text-indigo-400"
-          set:html={nextTitle} />
+        class="group flex items-center justify-end gap-3 rounded-lg border border-slate-200 dark:border-slate-700 px-4 py-3 text-right no-underline hover:border-indigo-500 dark:hover:border-indigo-400 transition-colors">
+        <div class="min-w-0">
+          <div class="text-xs font-semibold uppercase tracking-wide text-slate-400 dark:text-slate-500">Next</div>
+          <div class="text-sm font-medium text-slate-800 dark:text-slate-200 group-hover:text-indigo-600 dark:group-hover:text-indigo-400 truncate"
+            set:html={nextTitle} />
+        </div>
+        <span class="text-2xl leading-none text-slate-300 dark:text-slate-600 group-hover:text-indigo-500 dark:group-hover:text-indigo-400 transition-colors shrink-0" aria-hidden="true">&rarr;</span>
       </a>
     ) : <div />}
   </div>

package/README.md

@@ -30,8 +30,10 @@ import Card from 'astro-better-cards/Card.astro';
 | `cardImage` | `string` | — | Hero image URL |
 | `variant` | `'full' \| 'compact' \| 'quickstart'` | `'full'` | Display style |
 | `comingSoon` | `boolean` | `false` | Greys out the card |
-| `label` | `string` | — | Small label text (e.g. `'->'`) |
+| `label` | `string` | — | Small label text |
 | `labelFirst` | `boolean` | `false` | Render label before title |
+| `version` | `string` | — | Version string shown below the title |
+| `badges` | `string[]` | — | Badge labels shown beside the version |
 
 ## ChildCards
 
@@ -46,46 +48,58 @@ import ChildCards from 'astro-better-cards/ChildCards.astro';
 <!-- grandchildren grouped by subfolder with section headers -->
 <ChildCards depth={2} />
 
-<!-- children of an explicit folder -->
-<ChildCards folder="get-started/quickstarts/web" />
+<!-- deeper nesting (up to 4) with h2/h3/h4 section headers -->
+<ChildCards depth={4} />
+
+<!-- explicit folder, 3 columns -->
+<ChildCards folder="get-started/quickstarts" columns={3} />
 
 <!-- children from a different collection -->
 <ChildCards collection="articles" />
 ```
 
-Typically used via the `sectionIndex: true` front matter field (rendered automatically by the layout), or imported directly in MDX for more control.
-
 ### Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `collection` | `string` | `'docs'` | Astro content collection name |
 | `folder` | `string` | current page folder | Collection-relative path (`get-started/foo`), URL-absolute path (`/docs/get-started/foo`), or relative path (`./sub`, `../other`) |
-| `depth` | `1 \| 2` | `1` | `1` = direct children; `2` = grandchildren grouped under section headers |
+| `depth` | `1 \| 2 \| 3 \| 4` | `1` | `1` = direct children; `2`-`4` = deeper pages grouped under section headers (h2, then h3, then h4) |
+| `columns` | `1 \| 2 \| 3 \| 4` | `2` | Number of columns in the card grid |
 
 Pages with `excludeFromNav: true` or `route: false` are excluded.
 
 ## PageNav
 
-Renders previous/next navigation links at the bottom of a page, resolving page titles automatically from the collection.
+Renders previous/next navigation links at the bottom of a page. Reads `prev` and `next` from the
+current page's frontmatter and resolves titles automatically from the collection. Prop values
+override frontmatter when both are present.
+
+Add `prev` and `next` to the page's frontmatter:
+
+```yaml
+prev: "step-1"
+next: "step-3"
+```
+
+Then use the component with no props:
 
 ```astro
 import PageNav from 'astro-better-cards/PageNav.astro';
 
-<PageNav
-  currentId={entry.id}
-  lastPage="step-1"
-  nextPage="step-3"
-/>
+<PageNav />
 ```
 
-Or set `lastPage` / `nextPage` in front matter and let the layout render it automatically.
+Or override frontmatter on a specific instance:
+
+```astro
+<PageNav prev="other-page" next="another-page" />
+```
 
 ### Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `collection` | `string` | `'docs'` | Astro content collection name |
-| `currentId` | `string` | required | The current page's `entry.id` (e.g. `get-started/start-here/step-1.mdx`) |
-| `nextPage` | `string` | — | Relative href to the next page (e.g. `step-2`) or absolute (`/docs/...`) |
-| `lastPage` | `string` | — | Relative href to the previous page |
+| `prev` | `string` | frontmatter `prev` | Path to the previous page (relative filename, collection-relative, or absolute `/`) |
+| `next` | `string` | frontmatter `next` | Path to the next page |

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "astro-better-cards",
-  "version": "0.2.6",
+  "version": "1.0.1",
   "type": "module",
   "exports": {
     "./Card.astro": "./Card.astro",
+    "./CardGrid.astro": "./CardGrid.astro",
     "./ChildCards.astro": "./ChildCards.astro",
     "./PageNav.astro": "./PageNav.astro"
   },