Make index pages prettier (#8)

docusaurus.config.ts

@@ -15,14 +15,16 @@ fs.writeFileSync(path.join(__dirname, 'static/theoplayer-license.txt'), theoplay
 const docsConfigBase = {
   include: [
     '**/*.{md,mdx}',
-    // Only include docs folder from external projects
-    '!external/**/*',
-    'external/**/CHANGELOG.md',
+    // For external projects: include changelogs and /docs folder
+    'external/*/CHANGELOG.md',
+    'external/*/*/CHANGELOG.md',
     'external/*/docs/**/*.{md,mdx}',
   ],
   exclude: [
     // Remove index pages from external projects, we'll generate our own instead
     'external/*/docs/**/index.{md,mdx}',
+    // Ignore node_modules
+    'external/**/node_modules/**/*',
   ],
   editUrl: ({ versionDocsDirPath, docPath }) => {
     if (docPath.startsWith('external')) {

open-video-ui/index.mdx

@@ -7,8 +7,6 @@ The Open Video UI provides component libraries for building a world-class video
 
 On these pages, you'll learn how to get started with the Open Video UI and make your very own UI.
 
-<!-- TODO Make this prettier -->
+import SidebarDocCardList from '@site/src/components/SidebarDocCardList';
 
-- [Web](./web/)
-- [React](./react/)
-- [Android](./android/)
+<SidebarDocCardList />

sidebarsOpenVideoUI.ts

@@ -16,7 +16,15 @@ const sidebars: SidebarsConfig = {
     {
       type: 'category',
       label: 'Web',
-      link: { type: 'generated-index', slug: 'web' },
+      description: 'Build an astonishing player UI with Web Components.',
+      customProps: {
+        icon: '🌐',
+      },
+      link: {
+        type: 'generated-index',
+        slug: 'web',
+        title: 'Open Video UI for Web',
+      },
       items: [
         { type: 'doc', id: 'web/getting-started' },
         {
@@ -42,7 +50,15 @@ const sidebars: SidebarsConfig = {
     {
       type: 'category',
       label: 'React',
-      link: { type: 'generated-index', slug: 'react' },
+      description: 'Build a stunning player UI with React components.',
+      customProps: {
+        icon: '⚛️',
+      },
+      link: {
+        type: 'generated-index',
+        slug: 'react',
+        title: 'Open Video UI for React',
+      },
       items: [
         { type: 'doc', id: 'react/getting-started' },
         {
@@ -64,7 +80,15 @@ const sidebars: SidebarsConfig = {
     {
       type: 'category',
       label: 'Android',
-      link: { type: 'generated-index', slug: 'android' },
+      description: 'Build a mobile-first player UI for Android with Jetpack Compose.',
+      customProps: {
+        icon: '🤖',
+      },
+      link: {
+        type: 'generated-index',
+        slug: 'android',
+        title: 'Open Video UI for Android',
+      },
       items: [
         { type: 'doc', id: 'android/getting-started' },
         {

sidebarsTheoplayer.ts

@@ -12,10 +12,45 @@ import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
  */
 const sidebars: SidebarsConfig = {
   theoplayer: [
-    { type: 'autogenerated', dirName: '.' },
+    'index',
+    {
+      type: 'category',
+      label: 'Getting started',
+      description: 'Set up your first THEOplayer in just a few minutes!',
+      customProps: {
+        icon: '🚀',
+      },
+      link: { type: 'doc', id: 'getting-started/index' },
+      items: [{ type: 'autogenerated', dirName: 'getting-started' }],
+    },
+    {
+      type: 'category',
+      label: 'Guides',
+      description: 'Learn how to implement our rich set of features and integrations.',
+      customProps: {
+        icon: '📖',
+      },
+      link: { type: 'generated-index', slug: 'guides' },
+      items: [{ type: 'autogenerated', dirName: 'guides' }],
+    },
+    {
+      type: 'category',
+      label: 'Examples',
+      description: 'See the player in action!',
+      customProps: {
+        icon: '🛝',
+      },
+      link: { type: 'generated-index', slug: 'examples' },
+      items: [{ type: 'autogenerated', dirName: 'examples' }],
+    },
+    'changelog',
     {
       type: 'category',
       label: 'API references',
+      description: 'Discover all properties and functions of THEOplayer.',
+      customProps: {
+        icon: '*️⃣',
+      },
       link: { type: 'generated-index', slug: 'api' },
       items: [
         {

src/components/SidebarDocCardList/index.tsx

@@ -0,0 +1,13 @@
+import { useDoc, useDocsSidebar } from '@docusaurus/theme-common/internal';
+import DocCardList, { type Props as DocCardListProps } from '@theme/DocCardList';
+
+export interface Props extends Omit<DocCardListProps, 'items'> {}
+
+export default function SidebarDocCardList(props: Props) {
+  const doc = useDoc();
+  const sidebar = useDocsSidebar();
+  const items = sidebar.items
+    // Hide the current doc page from list
+    .filter((item) => !(item.type === 'link' && item.docId === doc.metadata.id));
+  return <DocCardList items={items} {...props} />;
+}

src/theme/DocCard/index.tsx

@@ -4,6 +4,8 @@ import Link from '@docusaurus/Link';
 import { findFirstSidebarItemLink, useDocById } from '@docusaurus/theme-common/internal';
 import isInternalUrl from '@docusaurus/isInternalUrl';
 import { translate } from '@docusaurus/Translate';
+import type { Props } from '@theme/DocCard';
+import type { PropSidebarItemCategory, PropSidebarItemLink } from '@docusaurus/plugin-content-docs';
 import Heading from '@theme/Heading';
 import styles from './styles.module.css';
 
@@ -22,15 +24,15 @@ function CardLayout({ href, icon, title, description }) {
         {icon} {title}
       </Heading>
       {description && (
-        <p className={clsx('text--truncate', styles.cardDescription)} title={description}>
+        <p className={clsx(styles.cardDescription)}>
           {description}
         </p>
       )}
     </CardContainer>
   );
 }
 
-function CardCategory({ item }) {
+function CardCategory({ item }: { item: PropSidebarItemCategory }) {
   const icon = item.customProps?.icon ?? '🗃️';
   const href = findFirstSidebarItemLink(item);
   // Unexpected: categories that don't have a link have been filtered upfront
@@ -57,13 +59,13 @@ function CardCategory({ item }) {
   );
 }
 
-function CardLink({ item }) {
+function CardLink({ item }: { item: PropSidebarItemLink }) {
   const icon = item.customProps?.icon ?? (isInternalUrl(item.href) ? '📄️' : '🔗');
   const doc = useDocById(item.docId ?? undefined);
   return <CardLayout href={item.href} icon={icon} title={item.label} description={item.description ?? doc?.description} />;
 }
 
-export default function DocCard({ item }) {
+export default function DocCard({ item }: Props) {
   switch (item.type) {
     case 'link':
       return <CardLink item={item} />;

src/theme/DocCardList/index.tsx

@@ -0,0 +1,34 @@
+import React from 'react';
+import clsx from 'clsx';
+import { filterDocCardListItems, useCurrentSidebarCategory } from '@docusaurus/theme-common';
+import type { PropSidebarItem } from '@docusaurus/plugin-content-docs';
+import type { Props } from '@theme/DocCardList';
+import DocCard from '@theme/DocCard';
+
+function DocCardListForCurrentSidebarCategory({ className }: Props) {
+  const category = useCurrentSidebarCategory();
+  return <DocCardList items={category.items} className={className} />;
+}
+
+function isIndexLink(item: PropSidebarItem): boolean {
+  return item.type === 'link' && item.docId && item.docId.endsWith('/index');
+}
+
+export default function DocCardList(props: Props) {
+  const { items, className } = props;
+  if (!items) {
+    return <DocCardListForCurrentSidebarCategory {...props} />;
+  }
+  const filteredItems = filterDocCardListItems(items)
+    // Remove link to index page
+    .filter((item) => !isIndexLink(item));
+  return (
+    <section className={clsx('row', className)}>
+      {filteredItems.map((item, index) => (
+        <article key={index} className="col col--6 margin-bottom--lg">
+          <DocCard item={item} />
+        </article>
+      ))}
+    </section>
+  );
+}

theoplayer/getting-started/index.mdx

@@ -1,3 +1,10 @@
+---
+sidebar_position: 0
+sidebar_label: Overview
+pagination_label: Getting started
+pagination_next: getting-started/web
+---
+
 # Getting started
 
 THEOplayer offers a rich portfolio of video SDKs for many platforms and frameworks across desktop, mobile and TV devices.

theoplayer/index.mdx

@@ -8,8 +8,6 @@ THEOplayer is the universal video player solution created by THEO Technologies.
 
 On these pages, you'll learn how to get started with THEOplayer, how to use the various features, and explore the many examples.
 
-<!-- TODO Make this prettier -->
+import SidebarDocCardList from '@site/src/components/SidebarDocCardList';
 
-- [Getting started](./getting-started/)
-- [Guides](./guides/)
-- [API references](./api)
+<SidebarDocCardList />