docs: host the docs on Read the Docs

.readthedocs.yaml

@@ -0,0 +1,18 @@
+# Read the Docs configuration for the documentation app (apps/documentation).
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html
+#
+# Pull request previews and per-branch builds are project settings on Read
+# the Docs ("Build pull requests" and an "activate" automation rule for
+# branches), not part of this file.
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    # Same major version as the docs image (Dockerfile) once #466 is done
+    nodejs: "24"
+  commands:
+    - npm ci --no-audit --no-fund
+    - npx turbo run build --filter=ecc-docs...
+    - mkdir -p $READTHEDOCS_OUTPUT
+    - cp -r apps/documentation/out $READTHEDOCS_OUTPUT/html

apps/documentation/components/common/Footer.tsx

@@ -1,37 +1,38 @@
 import Image from 'next/image';
+import { withBasePath } from '@/utils/basePath';
 
 function Footer() {
   return (
     <div className='flex justify-center items-center p-1 border-t dark:border-zinc-800 border-zinc-200 rounded-md'>
       <div className='container flex flex-col sm:flex-row justify-between px-4 py-4'>
         <div className='flex justify-center items-center my-2 gap-4'>
           <a href='https://elixir-cloud.dcc.sib.swiss/' target='_blank' rel='noopener noreferrer'>
-            <Image src='/elixir-cloud/logo.svg' alt='Elixir Cloud & AAI' width={75} height={75} />
+            <Image src={withBasePath('/elixir-cloud/logo.svg')} alt='Elixir Cloud & AAI' width={75} height={75} />
           </a>
           <Image
-            src='/cloud-sdk/dark.svg'
+            src={withBasePath('/cloud-sdk/dark.svg')}
             alt='Cloud SDK'
             width={75}
             height={75}
             className='dark:block hidden'
           />
           <Image
-            src='/cloud-sdk/light.svg'
+            src={withBasePath('/cloud-sdk/light.svg')}
             alt='Cloud SDK'
             width={75}
             height={75}
             className='block dark:hidden'
           />
           <a href='https://elixir-europe.org/' target='_blank' rel='noopener noreferrer'>
             <Image
-              src='/elixir/dark.png'
+              src={withBasePath('/elixir/dark.png')}
               alt='Elixir'
               width={75}
               height={75}
               className='dark:block hidden ml-2'
             />
             <Image
-              src='/elixir/light.svg'
+              src={withBasePath('/elixir/light.svg')}
               alt='Elixir'
               width={95}
               height={95}

apps/documentation/components/home/Hero.tsx

@@ -1,8 +1,10 @@
 'use client';
+import { useRouter } from 'next/router';
 import { RiArrowRightLine, RiGithubLine } from '@remixicon/react';
 import { EccUtilsDesignButton } from '@elixir-cloud/design/react';
 
 export default function Hero() {
+  const router = useRouter();
   return (
     <div className='mx-auto static mt-12 md:mt-[6rem] flex flex-col items-center'>
       <div className='flex flex-col items-center w-full md:w-5/6 max-w-6xl'>
@@ -29,7 +31,7 @@ export default function Hero() {
         <div className='flex flex-col sm:flex-row gap-4 mt-10 md:mt-12 text-sm md:text-base items-center justify-center'>
           <EccUtilsDesignButton
             onClick={() => {
-              window.location.href = '/docs/introduction';
+              router.push('/docs/introduction');
             }}
             variant='default'
             className='part:bg-sky-600 part:hover:bg-sky-500 part:text-white'

apps/documentation/components/home/ServicesShowcase.tsx

@@ -1,5 +1,6 @@
 'use client';
 import { useState } from 'react';
+import Link from 'next/link';
 import { useTheme } from 'next-themes';
 import RunsPreview from '@/components/packages/wes/RunsPreview';
 import RunCreatePreview from '@/components/packages/wes/RunCreatePreview';
@@ -134,9 +135,9 @@ export default function ServicesShowcase() {
         </div>
         <div className='flex justify-center mt-4'>
           <div className='flex items-center justify-center'>
-            <a href={services[activeService].link} className='inline-flex items-center px-4 py-2 text-sm font-medium text-sky-600 dark:text-sky-400 bg-sky-50 dark:bg-sky-900/20 rounded-lg hover:bg-sky-100 dark:hover:bg-sky-900/30 transition-colors'>
+            <Link href={services[activeService].link} className='inline-flex items-center px-4 py-2 text-sm font-medium text-sky-600 dark:text-sky-400 bg-sky-50 dark:bg-sky-900/20 rounded-lg hover:bg-sky-100 dark:hover:bg-sky-900/30 transition-colors'>
               View More Components
-            </a>
+            </Link>
           </div>
         </div>
       </div>

apps/documentation/next.config.js

@@ -7,11 +7,22 @@ const withNextra = require('nextra')({
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const withLitSSR = require('@lit-labs/nextjs')();
 
+// Read the Docs serves each version under a subpath (e.g. /en/latest/ or
+// /en/<pr-number>/), given by READTHEDOCS_CANONICAL_URL at build time.
+// Outside Read the Docs, the variable is unset and nothing changes.
+const rtdUrl = process.env.READTHEDOCS_CANONICAL_URL;
+const basePath = rtdUrl ? new URL(rtdUrl).pathname.replace(/\/$/, '') : '';
+const rtdConfig = rtdUrl ? { basePath, trailingSlash: true } : {};
+
 /** @type {import('next').NextConfig} */
 module.exports = withLitSSR({
   ...withNextra(),
   output: 'export',
   images: {
     unoptimized: true,
   },
+  // Always set, so that a stray NEXT_PUBLIC_BASE_PATH in the environment
+  // can't prefix assets without a matching basePath.
+  env: { NEXT_PUBLIC_BASE_PATH: basePath },
+  ...rtdConfig,
 });

apps/documentation/pages/docs/introduction.mdx

@@ -1,3 +1,4 @@
+import Link from 'next/link';
 import { Callout } from 'nextra/components';
 import { Steps } from 'nextra/components';
 import {
@@ -34,9 +35,9 @@ While we are continuously expanding the ECC suite, the current version includes
         </td>
         <td className="py-2 px-3">
           <div className="flex items-center justify-center gap-3">
-            <a href="/docs/service-registry/introduction" title="Documentation" className="text-gray-500 hover:text-blue-600 dark:hover:text-blue-400">
+            <Link href="/docs/service-registry/introduction" title="Documentation" className="text-gray-500 hover:text-blue-600 dark:hover:text-blue-400">
               <RiBook2Line size={16} />
-            </a>
+            </Link>
             <a href="https://cloud-registry.anuragxd.com" title="Live Demo" target="_blank" rel="noopener noreferrer" className="text-gray-500 hover:text-green-600 dark:hover:text-green-400">
               <RiExternalLinkLine size={16} />
             </a>
@@ -55,9 +56,9 @@ While we are continuously expanding the ECC suite, the current version includes
         </td>
         <td className="py-2 px-3">
           <div className="flex items-center justify-center gap-3">
-            <a href="/docs/cloud-registry/introduction" title="Documentation" className="text-gray-500 hover:text-blue-600 dark:hover:text-blue-400">
+            <Link href="/docs/cloud-registry/introduction" title="Documentation" className="text-gray-500 hover:text-blue-600 dark:hover:text-blue-400">
               <RiBook2Line size={16} />
-            </a>
+            </Link>
             <a href="https://cloud-registry.anuragxd.com" title="Live Demo" target="_blank" rel="noopener noreferrer" className="text-gray-500 hover:text-green-600 dark:hover:text-green-400">
               <RiExternalLinkLine size={16} />
             </a>
@@ -76,9 +77,9 @@ While we are continuously expanding the ECC suite, the current version includes
         </td>
         <td className="py-2 px-3">
           <div className="flex items-center justify-center gap-3">
-            <a href="/docs/trs/introduction" title="Documentation" className="text-gray-500 hover:text-blue-600 dark:hover:text-blue-400">
+            <Link href="/docs/trs/introduction" title="Documentation" className="text-gray-500 hover:text-blue-600 dark:hover:text-blue-400">
               <RiBook2Line size={16} />
-            </a>
+            </Link>
             <a href="https://trs-filer.anuragxd.com" title="Live Demo" target="_blank" rel="noopener noreferrer" className="text-gray-500 hover:text-green-600 dark:hover:text-green-400">
               <RiExternalLinkLine size={16} />
             </a>
@@ -97,9 +98,9 @@ While we are continuously expanding the ECC suite, the current version includes
         </td>
         <td className="py-2 px-3">
           <div className="flex items-center justify-center gap-3">
-            <a href="/docs/trs-filer/introduction" title="Documentation" className="text-gray-500 hover:text-blue-600 dark:hover:text-blue-400">
+            <Link href="/docs/trs-filer/introduction" title="Documentation" className="text-gray-500 hover:text-blue-600 dark:hover:text-blue-400">
               <RiBook2Line size={16} />
-            </a>
+            </Link>
             <a href="https://trs-filer.anuragxd.com" title="Live Demo" target="_blank" rel="noopener noreferrer" className="text-gray-500 hover:text-green-600 dark:hover:text-green-400">
               <RiExternalLinkLine size={16} />
             </a>
@@ -118,9 +119,9 @@ While we are continuously expanding the ECC suite, the current version includes
         </td>
         <td className="py-2 px-3">
           <div className="flex items-center justify-center gap-3">
-            <a href="/docs/wes/introduction" title="Documentation" className="text-gray-500 hover:text-blue-600 dark:hover:text-blue-400">
+            <Link href="/docs/wes/introduction" title="Documentation" className="text-gray-500 hover:text-blue-600 dark:hover:text-blue-400">
               <RiBook2Line size={16} />
-            </a>
+            </Link>
             <a href="https://weskit.anuragxd.com" title="Live Demo" target="_blank" rel="noopener noreferrer" className="text-gray-500 hover:text-green-600 dark:hover:text-green-400">
               <RiExternalLinkLine size={16} />
             </a>

apps/documentation/theme.config.tsx

@@ -1,14 +1,15 @@
 import { useRouter } from 'next/router'
 import { DocsThemeConfig } from 'nextra-theme-docs';
 import Image from 'next/image';
+import { withBasePath } from './utils/basePath';
 import { RiSlackFill, RiGithubFill } from '@remixicon/react';
 
 import Footer from './components/common/Footer';
 
 const config: DocsThemeConfig = {
   logo: (
     <div className='flex gap-3 items-center'>
-      <Image src='/elixir-cloud/logo.svg' alt='Logo' width={44} height={44} />
+      <Image src={withBasePath('/elixir-cloud/logo.svg')} alt='Logo' width={44} height={44} />
       <span className='tracking-wide font-semibold'>ELIXIR Cloud Components</span>
     </div>
   ),
@@ -26,6 +27,15 @@ const config: DocsThemeConfig = {
     component: <Footer />,
   },
   gitTimestamp: false,
+  // Replaces Nextra's default head: keep its generic tags, drop its own
+  // branding (description and social tags).
+  head: (
+    <>
+      <meta name="msapplication-TileColor" content="#fff" />
+      <meta httpEquiv="Content-Language" content="en" />
+      <link rel="icon" href={withBasePath('/favicon.ico')} />
+    </>
+  ),
   nextThemes: {
     defaultTheme: 'light'
   },

apps/documentation/utils/basePath.ts

@@ -0,0 +1,4 @@
+// Prefix for files in public/ when the site is served under a subpath
+// (set in next.config.js, e.g. on Read the Docs); empty otherwise.
+export const withBasePath = (path: string): string =>
+  `${process.env.NEXT_PUBLIC_BASE_PATH ?? ''}${path}`;

turbo.json

@@ -7,7 +7,8 @@
     },
     "build": {
       "outputs": ["dist/**"],
-      "dependsOn": ["^build"]
+      "dependsOn": ["^build"],
+      "env": ["READTHEDOCS_CANONICAL_URL", "NEXT_PUBLIC_BASE_PATH"]
     },
     "test": {
       "inputs": [],