coherent-docs-theme 1.0.6 → 1.0.7

package/components/GallerySlider.astro

@@ -31,9 +31,13 @@ let {
 } = Astro.props;
 
 let slides: CustomSlide[] = [];
+const baseUrl =
+    import.meta.env.BASE_URL === "/" ? "" : import.meta.env.BASE_URL;
 
 if (dir) {
-    const publicPath = path.join(process.cwd(), "public", dir);
+    const cleanDir = dir.replace(/\/+$/, "");
+    const publicPath = path.join(process.cwd(), "public", cleanDir);
+
     try {
         if (fs.existsSync(publicPath)) {
             const files = fs.readdirSync(publicPath);
@@ -41,11 +45,16 @@ if (dir) {
                 /\.(png|jpe?g|gif|svg|webp)$/i.test(file),
             );
             slides.push(
-                ...imageFiles.map((file) => ({ src: `/${dir}/${file}` }))
+                ...imageFiles.map((file) => ({
+                    src: `${baseUrl}/${cleanDir}/${file}`,
+                })),
             );
         }
     } catch (e) {
-        console.error(`[Gallery] Error while reading the dir: ${publicPath}`, e);
+        console.error(
+            `[Gallery] Error while reading the dir: ${publicPath}`,
+            e,
+        );
     }
 }
 
@@ -78,13 +87,26 @@ if (slides.length === 0) {
                     const altText = slide.alt || "Gallery slide";
 
                     const imgContent = isLocal ? (
-                        <Image src={slide.src as ImageMetadata} alt={altText} class="slide-img" />
+                        <Image
+                            src={slide.src as ImageMetadata}
+                            alt={altText}
+                            class="slide-img"
+                        />
                     ) : (
-                        <img src={slide.src as string} alt={altText} class="slide-img" />
+                        <img
+                            src={slide.src as string}
+                            alt={altText}
+                            class="slide-img"
+                        />
                     );
 
                     const slideBody = slide.link ? (
-                        <a href={slide.link} target="_blank" rel="noopener noreferrer" class="slide-link">
+                        <a
+                            href={slide.link}
+                            target="_blank"
+                            rel="noopener noreferrer"
+                            class="slide-link"
+                        >
                             {imgContent}
                         </a>
                     ) : (
@@ -94,7 +116,7 @@ if (slides.length === 0) {
                     return (
                         <li class="slide">
                             {slideBody}
-                            
+
                             {slide.description && (
                                 <div class="slide-caption">
                                     <p>{slide.description}</p>
@@ -171,7 +193,7 @@ if (slides.length === 0) {
         padding: 1rem 1.5rem;
         text-align: center;
         box-sizing: border-box;
-        pointer-events: none; 
+        pointer-events: none;
     }
 
     .slide-caption p {
@@ -202,8 +224,12 @@ if (slides.length === 0) {
         background: rgba(0, 0, 0, 0.9);
     }
 
-    .nav.left { left: 1rem; }
-    .nav.right { right: 1rem; }
+    .nav.left {
+        left: 1rem;
+    }
+    .nav.right {
+        right: 1rem;
+    }
 </style>
 
 <script>
@@ -225,15 +251,21 @@ if (slides.length === 0) {
 
             if (this.totalSlides === 0) return;
 
-            this.querySelector(".left")?.addEventListener("click", () => this.move("back"));
-            this.querySelector(".right")?.addEventListener("click", () => this.move("forward"));
+            this.querySelector(".left")?.addEventListener("click", () =>
+                this.move("back"),
+            );
+            this.querySelector(".right")?.addEventListener("click", () =>
+                this.move("forward"),
+            );
 
             this.resetAutoSlide();
         }
 
         move(direction: "back" | "forward") {
             if (direction === "back") {
-                this.currentSlide = (this.currentSlide - 1 + this.totalSlides) % this.totalSlides;
+                this.currentSlide =
+                    (this.currentSlide - 1 + this.totalSlides) %
+                    this.totalSlides;
             } else {
                 this.currentSlide = (this.currentSlide + 1) % this.totalSlides;
             }
@@ -249,7 +281,10 @@ if (slides.length === 0) {
         resetAutoSlide() {
             if (this.autoSlide > 0) {
                 if (this.interval) clearInterval(this.interval);
-                this.interval = setInterval(() => this.move("forward"), this.autoSlide) as any;
+                this.interval = setInterval(
+                    () => this.move("forward"),
+                    this.autoSlide,
+                ) as any;
             }
         }
     }
@@ -257,4 +292,4 @@ if (slides.length === 0) {
     if (!customElements.get("gallery-slider")) {
         customElements.define("gallery-slider", GallerySlider);
     }
-</script>
+</script>

package/components/GamefaceDocsSidebar.astro

@@ -0,0 +1,7 @@
+---
+import DefaultSidebar from "@astrojs/starlight/components/Sidebar.astro";
+import TopicSwitcher from "../internal-components/TopicSwitcher.astro";
+---
+
+<TopicSwitcher />
+<DefaultSidebar {...Astro.props} />

package/components/Highlight.astro

@@ -0,0 +1,30 @@
+---
+export interface Props {
+    light?: string;
+    dark?: string;
+}
+
+const { 
+    light = '#8e6400',
+    dark = '#F5BC35'
+} = Astro.props;
+---
+
+<span class="highlight" style={`--light-color: ${light}; --dark-color: ${dark};`}>
+    <slot />
+</span>
+
+<style>
+    .highlight {
+        font-weight: 600;
+        color: var(--light-color); 
+    }
+
+    :global([data-theme='dark']) .highlight {
+        color: var(--dark-color);
+    }
+    
+    :global([data-theme='light']) .highlight {
+        color: var(--light-color);
+    }
+</style>

package/components/Link.astro

@@ -0,0 +1,19 @@
+---
+export interface Props {
+    href: string;
+    blank?: boolean;
+}
+
+const { 
+    href, 
+    blank = true
+} = Astro.props;
+---
+
+<a 
+    href={href} 
+    target={blank ? "_blank" : undefined} 
+    rel={blank ? "noopener noreferrer" : undefined}
+>
+    <slot />
+</a>

package/components/LinkCardGrid.astro

@@ -0,0 +1,63 @@
+---
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+export interface Props {
+  cards: {
+    href: string;
+    title: string;
+    imgSrc: string;
+    description: string;
+  }[];
+}
+
+const { cards } = Astro.props;
+---
+
+<CardGrid class="custom-card-grid">
+  {cards.map((card) => (
+    <a class="card-link" href={card.href}>
+      <Card title={card.title}>
+        <img src={card.imgSrc} class="card-image" alt={card.title} />
+        <p>{card.description}</p>
+      </Card>
+    </a>
+  ))}
+</CardGrid>
+
+<style>
+  .custom-card-grid {
+    display: grid;
+    grid-template-columns: repeat(3, minmax(0, 1fr)) !important;
+    gap: 1.5rem;
+    margin-top: 3rem;
+  }
+
+  @media (max-width: 90rem) {
+    .custom-card-grid {
+      grid-template-columns: repeat(2, minmax(0, 1fr)) !important;
+    }
+  }
+
+  @media (max-width: 70rem) {
+    .custom-card-grid {
+      grid-template-columns: 1fr !important;
+    }
+  }
+
+  .card-link {
+    text-decoration: none;
+    position: relative;
+  }
+
+  .card-link p {
+    color: var(--sl-color-text);
+  }
+
+  .card-image {
+    width: 100%;
+    height: 10rem;
+    object-fit: cover;
+    object-position: top center;
+    margin-bottom: 1rem;
+  }
+</style>

package/components/NativeLink.astro

@@ -0,0 +1,24 @@
+---
+export interface Props {
+    href: string;
+    product?: string; 
+}
+
+const { href, product } = Astro.props;
+
+const currentProduct = product || process.env.DOCS_PRODUCT || 'gameface';
+
+const productPaths: Record<string, string> = {
+    'gameface': 'cpp-gameface',
+    'prysm': 'cpp-prysm',
+};
+
+const urlSegment = productPaths[currentProduct.toLowerCase()] || `cpp-${currentProduct.toLowerCase()}`;
+
+const baseUrl = `https://docs.coherent-labs.com/${urlSegment}`;
+
+const cleanHref = !href ? "/" : href.startsWith("/") ? href : `/${href}`;
+const fullUrl = `${baseUrl}${cleanHref}`;
+---
+
+<a href={fullUrl} target="_blank" rel="noopener noreferrer"><slot /></a>

package/components/Summary.astro

@@ -0,0 +1,18 @@
+<div class="summary">
+    <slot />
+</div>
+
+<style>
+    .summary {
+        font-size: 1.15rem;
+        line-height: 1.6;
+        color: var(--sl-color-gray-2);
+        margin-bottom: 2rem;
+    }
+
+    .summary :global(p) {
+        font-size: inherit;
+        line-height: inherit;
+        color: inherit;
+    }
+</style>

package/components/index.ts

@@ -0,0 +1,23 @@
+export { default as Api } from './Api.astro';
+export { default as BeforeAfter } from './BeforeAfter.astro';
+export { default as Details } from './Details.astro';
+export { default as Enhancement } from './Enhancement.astro';
+export { default as Feature } from './Feature.astro';
+export { default as Figure } from './Figure.astro';
+export { default as Fix } from './Fix.astro';
+export { default as GallerySlider } from './GallerySlider.astro';
+export { default as GamefaceDocsSidebar } from './GamefaceDocsSidebar.astro';
+export { default as Highlight } from './Highlight.astro';
+export { default as If } from './If.astro';
+export { default as IfEnv } from './IfEnv.astro';
+export { default as IfNot } from './IfNot.astro';
+export { default as IncludeSnippets } from './IncludeSnippets.astro';
+export { default as Internal } from './Internal.astro';
+export { default as Link } from './Link.astro';
+export { default as LinkCardGrid } from './LinkCardGrid.astro';
+export { default as NativeLink } from './NativeLink.astro';
+export { default as ProductName } from './ProductName.astro';
+export { default as Release } from './Release.astro';
+export { default as SideBarWithDropdown } from './SideBarWithDropdown.astro';
+export { default as Summary } from './Summary.astro';
+export { default as Typeref } from './Typeref.astro';

package/index.ts

@@ -10,33 +10,71 @@ import { fileURLToPath } from 'url';
 import { directives } from './remark-directives';
 import { getSortedCoherentReleases } from './utils/coherentReleases';
 import { version } from './package.json';
+import { remarkFixAbsoluteLinks } from './remark-directives/fixAbsoluteLinks';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const defaultHeaderLinks = [
-  { href: 'https://docs.coherent-labs.com/cpp-gameface', label: 'Gameface' },
-  { href: 'https://docs.coherent-labs.com/cpp-prysm', label: 'Prysm' },
+  { href: 'https://docs.coherent-labs.com/cpp-gameface', label: 'Gameface', subDocumentations: ['Unreal', 'Unity'] },
+  { href: 'https://docs.coherent-labs.com/cpp-prysm', label: 'Prysm', subDocumentations: ['Unreal', 'Unity'] },
   { href: 'https://starter.coherent-labs.com/', label: 'UI Starter Guide' },
   { href: 'https://frontend-tools.coherent-labs.com', label: 'UI Tools' },
   { href: 'https://gameface-ui.coherent-labs.com', label: 'Gameface UI' },
   { href: 'https://coherent-labs.com/Documentation/ExporterLTS/', label: 'Adobe CC Tools' },
 ];
+
 const defaultMergeIndex = [
   {
     bundlePath: "https://gameface-ui.coherent-labs.com/pagefind",
     indexWeight: 0.5,
-    mergeFilter: {
-      resource: "Gameface UI"
-    }
+    mergeFilter: { resource: "Gameface UI" }
   },
   {
     bundlePath: "https://frontend-tools.coherent-labs.com/pagefind",
     indexWeight: 0.5,
-    mergeFilter: {
-      resource: "UI Tools"
-    }
+    mergeFilter: { resource: "UI Tools" }
+  },
+  {
+    bundlePath: "https://docs.coherent-labs.com/cpp-gameface/pagefind",
+    indexWeight: 0.5,
+    mergeFilter: { resource: "Gameface Custom Engine" }
+  },
+  {
+    bundlePath: "https://docs.coherent-labs.com/cpp-prysm/pagefind",
+    indexWeight: 0.5,
+    mergeFilter: { resource: "Prysm Custom Engine" }
+  },
+  {
+    bundlePath: "https://docs.coherent-labs.com/unreal-gameface/pagefind",
+    indexWeight: 0.5,
+    mergeFilter: { resource: "Gameface Unreal" }
+  },
+  {
+    bundlePath: "https://docs.coherent-labs.com/unreal-prysm/pagefind",
+    indexWeight: 0.5,
+    mergeFilter: { resource: "Prysm Unreal" }
+  },
+  {
+    bundlePath: "https://docs.coherent-labs.com/unity-gameface/pagefind",
+    indexWeight: 0.5,
+    mergeFilter: { resource: "Gameface Unity" }
+  },
+  {
+    bundlePath: "https://docs.coherent-labs.com/unity-prysm/pagefind",
+    indexWeight: 0.5,
+    mergeFilter: { resource: "Prysm Unity" }
   }
-]
+];
+
+async function isPagefindIndexAvailable(bundlePath: string): Promise<boolean> {
+  try {
+    const metaUrl = `${bundlePath.replace(/\/$/, '')}/pagefind-entry.json`;
+    const response = await fetch(metaUrl, { method: 'HEAD' });
+    return response.ok;
+  } catch (e) {
+    return false;
+  }
+}
 
 export default function coherentThemePlugin(options: CoherentThemeOptions = { documentationSearchTag: '' }): StarlightPlugin[] {
   if (!options?.documentationSearchTag) {
@@ -56,7 +94,7 @@ export default function coherentThemePlugin(options: CoherentThemeOptions = { do
   const corePlugin: StarlightPlugin = {
     name: 'coherent-docs-theme',
     hooks: {
-      'config:setup'({ config, logger, updateConfig, addIntegration }) {
+      async 'config:setup'({ config, astroConfig, logger, updateConfig, addIntegration, command }) {
         logger.info(`Initializing Coherent Theme v${version}...`);
 
         addIntegration({
@@ -65,24 +103,34 @@ export default function coherentThemePlugin(options: CoherentThemeOptions = { do
             'astro:config:setup': ({ updateConfig }) => {
               updateConfig({
                 markdown: {
-                  remarkPlugins: [...directives],
+                  remarkPlugins: [...directives, [remarkFixAbsoluteLinks, { basePath: astroConfig.base }]],
                 },
               });
             }
           }
         });
 
-        process.env.COHERENT_THEME_CONFIG = JSON.stringify({ showPageProgress, navLinks, documentationSearchTag: options.documentationSearchTag });
+        process.env.COHERENT_THEME_CONFIG = JSON.stringify({
+          showPageProgress,
+          navLinks,
+          documentationSearchTag: options.documentationSearchTag,
+          tagManagerId: options.tagManagerId,
+          breadcrumbs: options.breadcrumbs,
+          topicsConfig: options.topicsConfig,
+          currentTopicId: options.currentTopicId,
+          version: options.version
+        });
 
         const configUpdates: any = {
           customCss: [...(config.customCss ?? []), 'coherent-docs-theme/styles'],
           components: overrideComponents(
             config,
-            ['Header', 'ThemeSelect', 'Footer', 'Search'],
+            ['Header', 'ThemeSelect', 'Footer', 'Search', 'PageTitle', 'MarkdownContent'],
             logger,
           ),
           head: config.head || [],
         };
+
         if (!disableDefaultLogo && !config.logo) {
           configUpdates.logo = {
             dark: path.join(__dirname, 'assets/gameface-ui-header-dark.svg'),
@@ -97,15 +145,37 @@ export default function coherentThemePlugin(options: CoherentThemeOptions = { do
             'data-pagefind-filter': 'resource[content]',
             content: options.documentationSearchTag
           }
-        })
-
-        configUpdates.pagefind = {
-          indexWeight: 2,
-          mergeIndex: defaultMergeIndex.filter(merge => {
-            const resource = merge.mergeFilter.resource;
-            return resource !== options.documentationSearchTag;
-          })
-        };
+        });
+
+        if (command === 'build') {
+          const otherIndexes = defaultMergeIndex.filter(merge =>
+            merge.mergeFilter.resource !== options.documentationSearchTag
+          );
+
+          logger.info('Validating external Pagefind indexes for production build...');
+          const validMergeIndexes = [];
+
+          for (const mergeConfig of otherIndexes) {
+            const isAvailable = await isPagefindIndexAvailable(mergeConfig.bundlePath);
+            if (isAvailable) {
+              validMergeIndexes.push(mergeConfig);
+              logger.info(`✅ Found index: ${mergeConfig.mergeFilter.resource}`);
+            } else {
+              logger.warn(`⚠️ Skipping index (not found): ${mergeConfig.mergeFilter.resource} at ${mergeConfig.bundlePath}`);
+            }
+          }
+
+          configUpdates.pagefind = {
+            indexWeight: 2,
+            mergeIndex: validMergeIndexes
+          };
+        } else {
+          logger.info('Dev mode detected. Skipping external Pagefind index validation.');
+          configUpdates.pagefind = {
+            indexWeight: 2,
+            mergeIndex: []
+          };
+        }
 
         updateConfig(configUpdates);
       },

package/internal/themeConfig.ts

@@ -1,13 +1,43 @@
+interface Topic {
+    label?: string
+    href?: string
+    icon?: string
+}
+
 export interface CoherentThemeOptions {
-    documentationSearchTag: string
+    documentationSearchTag:
+    'Gameface Custom Engine' | 'Prysm Custom Engine' |
+    'Gameface Unreal' | 'Prysm Unreal' |
+    'Gameface Unity' | 'Prysm Unity' |
+    'UI Tools' |
+    'Gameface UI' | string
+    topicsConfig?: {
+        native?: Topic
+        unreal?: Topic
+        unity?: Topic
+    }
+    version?: string
+    currentTopicId?: string
     showPageProgress?: boolean;
-    navLinks?: Array<{ label: string; href: string }>;
+    navLinks?: Array<{ label: string; href: string, subDocumentations?: string[] }>;
     disableDefaultLogo?: boolean;
     replacesTitle?: boolean
+    tagManagerId?: string
+    breadcrumbs?: boolean
 }
 
 export default function getThemeConfig(): CoherentThemeOptions {
-    let themeConfig = { documentationSearchTag: '', showPageProgress: false, navLinks: [], disableDefaultLogo: false } as CoherentThemeOptions;
+    let themeConfig = {
+        documentationSearchTag: '',
+        showPageProgress: false,
+        navLinks: [],
+        disableDefaultLogo: false,
+        tagManagerId: '',
+        breadcrumbs: true,
+        topicsConfig: {},
+        currentTopicId: 'native',
+        version: '0.0.0.0'
+    } as CoherentThemeOptions;
 
     if (process.env.COHERENT_THEME_CONFIG) {
         try {

package/internal-components/BreadcrumbArrow.astro

@@ -0,0 +1,12 @@
+<svg
+    width="14"
+    height="14"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="2"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+>
+    <polyline points="6 9 12 15 18 9"></polyline>
+</svg>

package/internal-components/NavLinks.astro

@@ -9,8 +9,19 @@ interface Props {
 const { type = "header" } = Astro.props;
 const { navLinks, documentationSearchTag } = getThemeConfig();
 
-const isLinkActive = (href: string, label: string) => {
+const isLinkActive = (href: string, label: string, subDocumentations?: string[]) => {
     try {
+        if (documentationSearchTag) {
+            if (documentationSearchTag === label) return true;
+
+            if (subDocumentations && subDocumentations.length > 0) {
+                const possibleTags = subDocumentations.map(sub => `${label} ${sub}`);
+                if (possibleTags.includes(documentationSearchTag)) {
+                    return true;
+                }
+            }
+        }
+
         const linkUrl = new URL(href, Astro.url.origin);
         const currentUrl = Astro.url;
         const isLocal =
@@ -39,7 +50,7 @@ const navClasses =
         : "extra-links mobile sidebar-mode lg:hidden";
 
 const activeLinkObj = navLinks?.find((link) =>
-    isLinkActive(link.href, link.label),
+    isLinkActive(link.href, link.label, link.subDocumentations),
 );
 const activeLabel = activeLinkObj ? activeLinkObj.label : "Documentations";
 ---
@@ -61,7 +72,7 @@ const activeLabel = activeLinkObj ? activeLinkObj.label : "Documentations";
                         <li class="nav-item">
                             <a
                                 href={link.href}
-                                class={`nav-link ${isLinkActive(link.href, link.label) ? "active" : ""}`}
+                                class={`nav-link ${isLinkActive(link.href, link.label, link.subDocumentations) ? "active" : ""}`}
                             >
                                 {link.label}
                             </a>
@@ -80,7 +91,7 @@ const activeLabel = activeLinkObj ? activeLinkObj.label : "Documentations";
                             <li>
                                 <a
                                     href={link.href}
-                                    class={`dropdown-link ${isLinkActive(link.href, link.label) ? "active" : ""}`}
+                                    class={`dropdown-link ${isLinkActive(link.href, link.label, link.subDocumentations) ? "active" : ""}`}
                                 >
                                     {link.label}
                                 </a>