stack-site-builder 1.17.4 → 1.18.0

package/CHANGELOG.md

@@ -11,6 +11,26 @@ content schema, while a consuming site supplies only content, taxonomy data and
 config. Sites track the theme with `pnpm up stack-site-builder`, so each release
 here is a plain version bump they pull in.
 
+## [1.18.0] - 2026-07-23
+
+### Added
+
+- **`papers` collection — the reading room** — an opt-in section
+  (`sections: { papers: true }` + `src/data/paper-categories.ts`, with an
+  optional `paperCategoryMap` for build-time category validation) for sites
+  that review the literature behind their stack. Frontmatter carries the
+  full author list (cards abbreviate to "et al."), venue/year, arXiv /
+  publisher / released-code links, and an **open-source availability badge**
+  (`openSource` + `repo`); `tools` cross-links catalog stacks on the detail
+  page. Routes mirror concepts: `/paper/`, `/paper/<id>/`,
+  `/paper/category/<id>/`, with a category-grouped index.
+- **Private entries are unlisted by default** — index listings (catalog
+  home, categories, tags, vendors, blog, concepts, courses, papers,
+  products, slides) now skip `private` entries unless they opt in with
+  `listed: true`, which shows the familiar locked teaser card. Unlisted
+  private entries still build and stay reachable via direct links and the
+  related sections on detail pages — the discovery path for gated content.
+
 ## [1.17.4] - 2026-07-22
 
 ### Changed
@@ -23,6 +43,12 @@ here is a plain version bump they pull in.
   its slide leaves the screen — the deck never carries a live embed between
   slides.
 
+### Fixed
+
+- **Table label columns wrapped** — in a wide table the first column got
+  squeezed to its minimum width, breaking short labels ("Part 1") onto two
+  lines. The first column of prose and slide tables no longer wraps.
+
 ## [1.17.3] - 2026-07-22
 
 ### Fixed
@@ -277,6 +303,7 @@ catalog sites from a thin content-only repository.
 - **Standalone development setup** — a devcontainer and a minimal `playground/`
   consuming site for developing and previewing the theme on its own.
 
+[1.18.0]: https://github.com/CodeCompose7/stack-site-builder/compare/v1.17.4...v1.18.0
 [1.17.4]: https://github.com/CodeCompose7/stack-site-builder/compare/v1.17.3...v1.17.4
 [1.17.3]: https://github.com/CodeCompose7/stack-site-builder/compare/v1.17.2...v1.17.3
 [1.17.2]: https://github.com/CodeCompose7/stack-site-builder/compare/v1.17.1...v1.17.2

package/README.md

@@ -38,9 +38,9 @@ export const collections = defineAasCollections({ categoryMap });
 | --- | --- |
 | `src/data/site.ts` | Site identity: name, repo URL (`repoNav: false` hides the header's GitHub link), the `locales` it ships, optional `sections` toggles, browser icons (`icons: { favicon, appleTouch, manifest }`), the `home` template, per-locale UI string overrides |
 | `src/data/categories.ts` | The tool-catalog category tree (validated against content) |
-| `src/data/concept-categories.ts` · `article-categories.ts` · `course-categories.ts` · `product-categories.ts` (opt-in) | Taxonomies for concepts / articles / courses / products |
+| `src/data/concept-categories.ts` · `article-categories.ts` · `course-categories.ts` · `product-categories.ts` · `paper-categories.ts` (opt-in) | Taxonomies for concepts / articles / courses / products / papers |
 | `src/data/glossary.mjs` | `[[Term]]` wikilink targets |
-| `src/content/{stacks,concepts,courses,products,articles,slides}/` | The content, one MDX file per locale |
+| `src/content/{stacks,concepts,courses,products,papers,articles,slides}/` | The content, one MDX file per locale |
 | `src/content/pages/` | Standalone top-level pages (e.g. an About/소개), rendered at `/<slug>/` and optionally linked in the header nav |
 | `public/` · `samples/` | Logos/favicons and runnable sample projects |
 
@@ -72,7 +72,7 @@ The rest are opt-out — **concepts, articles, samples, slides, glossary** and t
 standalone **pages** collection (About/소개, …) — so a site can ship only what it
 needs. Turning one off removes both its routes and its header-nav item. (`pages`
 also has finer control: each page's `nav` / `draft` frontmatter, or simply not
-authoring it.) **courses** and **products** are the opt-IN sections — see below.
+authoring it.) **courses**, **products** and **papers** are the opt-IN sections — see below.
 
 Declare the toggles once in `src/data/site.ts` and forward them to the theme in
 astro.config (which needs them to skip route injection). Import `SectionKey` from
@@ -166,6 +166,16 @@ Localized values are either one string or a per-locale record with
 default-locale fallback. On a cards home the header's Browse link (which
 anchors into the catalog) hides itself.
 
+## Papers (opt-in)
+
+A reading room for the literature behind the stack: each entry is one paper
+with its full author list, venue/year, arXiv / publisher / code links and an
+open-source availability badge; the body is your reading of it. `tools`
+cross-links catalog stacks. Enable with `sections: { papers: true }` plus
+`src/data/paper-categories.ts` (exporting `paperTree` / `paperCatOf`), and
+optionally pass `paperCategoryMap` to `defineAasCollections`. Routes mirror
+concepts: `/paper/`, `/paper/<id>/`, `/paper/category/<id>/`.
+
 ## Body components
 
 Reusable MDX-body components, importable from any collection's content:
@@ -196,8 +206,10 @@ teaser: A public one-liner shown on cards and above the login form. # optional
 
 The body ships **encrypted** (AES-256-GCM, key wrapped per user with PBKDF2) and
 is decrypted in the browser after login — no server needed, works on any static
-host. Listings show only the title + 🔒 (+ teaser); private URLs get `noindex`
-and stay out of the sitemap. Users and keys come from env vars (see
+host. By default a private entry stays OUT of index listings (reachable via
+direct links and the related sections on detail pages); set `listed: true` to
+show it as a locked teaser card (title + 🔒 + teaser). Private URLs get
+`noindex` and stay out of the sitemap. Users and keys come from env vars (see
 `playground/.env.sample`): `AAS_PRIVATE_USERS` (`id:password,…`),
 `AAS_PRIVATE_MASTER_SECRET` (rotate it to log every device out) and
 `AAS_PRIVATE_SESSION_DAYS`. Set them in `.env` locally or as CI secrets.

package/index.d.ts

@@ -8,6 +8,7 @@ export type SectionKey =
   | 'articles'
   | 'courses'
   | 'products'
+  | 'papers'
   | 'samples'
   | 'slides'
   | 'glossary'

package/index.mjs

@@ -44,6 +44,9 @@ const PAGES = [
   'concept/[...id].astro',
   'concept/category/[id].astro',
   'course/index.astro',
+  'paper/index.astro',
+  'paper/[...id].astro',
+  'paper/category/[id].astro',
   'course/[...id].astro',
   'course/category/[id].astro',
   'glossary.astro',
@@ -72,6 +75,7 @@ function sectionOf(file) {
   if (file.startsWith('concept/')) return 'concepts';
   if (file.startsWith('article/')) return 'articles';
   if (file.startsWith('course/')) return 'courses';
+  if (file.startsWith('paper/')) return 'papers';
   if (file.startsWith('products/')) return 'products';
   if (file.startsWith('sample/')) return 'samples';
   if (file.startsWith('slides/')) return 'slides';
@@ -85,7 +89,7 @@ function sectionOf(file) {
 // when the site passes `{ <key>: true }`. Both need site-side data
 // (src/data/{course,product}-categories.ts), so a theme upgrade alone must
 // not enable them.
-const OPT_IN_SECTIONS = new Set(['courses', 'products']);
+const OPT_IN_SECTIONS = new Set(['courses', 'products', 'papers']);
 
 /**
  * @param {object} opts

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "stack-site-builder",
   "type": "module",
-  "version": "1.17.4",
+  "version": "1.18.0",
   "license": "MIT",
   "description": "The engine behind the awesome-*-stack catalog sites: an Astro theme with the catalog/concepts/articles/slides/samples routes, components, styles and markdown pipeline. Sites provide content, taxonomy data and config.",
   "repository": {

package/src/components/BlogIndex.astro

@@ -8,6 +8,7 @@ import ArrowUpRight from './ArrowUpRight.astro';
 const PAGE = 12;
 import { articleTree, articleCatOf } from '@aas-data/article-categories';
 import { getArticles, articleSlugOf, type ArticleEntry } from '../lib/articles';
+import { listedInIndex } from '../lib/listing';
 import { useTranslations, type Lang } from '../i18n/ui';
 
 // Doubles as the writing index (no `categoryId` → all articles, grouped by
@@ -20,7 +21,7 @@ interface Props {
 
 const { lang, categoryId } = Astro.props;
 const t = useTranslations(lang);
-const all = await getArticles(lang);
+const all = (await getArticles(lang)).filter((e) => listedInIndex(e.data));
 const catUrl = (cid: string) => getRelativeLocaleUrl(lang, `article/category/${cid}/`);
 
 const itemsIn = (cid: string): ArticleEntry[] => {

package/src/components/CategoryIndex.astro

@@ -7,6 +7,7 @@ import ArrowUpRight from './ArrowUpRight.astro';
 import { categoryMap, childrenOf, pathOf } from '@aas-data/categories';
 import { getStacks, getStacksByCategory, slugOf, type StackEntry } from '../lib/stacks';
 import { deriveFacets } from '../lib/facets';
+import { listedInIndex } from '../lib/listing';
 import { useTranslations, type Lang } from '../i18n/ui';
 
 interface Props {
@@ -31,16 +32,21 @@ const crumbs = [
 
 const children = childrenOf(id);
 // Stacks attached directly to this node (vs. nested under a subcategory).
-const direct = (await getStacksByCategory(lang, id)).filter((s) => s.data.category === id);
+const direct = (await getStacksByCategory(lang, id)).filter(
+  (s) => s.data.category === id && listedInIndex(s.data),
+);
 // Each child subcategory with its own rolled-up stacks.
 const childGroups = await Promise.all(
-  children.map(async (c) => ({ cat: c, items: await getStacksByCategory(lang, c.id) })),
+  children.map(async (c) => ({
+    cat: c,
+    items: (await getStacksByCategory(lang, c.id)).filter((s) => listedInIndex(s.data)),
+  })),
 );
 
 // Filter facets are built from the WHOLE catalog (not just this page's tools) so
 // they're identical on every page — a sort/filter carried in from elsewhere can
 // always be restored here, even if no tool in this category has that value.
-const facets = deriveFacets(await getStacks(lang), lang);
+const facets = deriveFacets((await getStacks(lang)).filter((e) => listedInIndex(e.data)), lang);
 
 const cardProps = (e: StackEntry) => ({
   slug: slugOf(e),

package/src/components/ConceptIndex.astro

@@ -8,6 +8,7 @@ import ArrowUpRight from './ArrowUpRight.astro';
 const PAGE = 12;
 import { conceptTree, conceptCatOf } from '@aas-data/concept-categories';
 import { getConcepts, conceptSlugOf, type ConceptEntry } from '../lib/concepts';
+import { listedInIndex } from '../lib/listing';
 import { useTranslations, type Lang } from '../i18n/ui';
 
 // Doubles as the concept index (no `categoryId` → all concepts, grouped by
@@ -22,7 +23,7 @@ const { lang, categoryId } = Astro.props;
 const t = useTranslations(lang);
 // Default order is most-recently-updated first (matches the ListControls
 // default), so the server render and the client sort agree — no reflow on load.
-const all = (await getConcepts(lang)).sort(
+const all = (await getConcepts(lang)).filter((e) => listedInIndex(e.data)).sort(
   (a, b) =>
     (b.data.updated?.getTime() ?? 0) - (a.data.updated?.getTime() ?? 0) ||
     a.data.title.localeCompare(b.data.title),

package/src/components/CourseIndex.astro

@@ -8,6 +8,7 @@ import ArrowUpRight from './ArrowUpRight.astro';
 const PAGE = 12;
 import { courseTree, courseCatOf } from '@aas-data/course-categories';
 import { getCourses, courseSlugOf, type CourseEntry } from '../lib/courses';
+import { listedInIndex } from '../lib/listing';
 import { useTranslations, type Lang } from '../i18n/ui';
 
 // Doubles as the course index (no `categoryId` → all courses, grouped by
@@ -22,7 +23,7 @@ const { lang, categoryId } = Astro.props;
 const t = useTranslations(lang);
 // getCourses() order (manual `order` desc, then date) agrees with the client
 // "recent" comparator over CourseCard's data-date keys — no reflow on load.
-const all = await getCourses(lang);
+const all = (await getCourses(lang)).filter((e) => listedInIndex(e.data));
 const catUrl = (cid: string) => getRelativeLocaleUrl(lang, `course/category/${cid}/`);
 
 const itemsIn = (cid: string): CourseEntry[] => {

package/src/components/Home.astro

@@ -7,6 +7,7 @@ import { rootCategories, descendantIds } from '@aas-data/categories';
 import { getStacks, slugOf } from '../lib/stacks';
 import { site } from '@aas-data/site';
 import { deriveFacets } from '../lib/facets';
+import { listedInIndex } from '../lib/listing';
 import { useTranslations, type Lang } from '../i18n/ui';
 
 interface Props {
@@ -15,7 +16,7 @@ interface Props {
 
 const { lang } = Astro.props;
 const t = useTranslations(lang);
-const entries = await getStacks(lang);
+const entries = (await getStacks(lang)).filter((e) => listedInIndex(e.data));
 
 // Default order is alphabetical (matches the client's default sort, so no flash).
 // Group by top-level category, rolling up every subcategory in its subtree.

package/src/components/PaperCard.astro

@@ -0,0 +1,85 @@
+---
+import { Image } from 'astro:assets';
+import { getRelativeLocaleUrl } from 'astro:i18n';
+import { useTranslations, type Lang } from '../i18n/ui';
+import { shortAuthors } from '../lib/papers';
+import { inlineMd } from '../lib/inline-md';
+import type { ImageMetadata } from 'astro';
+
+interface Props {
+  lang: Lang;
+  slug: string;
+  title: string;
+  description: string;
+  authors: string[];
+  year?: number;
+  venue?: string;
+  openSource?: boolean;
+  tags: string[];
+  image?: ImageMetadata;
+  imageAlt?: string;
+  /** Private entry: show a lock and the (public) `teaser` instead of the description. */
+  isPrivate?: boolean;
+  teaser?: string;
+}
+
+const {
+  lang,
+  slug,
+  title,
+  description,
+  authors,
+  year,
+  venue,
+  openSource = false,
+  tags,
+  image,
+  imageAlt,
+  isPrivate = false,
+  teaser,
+} = Astro.props;
+const t = useTranslations(lang);
+const shownDesc = isPrivate ? (teaser ?? '') : description;
+---
+
+<a
+  href={getRelativeLocaleUrl(lang, `paper/${slug}/`)}
+  data-name={title.toLowerCase()}
+  data-date={year ? String(year) : ''}
+  class="aas-lift block overflow-hidden rounded-3xl border border-[var(--aas-border)] bg-[var(--aas-panel)] no-underline"
+>
+  {image && <Image src={image} alt={imageAlt ?? title} class="aspect-[16/9] w-full object-cover" />}
+  <div class="p-5">
+    <p class="flex flex-wrap items-center gap-x-2 gap-y-1 text-xs text-[var(--aas-muted)]">
+      {venue && <span>{venue}</span>}
+      {venue && year && <span>·</span>}
+      {year && <span>{year}</span>}
+      {
+        openSource && (
+          <span class="rounded-full border border-[var(--aas-accent)] px-2 py-0.5 text-[var(--aas-accent)]">
+            {t('paper.openSource')}
+          </span>
+        )
+      }
+    </p>
+    <h3 class="mt-1 text-lg font-semibold text-[var(--aas-text)]">
+      {isPrivate && <span aria-label={t('private.badge')} title={t('private.badge')}>🔒 </span>}{title}
+    </h3>
+    {authors.length > 0 && <p class="mt-1 text-sm text-[var(--aas-muted)]">{shortAuthors(authors)}</p>}
+    <p
+      class="aas-md mt-2 text-sm leading-relaxed text-[var(--aas-muted)]"
+      set:html={inlineMd(shownDesc)}
+    />
+    {
+      tags.length > 0 && (
+        <div class="mt-3 flex flex-wrap gap-1.5">
+          {tags.slice(0, 4).map((tag) => (
+            <span class="rounded-full border border-[var(--aas-border)] px-2 py-0.5 text-xs text-[var(--aas-muted)]">
+              {tag}
+            </span>
+          ))}
+        </div>
+      )
+    }
+  </div>
+</a>

package/src/components/PaperDetail.astro

@@ -0,0 +1,123 @@
+---
+import { render } from 'astro:content';
+import { getRelativeLocaleUrl } from 'astro:i18n';
+import { getPapers, paperSlugOf, type PaperEntry } from '../lib/papers';
+import { inlineMd } from '../lib/inline-md';
+import { Image } from 'astro:assets';
+import { useTranslations, type Lang } from '../i18n/ui';
+import { formatDate } from '../lib/dates';
+import MermaidLoader from './MermaidLoader.astro';
+import TocRail from './TocRail.astro';
+import Breadcrumb from './Breadcrumb.astro';
+import ArrowUpRight from './ArrowUpRight.astro';
+import { paperTree, paperCatOf } from '@aas-data/paper-categories';
+import RelatedPapers from './RelatedPapers.astro';
+import RelatedTools from './RelatedTools.astro';
+
+interface Props {
+  entry: PaperEntry;
+  lang: Lang;
+}
+
+const { entry, lang } = Astro.props;
+const t = useTranslations(lang);
+const { Content, headings } = await render(entry);
+const data = entry.data;
+const tocItems = headings.filter((h) => h.depth >= 2 && h.depth <= 3);
+const bodyHasMermaid = (entry.body ?? '').includes('```mermaid');
+
+// Sibling papers linked from frontmatter (mutual cross-links, like concepts).
+const papers = await getPapers(lang);
+const paperBySlug = new Map(papers.map((c) => [paperSlugOf(c), c]));
+const relatedPapers = data.related
+  .map((sl) => paperBySlug.get(sl))
+  .filter(Boolean) as PaperEntry[];
+
+// External resource buttons: arXiv, the publisher page, and released code.
+const links = [
+  data.arxiv && { label: t('paper.arxiv'), href: data.arxiv },
+  data.paperUrl && { label: t('paper.paper'), href: data.paperUrl },
+  data.repo && { label: t('paper.code'), href: data.repo },
+].filter(Boolean) as { label: string; href: string }[];
+
+// Breadcrumb: All papers › category › subcategory… (each segment linked).
+const crumbs = [
+  { label: t('paper.backToPapers'), href: getRelativeLocaleUrl(lang, 'paper/') },
+  ...paperTree.pathOf(paperCatOf(data.category)).map((c) => ({
+    label: c.label[lang],
+    href: getRelativeLocaleUrl(lang, `paper/category/${c.id}/`),
+  })),
+];
+---
+
+<Breadcrumb segments={crumbs} />
+
+<header class="mt-4 pb-6">
+  <h1 class="text-3xl font-bold tracking-tight">{data.title}</h1>
+  {
+    data.authors.length > 0 && (
+      <p class="mt-2 text-sm text-[var(--aas-muted)]">
+        <span class="font-semibold">{t('paper.authors')}:</span> {data.authors.join(', ')}
+      </p>
+    )
+  }
+  <p class="mt-1 flex flex-wrap items-center gap-x-3 gap-y-1 text-sm text-[var(--aas-muted)]">
+    {data.venue && <span>{data.venue}</span>}
+    {data.year && <span>{data.year}</span>}
+    {
+      data.openSource && (
+        <span class="rounded-full border border-[var(--aas-accent)] px-2 py-0.5 text-xs text-[var(--aas-accent)]">
+          {t('paper.openSource')}
+        </span>
+      )
+    }
+    {data.version && <span>{t('meta.docVersion')} {data.version}</span>}
+    {
+      data.updated && (
+        <span>
+          {t('paper.updated')} {formatDate(data.updated, lang)}
+        </span>
+      )
+    }
+  </p>
+  {
+    links.length > 0 && (
+      <p class="mt-3 flex flex-wrap items-center gap-2">
+        {links.map((l) => (
+          <a
+            href={l.href}
+            target="_blank"
+            rel="noopener noreferrer"
+            class="rounded-full border border-[var(--aas-border)] bg-[var(--aas-panel)] px-3 py-1 text-sm text-[var(--aas-text)] no-underline hover:bg-[var(--aas-tint)]"
+          >
+            {l.label}
+            <ArrowUpRight size={14} class="ml-0.5 text-[var(--aas-muted)]" />
+          </a>
+        ))}
+      </p>
+    )
+  }
+  <p class="mt-2 aas-md text-lg whitespace-pre-line text-[var(--aas-muted)]" set:html={inlineMd(data.description)} />
+  {
+    data.image && (
+      <Image
+        src={data.image}
+        alt={data.imageAlt ?? data.title}
+        class="mt-5 aspect-[2/1] w-full rounded-2xl border border-[var(--aas-border)] object-cover"
+      />
+    )
+  }
+</header>
+
+<RelatedPapers lang={lang} papers={relatedPapers} />
+
+<div class="mt-8 flex items-start gap-8">
+  <article class="prose max-w-none aas-reading min-w-0 flex-1">
+    <Content />
+  </article>
+  <TocRail lang={lang} items={tocItems} />
+</div>
+
+<RelatedTools lang={lang} slugs={data.tools} />
+
+{bodyHasMermaid && <MermaidLoader />}

package/src/components/PapersIndex.astro

@@ -0,0 +1,144 @@
+---
+import { getRelativeLocaleUrl } from 'astro:i18n';
+import PaperCard from './PaperCard.astro';
+import Breadcrumb from './Breadcrumb.astro';
+import ListControls from './ListControls.astro';
+import ArrowUpRight from './ArrowUpRight.astro';
+
+const PAGE = 12;
+import { paperTree, paperCatOf } from '@aas-data/paper-categories';
+import { getPapers, paperSlugOf, type PaperEntry } from '../lib/papers';
+import { listedInIndex } from '../lib/listing';
+import { useTranslations, type Lang } from '../i18n/ui';
+
+// Doubles as the papers index (no `categoryId` → all papers, grouped by
+// category) and a category browse page (`categoryId` → that category, with a
+// breadcrumb, its direct papers, and a section per subcategory).
+interface Props {
+  lang: Lang;
+  categoryId?: string;
+}
+
+const { lang, categoryId } = Astro.props;
+const t = useTranslations(lang);
+// getPapers() sorts newest publication year first, matching the client-side
+// "recent" comparator over PaperCard's data-date (= year) — no reflow on load.
+const all = (await getPapers(lang)).filter((e) => listedInIndex(e.data));
+const catUrl = (cid: string) => getRelativeLocaleUrl(lang, `paper/category/${cid}/`);
+
+const itemsIn = (cid: string): PaperEntry[] => {
+  const ids = new Set(paperTree.descendantIds(cid));
+  return all.filter((c) => ids.has(paperCatOf(c.data.category)));
+};
+
+const node = categoryId ? paperTree.map.get(categoryId) : undefined;
+const sections = node ? paperTree.childrenOf(node.id) : paperTree.roots;
+const direct = node ? all.filter((c) => paperCatOf(c.data.category) === node.id) : [];
+
+// A leaf category page shows one flat list — that grid gets ?page= pagination.
+// Index and parent-category pages stay grouped overviews: each section is
+// capped to PAGE cards with a "see all" link to the fuller list.
+const isLeaf = !!node && sections.length === 0;
+
+const path = node ? paperTree.pathOf(node.id) : [];
+const crumbs = node
+  ? [
+      { label: t('paper.backToPapers'), href: getRelativeLocaleUrl(lang, 'paper/') },
+      ...path.map((c, i) => ({
+        label: c.label[lang],
+        href: i === path.length - 1 ? undefined : catUrl(c.id),
+      })),
+    ]
+  : [];
+
+const card = (c: PaperEntry) => ({
+  lang,
+  slug: paperSlugOf(c),
+  title: c.data.title,
+  description: c.data.description,
+  authors: c.data.authors,
+  year: c.data.year,
+  venue: c.data.venue,
+  openSource: c.data.openSource,
+  tags: c.data.tags,
+  image: c.data.image,
+  imageAlt: c.data.imageAlt,
+  isPrivate: c.data.private,
+  teaser: c.data.teaser,
+});
+---
+
+{
+  node ? (
+    <>
+      <Breadcrumb segments={crumbs} />
+      <header class="mt-4">
+        <h1 class="text-3xl font-bold tracking-tight">{node.label[lang]}</h1>
+        <p class="mt-2 max-w-2xl text-lg text-[var(--aas-muted)]">
+          {node.detail?.[lang] ?? node.description[lang]}
+        </p>
+      </header>
+    </>
+  ) : (
+    <section class="py-6">
+      <h1 class="text-4xl font-bold tracking-tight">{t('paper.title')}</h1>
+      <p class="mt-3 max-w-2xl text-lg text-[var(--aas-muted)]">{t('paper.tagline')}</p>
+    </section>
+  )
+}
+
+{all.length === 0 && <p class="mt-8 text-[var(--aas-muted)]">{t('paper.empty')}</p>}
+
+{all.length > 0 && <div class="mt-6"><ListControls lang={lang} /></div>}
+
+{
+  direct.length > 0 && (
+    <div
+      class="mt-4 grid gap-5 sm:grid-cols-2 lg:grid-cols-3"
+      data-sortgrid
+      data-paginate={isLeaf ? true : undefined}
+      data-page-size={isLeaf ? PAGE : undefined}
+    >
+      {direct.map((c) => (
+        <PaperCard {...card(c)} />
+      ))}
+    </div>
+  )
+}
+
+{
+  sections.map((cat) => {
+    const items = itemsIn(cat.id);
+    return (
+      items.length > 0 && (
+        <section class="mt-8">
+          <h2 class="text-2xl font-semibold">
+            <a
+              href={catUrl(cat.id)}
+              class="text-[var(--aas-text)] no-underline hover:text-[var(--aas-accent)]"
+            >
+              {cat.label[lang]}
+              <ArrowUpRight size={20} class="ml-1 text-[var(--aas-muted)]" />
+            </a>
+          </h2>
+          <p class="mt-1 text-sm text-[var(--aas-muted)]">{cat.description[lang]}</p>
+          <div class="mt-4 grid gap-5 sm:grid-cols-2 lg:grid-cols-3" data-sortgrid>
+            {items.slice(0, PAGE).map((c) => (
+              <PaperCard {...card(c)} />
+            ))}
+          </div>
+          {items.length > PAGE && (
+            <a
+              href={catUrl(cat.id)}
+              class="mt-3 inline-block text-sm font-medium text-[var(--aas-accent)] no-underline"
+            >
+              {t('list.seeAll').replace('{n}', String(items.length))} &rarr;
+            </a>
+          )}
+        </section>
+      )
+    );
+  })
+}
+
+{isLeaf && <nav data-pager aria-label="Pagination" class="mt-8 flex flex-wrap items-center justify-center gap-1.5" />}

package/src/components/ProductsIndex.astro

@@ -7,6 +7,7 @@
 import { getRelativeLocaleUrl } from 'astro:i18n';
 import { productTree, productCatOf } from '@aas-data/product-categories';
 import { getTopProducts, productSlugOf, type ProductEntry } from '../lib/products';
+import { listedInIndex } from '../lib/listing';
 import { useTranslations, type Lang } from '../i18n/ui';
 
 interface Props {
@@ -15,7 +16,7 @@ interface Props {
 
 const { lang } = Astro.props;
 const t = useTranslations(lang);
-const all = await getTopProducts(lang);
+const all = (await getTopProducts(lang)).filter((e) => listedInIndex(e.data));
 const base = import.meta.env.BASE_URL.replace(/\/$/, '');
 const withBase = (p?: string) => (p && p.startsWith('/') ? base + p : p);
 

package/src/components/RelatedPapers.astro

@@ -0,0 +1,59 @@
+---
+// "Related papers" card section on a paper detail page, mirroring
+// RelatedConcepts (title + authors/venue meta + description, collapsible grid).
+import { getRelativeLocaleUrl } from 'astro:i18n';
+import { Image } from 'astro:assets';
+import { paperSlugOf, shortAuthors, type PaperEntry } from '../lib/papers';
+import { useTranslations, type Lang } from '../i18n/ui';
+import { inlineMd } from '../lib/inline-md';
+import CollapsibleGrid from './CollapsibleGrid.astro';
+
+interface Props {
+  lang: Lang;
+  papers: PaperEntry[];
+}
+
+const { lang, papers } = Astro.props;
+const t = useTranslations(lang);
+---
+
+{
+  papers.length > 0 && (
+    <section class="mt-8">
+      <h2 class="text-xs font-semibold tracking-wide text-[var(--aas-muted)] uppercase">
+        {t('paper.relatedPapers')}
+      </h2>
+      <CollapsibleGrid lang={lang} count={papers.length}>
+        {papers.map((c) => (
+          <a
+            href={getRelativeLocaleUrl(lang, `paper/${paperSlugOf(c)}/`)}
+            class="aas-lift flex items-stretch overflow-hidden rounded-2xl border border-[var(--aas-border)] bg-[var(--aas-panel)] no-underline"
+          >
+            {c.data.image && (
+              <Image src={c.data.image} alt="" class="w-28 shrink-0 self-stretch object-cover" />
+            )}
+            <div class="min-w-0 p-4">
+              <span class="block font-semibold text-[var(--aas-text)]">
+                {c.data.private && (
+                  <span aria-label={t('private.badge')} title={t('private.badge')}>🔒 </span>
+                )}
+                {c.data.title}
+              </span>
+              <span class="mt-0.5 block text-xs text-[var(--aas-muted)]">
+                {shortAuthors(c.data.authors)}
+                {c.data.authors.length > 0 && (c.data.venue || c.data.year) && ' · '}
+                {c.data.venue}
+                {c.data.venue && c.data.year && ' '}
+                {c.data.year}
+              </span>
+              <span
+                class="aas-md mt-1.5 line-clamp-2 text-xs leading-relaxed text-[var(--aas-muted)] opacity-75"
+                set:html={inlineMd(c.data.private ? (c.data.teaser ?? '') : c.data.description)}
+              />
+            </div>
+          </a>
+        ))}
+      </CollapsibleGrid>
+    </section>
+  )
+}

package/src/components/SlidesIndex.astro

@@ -1,5 +1,6 @@
 ---
 import { getRelativeLocaleUrl } from 'astro:i18n';
+import { listedInIndex } from '../lib/listing';
 import { useTranslations, type Lang } from '../i18n/ui';
 import { getDecks, deckSlugOf } from '../lib/slides';
 
@@ -12,7 +13,7 @@ const t = useTranslations(lang);
 
 // Decks are locale-partitioned (content/slides/<lang>/); list this locale's and
 // link to its localized deck page. `related` points at the concept it summarizes.
-const decks = await getDecks(lang);
+const decks = (await getDecks(lang)).filter((e) => listedInIndex(e.data));
 ---
 
 <section class="py-6">

package/src/components/TagIndex.astro

@@ -2,6 +2,7 @@
 import { getRelativeLocaleUrl } from 'astro:i18n';
 import StackCard from './StackCard.astro';
 import { getStacksByTag, slugOf } from '../lib/stacks';
+import { listedInIndex } from '../lib/listing';
 import { useTranslations, type Lang } from '../i18n/ui';
 
 interface Props {
@@ -11,7 +12,7 @@ interface Props {
 
 const { lang, tag } = Astro.props;
 const t = useTranslations(lang);
-const entries = (await getStacksByTag(lang, tag)).sort((a, b) =>
+const entries = (await getStacksByTag(lang, tag)).filter((e) => listedInIndex(e.data)).sort((a, b) =>
   a.data.name.localeCompare(b.data.name),
 );
 ---

package/src/components/VendorIndex.astro

@@ -2,6 +2,7 @@
 import { getRelativeLocaleUrl } from 'astro:i18n';
 import StackCard from './StackCard.astro';
 import { getStacksByVendor, slugOf } from '../lib/stacks';
+import { listedInIndex } from '../lib/listing';
 import { useTranslations, type Lang } from '../i18n/ui';
 
 interface Props {
@@ -11,7 +12,7 @@ interface Props {
 
 const { lang, vendor } = Astro.props;
 const t = useTranslations(lang);
-const entries = await getStacksByVendor(lang, vendor);
+const entries = (await getStacksByVendor(lang, vendor)).filter((e) => listedInIndex(e.data));
 // The display name is whatever the entries wrote (e.g. "Hugging Face").
 const vendorName = entries[0]?.data.vendor ?? vendor;
 ---

package/src/content.ts

@@ -19,6 +19,7 @@ export function defineAasCollections({
   categoryMap,
   courseCategoryMap,
   productCategoryMap,
+  paperCategoryMap,
 }: {
   categoryMap: Map<string, unknown>;
   /** The site's course category tree (`src/data/course-categories.ts`). Optional
@@ -28,6 +29,9 @@ export function defineAasCollections({
   /** The site's product category tree (`src/data/product-categories.ts`).
    *  Optional like `courseCategoryMap` — `products` is opt-in too. */
   productCategoryMap?: Map<string, unknown>;
+  /** The site's paper category tree (`src/data/paper-categories.ts`).
+   *  Optional like the others — `papers` is opt-in too. */
+  paperCategoryMap?: Map<string, unknown>;
 }) {
   /**
    * The `stacks` collection holds one entry per tool/service used to build
@@ -125,6 +129,10 @@ export function defineAasCollections({
       // See docs/private-content-design.md. Requires the AAS_PRIVATE_* env vars.
       private: z.boolean().default(false),
       teaser: z.string().optional(),
+      // Show this PRIVATE entry on index listings as a locked teaser card.
+      // Default: private entries stay OUT of listings and are reached via
+      // direct links / the related sections on detail pages.
+      listed: z.boolean().default(false),
     }),
   });
 
@@ -169,6 +177,10 @@ export function defineAasCollections({
         // PUBLIC `teaser`). See docs/private-content-design.md.
         private: z.boolean().default(false),
         teaser: z.string().optional(),
+        // Show this PRIVATE entry on index listings as a locked teaser card.
+        // Default: private entries stay OUT of listings and are reached via
+        // direct links / the related sections on detail pages.
+        listed: z.boolean().default(false),
       }),
   });
 
@@ -207,6 +219,10 @@ export function defineAasCollections({
         // PUBLIC `teaser`). See docs/private-content-design.md.
         private: z.boolean().default(false),
         teaser: z.string().optional(),
+        // Show this PRIVATE entry on index listings as a locked teaser card.
+        // Default: private entries stay OUT of listings and are reached via
+        // direct links / the related sections on detail pages.
+        listed: z.boolean().default(false),
       }),
   });
 
@@ -263,6 +279,64 @@ export function defineAasCollections({
         // PUBLIC `teaser`). See docs/private-content-design.md.
         private: z.boolean().default(false),
         teaser: z.string().optional(),
+        // Show this PRIVATE entry on index listings as a locked teaser card.
+        // Default: private entries stay OUT of listings and are reached via
+        // direct links / the related sections on detail pages.
+        listed: z.boolean().default(false),
+      }),
+  });
+
+  /**
+   * The `papers` collection is the reading room — one entry per academic
+   * paper, an opt-in section (`sections: { papers: true }`) for sites that
+   * review the literature behind their stack. Frontmatter powers the cards
+   * (authors, venue/year, open-source availability, links); the body is the
+   * site's own reading/review of the paper. Locale-partitioned:
+   * `papers/<lang>/<slug>.mdx`.
+   */
+  const papers = defineCollection({
+    loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/papers' }),
+    schema: ({ image }) =>
+      z.object({
+        title: z.string(),
+        // The full author list, in publication order. Cards abbreviate to the
+        // first names + "et al."; the detail page shows everyone.
+        authors: z.array(z.string()).default([]),
+        year: z.number().int().optional(),
+        venue: z.string().optional(), // NeurIPS, ICML, arXiv, JMLR, …
+        description: z.string(), // one-line takeaway, shown on cards
+        // Leaf id from the site's src/data/paper-categories.ts. Validated when
+        // the site passes `paperCategoryMap`; otherwise resolved at render
+        // with an uncategorized fallback.
+        category: (paperCategoryMap
+          ? z.string().refine((id) => paperCategoryMap.has(id), {
+              message:
+                'unknown paper category id — must match a node in the site data paper category tree',
+            })
+          : z.string()
+        ).optional(),
+        image: image().optional(), // key figure / teaser image
+        imageAlt: z.string().optional(),
+        arxiv: z.string().url().optional(),
+        paperUrl: z.string().url().optional(), // publisher / DOI page
+        // Has the paper's code been released? Shown as a badge and filterable
+        // at a glance; `repo` links the released implementation.
+        openSource: z.boolean().default(false),
+        repo: z.string().url().optional(),
+        tools: z.array(z.string()).default([]), // catalog stacks this paper underpins
+        related: z.array(z.string()).default([]), // related paper slugs
+        tags: z.array(z.string()).default([]),
+        // Living-doc metadata for the review itself, mirroring concepts.
+        version: z.string().optional(),
+        updated: z.coerce.date().optional(),
+        draft: z.boolean().default(false),
+        // Login-gated entry (encrypted body; see docs/private-content-design.md).
+        private: z.boolean().default(false),
+        teaser: z.string().optional(),
+        // Show this PRIVATE entry on index listings as a locked teaser card.
+        // Default: private entries stay OUT of listings and are reached via
+        // direct links / the related sections on detail pages.
+        listed: z.boolean().default(false),
       }),
   });
 
@@ -307,6 +381,10 @@ export function defineAasCollections({
       // optional PUBLIC `teaser`). See docs/private-content-design.md.
       private: z.boolean().default(false),
       teaser: z.string().optional(),
+      // Show this PRIVATE entry on index listings as a locked teaser card.
+      // Default: private entries stay OUT of listings and are reached via
+      // direct links / the related sections on detail pages.
+      listed: z.boolean().default(false),
     }),
   });
 
@@ -452,6 +530,10 @@ export function defineAasCollections({
       // Login-gated page (encrypted body; see docs/private-content-design.md).
       private: z.boolean().default(false),
       teaser: z.string().optional(),
+      // Show this PRIVATE entry on index listings as a locked teaser card.
+      // Default: private entries stay OUT of listings and are reached via
+      // direct links / the related sections on detail pages.
+      listed: z.boolean().default(false),
     }),
   });
 
@@ -484,8 +566,12 @@ export function defineAasCollections({
         // PUBLIC `teaser`). See docs/private-content-design.md.
         private: z.boolean().default(false),
         teaser: z.string().optional(),
+        // Show this PRIVATE entry on index listings as a locked teaser card.
+        // Default: private entries stay OUT of listings and are reached via
+        // direct links / the related sections on detail pages.
+        listed: z.boolean().default(false),
       }),
   });
 
-  return { stacks, articles, concepts, courses, slides, products, pages };
+  return { stacks, articles, concepts, courses, papers, slides, products, pages };
 }

package/src/i18n/ui.ts

@@ -60,6 +60,7 @@ export const ui = {
     'nav.concepts': 'Concepts',
     'nav.courses': 'Courses',
     'nav.products': 'Products',
+    'nav.papers': 'Papers',
     'nav.blog': 'Writing',
     'nav.samples': 'Samples',
     'nav.slides': 'Slides',
@@ -129,6 +130,17 @@ export const ui = {
     'course.updated': 'Updated',
     'course.relatedCourses': 'Related courses',
     'course.slides': 'Slides',
+    'paper.title': 'Papers',
+    'paper.tagline': 'Paper readings and reviews — what matters and why.',
+    'paper.empty': 'No papers yet.',
+    'paper.backToPapers': 'All papers',
+    'paper.authors': 'Authors',
+    'paper.openSource': 'Code available',
+    'paper.arxiv': 'arXiv',
+    'paper.paper': 'Paper',
+    'paper.code': 'Code',
+    'paper.relatedPapers': 'Related papers',
+    'paper.updated': 'Updated',
     'products.title': 'Products',
     'products.tagline': 'What we build and offer.',
     'products.empty': 'No products yet.',
@@ -224,6 +236,7 @@ export const ui = {
     'nav.concepts': '개념',
     'nav.courses': '강의',
     'nav.products': '제품',
+    'nav.papers': '논문',
     'nav.blog': '글',
     'nav.samples': '샘플',
     'nav.slides': '슬라이드',
@@ -292,6 +305,17 @@ export const ui = {
     'course.updated': '업데이트',
     'course.relatedCourses': '관련 강의',
     'course.slides': '슬라이드',
+    'paper.title': '논문',
+    'paper.tagline': '논문을 읽고 정리합니다 — 무엇이, 왜 중요한지.',
+    'paper.empty': '아직 논문이 없습니다.',
+    'paper.backToPapers': '논문 전체',
+    'paper.authors': '저자',
+    'paper.openSource': '코드 공개',
+    'paper.arxiv': 'arXiv',
+    'paper.paper': '원문',
+    'paper.code': '코드',
+    'paper.relatedPapers': '관련 논문',
+    'paper.updated': '업데이트',
     'products.title': '제품',
     'products.tagline': '우리가 만들고 제공하는 것.',
     'products.empty': '아직 제품이 없습니다.',

package/src/layouts/BaseLayout.astro

@@ -95,6 +95,12 @@ const allNavItems: {
     section: 'courses',
     svg: '<path d="M21.42 10.922a1 1 0 0 0-.019-1.838L12.83 5.18a2 2 0 0 0-1.66 0L2.6 9.08a1 1 0 0 0 0 1.832l8.57 3.908a2 2 0 0 0 1.66 0z"/><path d="M22 10v6"/><path d="M6 12.5V16a6 3 0 0 0 12 0v-3.5"/>',
   },
+  {
+    href: getRelativeLocaleUrl(lang, 'paper/'),
+    label: t('nav.papers'),
+    section: 'papers' as SectionKey,
+    svg: '<path d="M4 19.5v-15A2.5 2.5 0 0 1 6.5 2H20v20H6.5a2.5 2.5 0 0 1 0-5H20"/>',
+  },
   {
     href: getRelativeLocaleUrl(lang, 'concept/'),
     label: t('nav.concepts'),

package/src/lib/listing.ts

@@ -0,0 +1,9 @@
+/**
+ * Whether an entry belongs on index listings. Public entries always do;
+ * PRIVATE entries only when they opt in with `listed: true` (shown as a
+ * locked teaser card). Unlisted private entries still build and stay
+ * reachable via direct links and the related-entry sections on detail pages —
+ * that's the discovery path for gated content.
+ */
+export const listedInIndex = (d: { private?: boolean; listed?: boolean }): boolean =>
+  !d.private || d.listed === true;

package/src/lib/papers.ts

@@ -0,0 +1,25 @@
+import { getCollection, type CollectionEntry } from 'astro:content';
+import type { Lang } from '../i18n/ui';
+
+export type PaperEntry = CollectionEntry<'papers'>;
+
+/** The url slug of a paper, i.e. its id with the `<lang>/` prefix removed. */
+export function paperSlugOf(entry: PaperEntry): string {
+  return entry.id.replace(/^[a-z]{2}\//, '');
+}
+
+/** Published papers for one locale — newest publication year first, then title. */
+export async function getPapers(lang: Lang): Promise<PaperEntry[]> {
+  const all = await getCollection('papers');
+  return all
+    .filter((e) => e.id.startsWith(`${lang}/`) && !e.data.draft)
+    .sort(
+      (a, b) => (b.data.year ?? 0) - (a.data.year ?? 0) || a.data.title.localeCompare(b.data.title),
+    );
+}
+
+/** Cards abbreviate the author list: first `max` names, then "et al.". */
+export function shortAuthors(authors: string[], max = 3): string {
+  if (authors.length === 0) return '';
+  return authors.length <= max ? authors.join(', ') : `${authors.slice(0, max).join(', ')} et al.`;
+}

package/src/lib/sections.ts

@@ -21,6 +21,7 @@ export type SectionKey =
   | 'articles'
   | 'courses'
   | 'products'
+  | 'papers'
   | 'samples'
   | 'slides'
   | 'glossary'
@@ -31,6 +32,7 @@ const DEFAULTS: Record<SectionKey, boolean> = {
   articles: true,
   courses: false, // opt-in: needs src/data/course-categories.ts on the site
   products: false, // opt-in: needs src/data/product-categories.ts on the site
+  papers: false, // opt-in: needs src/data/paper-categories.ts on the site
   samples: true,
   slides: true,
   glossary: true,

package/src/pages/[...lang]/paper/[...id].astro

@@ -0,0 +1,35 @@
+---
+import { site } from '@aas-data/site';
+import type { GetStaticPaths } from 'astro';
+import BaseLayout from '../../../layouts/BaseLayout.astro';
+import PaperDetail from '../../../components/PaperDetail.astro';
+import PrivateGate from '../../../components/PrivateGate.astro';
+import { getPapers, paperSlugOf } from '../../../lib/papers';
+import { allLocales, langParam } from '../../../lib/locales';
+
+export const getStaticPaths = (async () => {
+  const paths: Awaited<ReturnType<GetStaticPaths>> = [];
+  for (const lang of allLocales) {
+    for (const entry of await getPapers(lang)) {
+      paths.push({ params: { lang: langParam(lang), id: paperSlugOf(entry) }, props: { lang, entry } });
+    }
+  }
+  return paths;
+}) satisfies GetStaticPaths;
+
+const { lang, entry } = Astro.props;
+const slug = paperSlugOf(entry);
+const priv = entry.data.private;
+---
+
+<BaseLayout
+  title={`${entry.data.title} — ${site.name}`}
+  description={priv ? entry.data.teaser : entry.data.description}
+  lang={lang}
+  path={`paper/${slug}/`}
+  noindex={priv}
+>
+  <PrivateGate enabled={priv} lang={lang} title={entry.data.title} teaser={entry.data.teaser}>
+    <PaperDetail entry={entry} lang={lang} />
+  </PrivateGate>
+</BaseLayout>

package/src/pages/[...lang]/paper/category/[id].astro

@@ -0,0 +1,25 @@
+---
+import { site } from '@aas-data/site';
+import type { GetStaticPaths } from 'astro';
+import BaseLayout from '../../../../layouts/BaseLayout.astro';
+import PapersIndex from '../../../../components/PapersIndex.astro';
+import { paperTree } from '@aas-data/paper-categories';
+import { allLocales, langParam } from '../../../../lib/locales';
+
+export const getStaticPaths = (() => {
+  const paths: Awaited<ReturnType<GetStaticPaths>> = [];
+  for (const lang of allLocales) {
+    for (const id of paperTree.allIds) {
+      paths.push({ params: { lang: langParam(lang), id }, props: { lang, id } });
+    }
+  }
+  return paths;
+}) satisfies GetStaticPaths;
+
+const { lang, id } = Astro.props as { lang: string; id: string };
+const node = paperTree.map.get(id)!;
+---
+
+<BaseLayout title={`${node.label[lang]} — ${site.name}`} lang={lang} path={`paper/category/${id}/`}>
+  <PapersIndex lang={lang} categoryId={id} />
+</BaseLayout>

package/src/pages/[...lang]/paper/index.astro

@@ -0,0 +1,18 @@
+---
+import { site } from '@aas-data/site';
+import type { GetStaticPaths } from 'astro';
+import BaseLayout from '../../../layouts/BaseLayout.astro';
+import PapersIndex from '../../../components/PapersIndex.astro';
+import { useTranslations } from '../../../i18n/ui';
+import { allLocales, langParam } from '../../../lib/locales';
+
+export const getStaticPaths = (() =>
+  allLocales.map((lang) => ({ params: { lang: langParam(lang) }, props: { lang } }))) satisfies GetStaticPaths;
+
+const { lang } = Astro.props;
+const t = useTranslations(lang);
+---
+
+<BaseLayout title={`${t('paper.title')} — ${site.name}`} lang={lang} path="paper/">
+  <PapersIndex lang={lang} />
+</BaseLayout>

package/src/styles/global.css

@@ -2384,3 +2384,11 @@ summary {
 .aas-embed.running .aas-embed-run {
   display: none;
 }
+
+/* Tables: keep the first (label) column on one line — a wide table otherwise
+   squeezes short labels like "Part 1" into two rows. Applies to reading prose
+   and slide-deck tables alike; label columns are short by convention. */
+.prose :where(table) :where(th, td):first-child,
+.aas-slide :where(table) :where(th, td):first-child {
+  white-space: nowrap;
+}