Organisez votre contenu Docusaurus avec un composant Series personnalisé

/**
 * getBlogMetadata
 *
 * Extracts metadata from all MDX blog posts located in the `/blog` directory.
 * Uses Webpack's `require.context` to dynamically load and parse frontmatter
 * from each post, returning a structured array of metadata objects.
 *
 * Behavior:
 * - Resolves permalinks based on `slug` or folder structure
 * - Normalizes image paths for static assets
 * - Filters out invalid or missing entries
 *
 * Returned metadata includes:
 * - `title`: Post title
 * - `description`: Short summary
 * - `image`: Resolved image path
 * - `draft`: Boolean flag for unpublished posts
 * - `unlisted`: Boolean flag for hidden posts
 * - `permalink`: URL path to the post
 * - `tags`: Array of tags
 * - `mainTag`: Primary tag (optional); used by the RelatedBlogPost component
 * - `authors`: Array of author names
 * - `date`: Publication date
 * - `series`: Series name (optional); used by the SeriesBlogPost component
 *
 * Usage:
 * ```ts
 * import { getBlogMetadata } from './posts';
 * const posts = getBlogMetadata();
 * const withDrafts = getBlogMetadata({ includeDrafts: true });
 * ```
 *
 * By default, posts flagged `draft` or `unlisted` are excluded so consumers don't have to
 * remember to filter them out themselves. Pass `includeDrafts`/`includeUnlisted` to opt back in
 * (e.g. author-facing counters that need to show "in progress" articles).
 *
 * Note:
 * This function is intended for use in static site generation or client-side rendering
 * where Webpack's `require.context` is available.
 */

/**
 * A tag as it reaches these helpers: a plain slug string from front matter, or —
 * defensively, since related.ts and TagArticlesPage both handle it — a
 * Docusaurus-normalised tag object.
 */
export type BlogTag = string | { label: string };?

export interface BlogPostMetadata {
  authors: string[];
  blueskyRecordKey: string | null;
  /**
   * ISO date string from front matter, e.g. "2026-08-28". Every article under blog/ carries
   * one (blog authoring convention, and the blog plugin itself refuses a post without a
   * date), so this is not optional.
   *
   * Runtime note: plugins/frontmatter-loader actually hands back a real `Date` instance for
   * a typical unquoted YAML date (see that plugin's own header comment) — not a string.
   * Declaring `string` here anyway matches the pre-existing contract every niveau 1-4 `.tsx`
   * consumer already compiles against (`Post.date?: string`, …); every one of them passes
   * this straight into `new Date(...)`, which accepts a `Date` argument just as well as a
   * string, so nothing behavioral changes. Widening this to the more literally accurate type
   * would ripple into every already-migrated consumer — out of scope here.
   */
  date: string;?
  description: string | undefined;
  draft: boolean;
  image: string | undefined;
  mainTag: string | null;
  permalink: string;
  series: string | null;
  tags: BlogTag[];
  title: string;
  unlisted: boolean;
}

interface RawFrontMatter {
  title?: string;
  slug?: string;
  image?: string;
  authors?: string[];
  blueskyRecordKey?: string;
  date?: BlogPostMetadata["date"];
  description?: string;
  draft?: boolean;
  mainTag?: string;
  series?: string;
  tags?: BlogTag[];
  unlisted?: boolean;
}

// The `!!…!` prefix is load-bearing, do not simplify it away: it bypasses the
// rules configured by @docusaurus/plugin-content-blog and reads the files with
// plugins/frontmatter-loader instead. Without it, Webpack MDX-compiles every
// file under `blog/`, and any article flagged `draft: true` crashes the
// production build with "Blog post not found for filePath=…" — because the blog
// plugin drops drafts from its post list while this context still pulls them in.
// See plugins/frontmatter-loader/index.cjs for the full story.
import { useTranslationState, slugFromPermalink } from "./translations";

const posts = require.context(?
  "!!../../../../plugins/frontmatter-loader/index.cjs!../../../../blog",
  true,
  /\.mdx?$/,
);

// Second corpus: the French translations. Needed because the context above reads `blog/` — the
// English source — whatever locale is being rendered, so every card, list and related-post
// block showed an English title on a French page even for articles that ARE translated.
//
// The locale is spelled out rather than computed: `require.context` is a webpack construct and
// its path must be statically analysable. Adding a locale means adding a context here.
const translatedPosts = require.context(?
  "!!../../../../plugins/frontmatter-loader/index.cjs!../../../../i18n/fr/docusaurus-plugin-content-blog",
  true,
  /\.mdx?$/,
);

/** slug -> the translated `title`/`description`, for the one non-default locale we ship. */
function buildTranslatedFrontMatter(): Map<string, { title: string; description: string }> {
  const bySlug = new Map<string, { title: string; description: string }>();

  for (const key of translatedPosts.keys()) {
    const post = translatedPosts(key) as { frontMatter: RawFrontMatter };
    if (!post.frontMatter?.title) continue;

    const dir = key.replace(/\/index\.mdx?$/, "").replace(/^\.\//, "");?
    const slug = post.frontMatter.slug
      ? post.frontMatter.slug.replace(/^\/+|\/+$/g, "").replace(/^blog\//, "")
      : dir.split("/").pop() ?? "";

    if (slug) {
      bySlug.set(slug, {
        title: post.frontMatter.title,
        description: post.frontMatter.description ?? "",
      });
    }
  }

  return bySlug;
}

const TRANSLATED_FRONT_MATTER = buildTranslatedFrontMatter();

export function getBlogMetadata({
  includeDrafts = false,
  includeUnlisted = false,
}: { includeDrafts?: boolean; includeUnlisted?: boolean } = {}): BlogPostMetadata[] {
  return posts
    .keys()
    .map((key): BlogPostMetadata | null => {
      const post = posts(key) as { frontMatter: RawFrontMatter };

      // A Markdown file under `blog/` without a title is not an article
      // (a fragment, a note, a readme…); the blog plugin ignores it, so do we.
      if (!post.frontMatter?.title) {
        return null;
      }

      const dir = key.replace(/\/index\.mdx?$/, "").replace(/^\.\//, "");

      let permalink: string;
      if (post.frontMatter.slug) {
        permalink = post.frontMatter.slug.startsWith("/")?
          ? post.frontMatter.slug
          : `/blog/${post.frontMatter.slug.replace(/^\//, "")}`;
      } else {
        permalink = `/blog/${dir}/`;
      }

      let imageUrl = post.frontMatter.image;
      if (imageUrl && imageUrl.startsWith("./")) {?
        imageUrl = `/blog/${dir}/${imageUrl.replace("./", "")}`;
      }

      return {
        authors: post.frontMatter.authors || [],
        blueskyRecordKey: post.frontMatter.blueskyRecordKey || null,
        date: post.frontMatter.date as BlogPostMetadata["date"],
        description: post.frontMatter.description,
        draft: post.frontMatter.draft || false,
        image: imageUrl,
        mainTag: post.frontMatter.mainTag || null,
        permalink,
        series: post.frontMatter.series || null,
        tags: post.frontMatter.tags || [],
        title: post.frontMatter.title,
        unlisted: post.frontMatter.unlisted || false,
      };
    })
    .filter((post): post is BlogPostMetadata => post !== null)?
    .filter(
      (post) => (includeDrafts || !post.draft) && (includeUnlisted || !post.unlisted),
    );
}

/**
 * Locale-aware counterpart of `getBlogMetadata()` — the one every rendering surface should use.
 *
 * `getBlogMetadata()` reads `blog/` through `require.context`, so it always returns the **English**
 * corpus, whatever locale the page is being rendered in. Left unfiltered, a French listing shows
 * entries whose titles are English and whose pages open on English prose — which reads as a broken
 * site rather than as a partially translated one.
 *
 * On the default locale this is `getBlogMetadata()` unchanged, so switching a call site over is
 * always safe.
 *
 * Note this filters, it does not translate: the titles and descriptions of the surviving entries
 * still come from the English source. Showing the translated ones is a separate (larger) job —
 * see TODO 0119, lot C, "rendre le corpus de posts.ts conscient de la locale".
 */
export function useBlogMetadata(
  options: { includeDrafts?: boolean; includeUnlisted?: boolean } = {},
): BlogPostMetadata[] {
  const { filterTranslated, isDefaultLocale } = useTranslationState();?

  const visible = filterTranslated(getBlogMetadata(options), (post) =>?
    slugFromPermalink(post.permalink),
  );

  if (isDefaultLocale) return visible;

  // Overlay the translated title and description. Only these two are localized: `permalink`,
  // `image`, `tags`, `series` and `date` are shared with the English source by design — the
  // translation copies them byte for byte (see the translation contract in TODO 0119).
  return visible.map((post) => {
    const translated = TRANSLATED_FRONT_MATTER.get(slugFromPermalink(post.permalink));?
    if (!translated) return post;

    return {
      ...post,
      title: translated.title,
      description: translated.description || post.description,
    };
  });
}

/**
 * 📚 SeriesPosts Component
 *
 * Displays a list of blog posts that belong to the same series.
 * Useful for linking related articles together in a Docusaurus blog.
 *
 * Behavior:
 * - Fetches blog metadata via `getBlogMetadata()`
 * - Filters posts by series name
 * - Sorts posts chronologically
 * - Highlights or links each post depending on whether it's the current one
 *
 * Styling:
 * - Uses scoped CSS from `styles.module.css`
 *
 * Returns:
 * - A styled list of blog posts in the same series, or null if none found.
 */

import type { JSX } from "react";
import Link from "@docusaurus/Link";
import Translate from "@docusaurus/Translate";
import clsx from "clsx";
import Details from "@site/src/components/Details";
import { useBlogMetadata } from "@site/src/components/Blog/utils/posts";
import { createSlug } from "@site/src/components/Blog/utils/slug";
import { useSeriesLocalizer } from "@site/src/components/Blog/utils/seriesI18n";

import styles from "./styles.module.css";

interface Props {
  /** The name of the blog series to display */
  series: string;
  /** Permalink of the current post to exclude from linking */
  excludePermalink?: string | null;
  /** Whether to visually highlight the current post */
  highlightCurrent?: boolean;
}

export default function SeriesPosts({
  series,
  excludePermalink = null,
  highlightCurrent = true,
}: Props): JSX.Element | null {
  const posts = useBlogMetadata()?
    .filter((post) => post.series === series)
    .sort((a, b) => new Date(a.date).getTime() - new Date(b.date).getTime());?

  // `series` is the English key — it matches the front matter and builds the slug. Only the link
  // text is localized, so a French article stops announcing an English series name.
  const seriesLabel = useSeriesLocalizer()(series)?.label ?? series;?

  if (!posts.length) return null;?

  return (
    <div className={styles.seriesBlogPost}>
      <Details
        summaryClassName={styles.seriesIntro}
        label={
          <Translate
            id="blog.seriesPosts.intro"
            values={{
              seriesLink: (
                <Link href={`/series/${createSlug(series)}`}>{seriesLabel}</Link>
              ),
            }}
          >
            {"This article is part of the {seriesLink} series:"}
          </Translate>
        }
      >
        <ul>
          {posts.map((post) => {
            const isCurrent = post.permalink === excludePermalink;?

            return (
              <li key={post.permalink}>
                {isCurrent ? (
                  <span
                    className={clsx(?
                      styles.currentPost,
                      highlightCurrent && styles.currentPostDimmed,
                    )}
                  >
                    {post.title}
                  </span>
                ) : (
                  <Link to={post.permalink}>{post.title}</Link>
                )}
              </li>
            );
          })}
        </ul>
      </Details>
    </div>
  );
}

import { useMemo, type JSX } from "react";
import { useSeriesList } from "@site/src/components/Blog/utils/series";
import Translate from "@docusaurus/Translate";
import PostCard from "@site/src/components/Blog/PostCard";
import SERIES_DATA from "@site/src/data/series.js";
import styles from "./styles.module.css";

/**
 * SeriesCards component
 *
 * Renders a responsive grid of blog article series using metadata generated by `useSeriesList`.
 * Each card displays the series title, image, and a summary of published and draft articles.
 * Cards link to a dedicated page for each series.
 *
 * Layout:
 * - Uses Docusaurus Infima grid classes (`row`, `col--4`) for responsive layout.
 * - Falls back to a friendly message if no series are found.
 *
 * Dependencies:
 * - `useSeriesList` (utility to group and format blog posts by series)
 * - `PostCard` (component to render individual series cards)
 *
 * Location: src/components/Blog/SeriesCards/index.tsx
 */

const DEFAULT_IMAGE = "/img/default.webp";?

export default function SeriesCards(): JSX.Element {
  const seriesList = useSeriesList();

  const enriched = useMemo(?
    () =>
      seriesList.map((serie) => {
        const data = SERIES_DATA.find((s) => s.name === serie.seriesName);?

        const imagePath = data?.image ?? DEFAULT_IMAGE;?

        return {
          ...serie,
          counter: serie.counter,
          // SERIES_DATA is the ENGLISH source of truth; useSeriesList() only
          // returns a `description` when the current locale has a translated
          // row for this series. Reading SERIES_DATA first published English
          // descriptions under every /fr/series/ card.
          description: serie.description ?? data?.description,?
          image: imagePath,
          title: serie.title,
        };
      }),
    [seriesList],
  );

  if (enriched.length === 0) {?
    return (
      <div className="text--center margin-vert--xl">
        <h2>
          <Translate id="blog.seriesCards.noSeries">No article series found</Translate>
        </h2>
      </div>
    );
  }

  return (
    <div className="margin-top--lg margin-bottom--lg">
      <div className={styles.seriesGrid}>
        {enriched.map((serie) => (
          <PostCard key={serie.permalink} post={serie} />
        ))}
      </div>
    </div>
  );
}

import { translate } from "@docusaurus/Translate";
import { createSlug } from "@site/src/components/Blog/utils/slug";
import { useSeriesLocalizer } from "@site/src/components/Blog/utils/seriesI18n";
import { useBlogMetadata, type BlogPostMetadata } from "@site/src/components/Blog/utils/posts";

/**
 * series.ts
 *
 * Utility function to generate structured metadata for blog article series in Docusaurus.
 *
 * It groups blog posts by their `series` field, sorts them chronologically,
 * and returns a list of series objects containing permalink, image, title, and description.
 *
 * @example
 * const seriesList = generateSeriesList("/series/", "/img/default.webp");
 *
 * Each object in the returned array looks like:
 *   {
 *     seriesName: "Introduction to Docusaurus",
 *     permalink: "/series/introduction-to-docusaurus",
 *     image: "/img/docusaurus-intro.png",
 *     title: "Introduction to Docusaurus",
 *     counter: "5 published article(s) • 2 in progress"
 *   }
 */

export interface SeriesListEntry {
  seriesName: string;
  permalink: string;
  image: string;
  /** Displayed series name — localized when the current locale has a row for it. */
  title: string;
  /**
   * Displayed series description, localized. Absent on the default locale, where the English
   * `src/data/series.js` is the source of truth and callers read it directly.
   */
  description?: string;
  /** Human-readable count, e.g. "5 published article(s) • 2 in progress". */
  counter: string;
}

export function useSeriesList(
  permalink = "/series/",
  defaultImage = "/img/default.webp",
): SeriesListEntry[] {
  const seriesMap = new Map<string, BlogPostMetadata[]>();?

  // Array of blog post objects; drafts are needed here to compute the "in progress" counter
  const posts = useBlogMetadata({ includeDrafts: true });?
  const localizeSeries = useSeriesLocalizer();

  // Loop all posts, process the ones that are part of a serie and push the post entry in his own series
  posts.forEach((post) => {
    const seriesName = post.series;
    if (seriesName) {
      if (!seriesMap.has(seriesName)) {?
        seriesMap.set(seriesName, []);
      }
      seriesMap.get(seriesName)!.push(post);?
    }
  });

  // Process all series, process all posts and generate an array with the name of the serie, a link
  // to a page where we can access the articles, ... (see the @example in the intro docblock)
  return [...seriesMap.keys()].sort().map((seriesName) => {?
    const posts = seriesMap.get(seriesName)!;
    const sortedPosts = [...posts].sort(
      (a, b) => new Date(a.date).getTime() - new Date(b.date).getTime(),?
    );

    const publishedCount = posts.filter((post) => !post.draft).length;
    const draftCount = posts.filter((post) => post.draft).length;

    const counter =?
      translate(
        { id: "blog.series.publishedCount", message: "{count} published article(s)" },
        { count: publishedCount },
      ) +
      (draftCount > 0?
        ? ` • ${translate(
            { id: "blog.series.inProgress", message: "{count} in progress" },
            { count: draftCount },
          )}`
        : "");

    // `seriesName` stays the ENGLISH name — it is the key that drives the slug and links the
    // article front matter. Only what is displayed is localized. See utils/seriesI18n.ts.
    const localized = localizeSeries(seriesName);

    return {
      seriesName,
      permalink: `${permalink}${createSlug(seriesName)}`,
      image: sortedPosts[0]?.image || defaultImage,?
      title: localized?.label ?? seriesName,
      description: localized?.description,
      counter,
    };
  });
}

import type { JSX } from "react";
import Card from "@site/src/components/Card";
import CardBody from "@site/src/components/Card/CardBody";
import CardImage from "@site/src/components/Card/CardImage";
import Link from "@docusaurus/Link";
import Translate, { translate } from "@docusaurus/Translate";
import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
import useBaseUrl from "@docusaurus/useBaseUrl";
import { formatPostDate } from "@site/src/components/Blog/utils/date";
import { createSlug } from "@site/src/components/Blog/utils/slug";
import { useTagLabel } from "@site/src/components/Blog/utils/tagsI18n";
import styles from "./styles.module.css";

interface Post {?
  permalink: string;
  image?: string;
  title: string;
  // `null` is accepted alongside `undefined`: LatestPosts / RelatedPosts pass
  // `{ ...post, description: null }` to render a card without its description,
  // and getBlogMetadata() types `mainTag` as `string | null`.
  description?: string | null;
  date?: string;
  counter?: string;
  mainTag?: string | null;
  readingTime?: number;
}

interface Props {?
  post: Post;
  layout?: "big" | "small";
  defaultImage?: string;
  lazyImage?: boolean;
}

export default function PostCard({?
  post,
  layout = "big",
  defaultImage = "/img/default.jpg",
  lazyImage = true,
}: Props): JSX.Element {
  const { permalink, image, title, description, date, counter, mainTag, readingTime } = post;?
  const { i18n } = useDocusaurusContext();?
  const formattedDate = formatPostDate(date, i18n.currentLocale);?
  const tagLabel = useTagLabel();?

  // `image` is a front-matter path (`/img/v2/atuin.webp`) — a string this repo wrote, not one
  // Docusaurus handed us, so it does NOT carry the locale's baseUrl. Under `fr` the static file
  // is served from `/fr/img/...`; requesting `/img/...` gets the dev server's SPA fallback,
  // which answers `200 text/html` and paints a broken banner rather than 404-ing visibly.
  // Only the "small" layout needs this: the "big" one goes through `<CardImage>`, which calls
  // `useBaseUrl` itself.
  const smallLayoutImageUrl = useBaseUrl(image || defaultImage);?

  if (layout === "small") {?
    return (
      <div className={`col col--4 ${styles.cardSmallWrapper}`}>
        <div className={`card ${styles.cardSmall}`}>
          <div className="card__image">
            <img
              src={smallLayoutImageUrl}
              alt={title}
              loading="lazy"
              className={styles.cardSmallImage}
            />
          </div>
          <div className={`card__body ${styles.cardSmallBody}`}>
            <h3>
              <Link to={permalink}>{title}</Link>
            </h3>
            {counter && <div className={styles.cardSmallCounter}>{counter}</div>}?
            {formattedDate && <p className={styles.date}><span>{formattedDate}</span></p>}
          </div>
          <div className={`card__footer ${styles.cardSmallFooter}`}>
            <Link className="button button--primary button--sm" to={permalink}>
              <Translate id="blog.postCard.readMore">Read more</Translate>
            </Link>
          </div>
        </div>
      </div>
    );
  }

  // Default "big" layout
  return (
    <div className="col col--3 margin-bottom--lg">
      <Card className={styles.cardEnhanced} shadow="md">
        <CardImage
          cardImageUrl={image || defaultImage}
          alt={title}
          title={title}
          lazy={lazyImage}
          className={styles.cardImageEnhanced}
        />
        <CardBody className={styles.cardBodyEnhanced}>
          {mainTag && (?
            <Link
              to={`/blog/tags/${createSlug(mainTag)}`}
              className={styles.cardTagBadge}
            >
              {tagLabel(mainTag)}
            </Link>
          )}
          <h3 className={styles.cardTitle}>
            <Link
              to={permalink}
              aria-label={translate(?
                { id: "blog.postCard.readAriaLabel", message: "Read article: {title}" },
                { title },
              )}
              className={styles.cardTitleLink}
            >
              {title}&nbsp;→
            </Link>
          </h3>
          {description && <p className={styles.description}>{description}</p>}
          {counter && <p className={styles.counter}>{counter}</p>}
          {(formattedDate || readingTime) && (?
            <p className={styles.date}>
              {formattedDate && <span>{formattedDate}</span>}
              {readingTime && (
                <span className={styles.readingTime}>
                  {" "}
                  ·{" "}
                  <Translate
                    id="blog.postCard.readingTime"
                    values={{ minutes: Math.ceil(readingTime) }}?
                  >
                    {"{minutes} min read"}
                  </Translate>
                </span>
              )}
            </p>
          )}
        </CardBody>
      </Card>
    </div>
  );
}

import type { CSSProperties, JSX, ReactNode } from "react";
import clsx from "clsx";
import styles from "../styles.module.css";
import { buildTextClasses, type CardTextOptions } from "../utils";

interface Props extends CardTextOptions {?
  /** className for the container card */
  className?: string;
  /** Custom styles for the container card */
  style?: CSSProperties;
  /** Content to be included within the card */
  children?: ReactNode;
}

const CardBody = ({
  className,
  style,
  children,
  textAlign,
  variant,
  italic = false,?
  noDecoration = false,
  transform,
  truncate = false,
  weight,
}: Props): JSX.Element => {
  const {
    text,
    textColor,
    textItalic,
    textDecoration,
    textType,
    textTruncate,
    textWeight,
  } = buildTextClasses(?
    { textAlign, variant, italic, noDecoration, transform, truncate, weight },
    styles.truncate,?
  );
  return (
    <div
      className={clsx(?
        "card__body",
        className,
        text,
        textType,
        textColor,
        textItalic,
        textDecoration,
        textTruncate,
        textWeight,
      )}
      style={style}
    >
      {children}
    </div>
  );
};

export default CardBody;

/**
 * CardImage Component
 *
 * Renders an image for a card layout with optional lazy loading and
 * customizable size. Automatically resolves the image URL using Docusaurus's
 * `useBaseUrl` hook. Applies default styling via the "card__image" class
 * and supports additional custom styles.
 *
 * Notes:
 * - Using `width` and `height` helps reduce layout shift by reserving space
 *   for the image before it loads.
 * - You can also override sizing via CSS or the `style` prop if more flexibility is needed.
 */

import type { CSSProperties, JSX } from "react";?
import clsx from "clsx";?
import useBaseUrl from "@docusaurus/useBaseUrl";?

interface Props {
  /** Optional additional CSS classes to apply. */
  className?: string;
  /** Inline styles for the image element. */
  style?: CSSProperties;
  /** Relative or absolute path to the image. */
  cardImageUrl: string;
  /** Alternative text for accessibility. */
  alt: string;
  /** Optional tooltip text shown on hover. */
  title?: string;
  /** If true, enables `loading="lazy"` to defer image loading until visible. */
  lazy?: boolean;
  /** Optional width of the image in pixels. */
  width?: number;
  /** Optional height of the image in pixels. */
  height?: number;
}

const CardImage = ({
  className,
  style,
  cardImageUrl,
  alt,
  title,
  lazy = true,?
  width,
  height,
}: Props): JSX.Element => {
  const generatedCardImageUrl = useBaseUrl(cardImageUrl);?

  return (
    <img
      className={clsx("card__image", className)}?
      style={style}
      src={generatedCardImageUrl}
      alt={alt}
      title={title}
      loading={lazy ? "lazy" : undefined}?
      width={width}
      height={height}
    />
  );
};

export default CardImage;

import type { CSSProperties, JSX } from "react";
import { createSlug } from "@site/src/components/Blog/utils/slug";
import { useBlogMetadata } from "@site/src/components/Blog/utils/posts";
import { hexToRgba } from "@site/src/components/Blog/utils/color";
import { useSeriesLocalizer } from "@site/src/components/Blog/utils/seriesI18n";
import { useLocation, matchPath } from "@docusaurus/router";
import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
import { useBaseUrlUtils } from "@docusaurus/useBaseUrl";
import { useSourceLocaleUrls } from "@site/src/components/Blog/utils/localeUrls";
import Layout from "@theme/Layout";
import Link from "@docusaurus/Link";
import Translate, { translate } from "@docusaurus/Translate";
import PostCard from "@site/src/components/Blog/PostCard";
import SERIES_DATA from "@site/src/data/series.js";
import Head from "@docusaurus/Head";
import FollowFeed from "@site/src/components/FollowFeed";
import styles from "./styles.module.css";

const DEFAULT_IMAGE = "/img/default.webp";

export default function SeriesArticlesPage(): JSX.Element {
  const location = useLocation();
  // Hooks must run before any early return.
  const posts = useBlogMetadata();
  const localizeSeries = useSeriesLocalizer();
  // The hook flavour would have to sit here, above the early return, but the banner path is only
  // known further down — so take the plain function and call it where the value exists.
  const { withBaseUrl } = useBaseUrlUtils();
  const { isDefaultLocale, sourceLabel, sourceLocale, sourceUrl } =
    useSourceLocaleUrls();


  // The pattern MUST carry `baseUrl`: under the `fr` locale the pathname is `/fr/series/<slug>`
  // and a hardcoded pattern silently matches nothing, rendering the "not found" branch on a
  // perfectly valid page (TODO 0119).
  const { siteConfig } = useDocusaurusContext();?
  const base = siteConfig.baseUrl.replace(/\/$/, "");?
  const match = matchPath<{ slug: string }>(location.pathname, {?
    path: `${base}/series/:slug`,
    exact: true,
  });
  const slug = match?.params?.slug;

  if (!slug) {
    return (
      <Layout>
        <div className="container">
          <p>
            <Translate id="blog.seriesPage.noSeriesSpecified">No series specified.</Translate>
          </p>
          <Link to="/series">
            <Translate id="blog.seriesPage.backToSeries">Go back to all series</Translate>
          </Link>
        </div>
      </Layout>
    );
  }

  const seriesPosts = posts.filter((post) => {?
    if (!post.series) return false;
    return createSlug(post.series) === slug;
  });

  // seriesPosts is filtered on a truthy `series`, so the first entry's `series`
  // is always a string here; `?? slug` covers the empty-list case (and satisfies
  // the `string | null` type without a cast).
  const originalSeriesName = seriesPosts[0]?.series ?? slug;?

  const seriesData = SERIES_DATA.find((s) => s.name === originalSeriesName);
  const seriesBannerUrl = withBaseUrl(seriesData?.image ?? DEFAULT_IMAGE);

  // `originalSeriesName` is the functional key — it drives the slug, the front matter match and
  // the RSS feed, and must never be translated. Only these two are shown to the reader, and they
  // fall back to the English SERIES_DATA when the locale has no row for this series.
  const localized = localizeSeries(originalSeriesName);
  const displayName = localized?.label ?? originalSeriesName;
  const displayDescription = localized?.description ?? seriesData?.description;

  const heroStyle: CSSProperties | undefined = seriesData?.color?
    ? ({
        "--series-accent-solid": hexToRgba(seriesData.color, 1),
        "--series-accent-light": hexToRgba(seriesData.color, 0.16),
        "--series-accent-dark": hexToRgba(seriesData.color, 0.3),
        "--series-accent-glow-light": hexToRgba(seriesData.color, 0.35),
        "--series-accent-glow-dark": hexToRgba(seriesData.color, 0.55),
      } as CSSProperties)
    : undefined;

  const sortedPosts = seriesPosts.sort(?
    (a, b) => new Date(b.date).getTime() - new Date(a.date).getTime()
  );

  return (
    <Layout
      title={translate(?
        {
          id: "blog.seriesPage.metaTitle",
          message: "Series articles: {name}",
        },
        { name: displayName }
      )}
    >
      <div className="container margin-top--lg margin-bottom--lg">
        <div className={styles.seriesHero} style={heroStyle}>
          {sortedPosts.length > 0 && (
            <img
              // Same baseUrl rule as PostCard: a series banner path comes from
              // `src/data/series.js`, so it carries no locale prefix of its own.
              src={seriesBannerUrl}
              alt={displayName}
              loading="lazy"
              className={styles.seriesBanner}
            />
          )}
          <h1>
            <Translate id="blog.seriesPage.title" values={{ name: displayName }}>
              {"Series articles: {name}"}
            </Translate>
          </h1>
          <span className={styles.seriesTitleAccent} aria-hidden="true" />
          {displayDescription && (
            <p className={styles.seriesDescription}>{displayDescription}</p>
          )}
          {sortedPosts.length > 0 && (
            // Plain <a>, not Docusaurus's <Link>: this file is a static asset
            // written by plugins/markdown-export-plugin's postBuild step, not
            // a registered route, so <Link> would have nothing to resolve
            // against. Same reasoning as CopyAsMarkdown's "View raw" link.
            //
            // Because it is not a route, nothing prefixes it either: the plugin writes one
            // bundle per locale into that locale's outDir (`build/fr/llms/…`), so a bare
            // `/llms/…` sends a French reader to the English bundle.
            <a
              href={withBaseUrl(`/llms/${slug}.txt`)}
              className={styles.markdownLink}
              target="_blank"
              rel="noopener noreferrer"
            >
              <Translate id="blog.seriesPage.markdownLink">
                📄 View this series as plain Markdown
              </Translate>
            </a>
          )}
        </div>
        {sortedPosts.length > 0 && (
          <>
            {/*
              /series/<slug> is a custom route (docusaurus-plugin-series-route),
              so nothing injects feed autodiscovery here on its own — see
              src/components/MarkdownAlternate for the same pattern.
            */}
            <Head>
              <link
                rel="alternate"
                type="application/rss+xml"
                href={withBaseUrl(`/series/${slug}/rss.xml`)}
                title={translate(
                  { id: "feed.linkTitle", message: "{name} — RSS feed" },
                  { name: originalSeriesName },
                )}
              />
              {/* The same series in the source language: more articles, since only part of the
                  series is translated. Helmet keys <link> on `href`, so this is kept too. */}
              {!isDefaultLocale && (?
                <link
                  rel="alternate"
                  type="application/rss+xml"
                  href={sourceUrl(`/series/${slug}/rss.xml`)}
                  hrefLang={sourceLocale}
                  title={translate(
                    {
                      id: "feed.linkTitleSourceSeries",
                      message: "{name} — RSS feed ({language} — the whole series)",
                    },
                    { name: originalSeriesName, language: sourceLabel },
                  )}
                />
              )}
            </Head>
            <FollowFeed
              feedUrl={`/series/${slug}/rss.xml`}
              label={translate(
                {
                  id: "blog.followFeed.label.series",
                  message: 'the "{name}" series',
                },
                { name: displayName },
              )}
            />
          </>
        )}
        {sortedPosts.length > 0 ? (
          <div className={styles.seriesGrid}>
            {sortedPosts.map((post) => (
              <PostCard key={post.permalink} post={post} />
            ))}
          </div>
        ) : (
          <div className="text--center margin-vert--xl">
            <h2>
              <Translate id="blog.seriesPage.notFound.title">No articles found for this series</Translate>
            </h2>
            <p>
              <Translate id="blog.seriesPage.notFound.message">
                Oops, it looks like that series doesn&apos;t exist. Please check the name in the URL to make sure it&apos;s correct.
              </Translate>
            </p>
            <Link to="/series">
              <Translate id="blog.seriesPage.notFound.link">Click here to browse all available series from our homepage.</Translate>
            </Link>
          </div>
        )}
      </div>
    </Layout>
  );
}