Afficher les articles de blog Docusaurus sous forme de cartes - Guide pas à pas

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;

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?: string;
  style?: CSSProperties;
  children?: ReactNode;
}

const CardFooter = ({
  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__footer",
        className,
        text,
        textType,
        textColor,
        textItalic,
        textDecoration,
        textTruncate,
        textWeight,
      )}
      style={style}
    >
      {children}
    </div>
  );
};

export default CardFooter;

import type { CSSProperties, JSX, ReactNode } from "react";
import clsx from "clsx"; // clsx helps manage conditional className names in a clean and concise manner.
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 CardHeader = ({
  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__header",
        className,
        text,
        textType,
        textColor,
        textItalic,
        textDecoration,
        textTruncate,
        textWeight,
      )}
      style={style}
    >
      {children}
    </div>
  );
};

export default CardHeader;

/**
 * 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 { JSX } from "react";
import { createSlug } from "@site/src/components/Blog/utils/slug";
import { useBlogMetadata } from "@site/src/components/Blog/utils/posts";
import { useLocation, matchPath } from "@docusaurus/router";
import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
import { useBaseUrlUtils } from "@docusaurus/useBaseUrl";
import Layout from "@theme/Layout";
import Link from "@docusaurus/Link";
import Translate, { translate } from "@docusaurus/Translate";
import styles from "./styles.module.css";
import PostCard from "@site/src/components/Blog/PostCard";
import Head from "@docusaurus/Head";
import FollowFeed from "@site/src/components/FollowFeed";
import { useTagLabel } from "@site/src/components/Blog/utils/tagsI18n";
import { useSourceLocaleUrls } from "@site/src/components/Blog/utils/localeUrls";

type Tag = string | { label: string };?

export default function TagArticlesPage(): JSX.Element {
  const location = useLocation();
  // Hooks must run before any early return.
  const posts = useBlogMetadata();
  const tagLabel = useTagLabel();
  const { isDefaultLocale, sourceLabel, sourceLocale, sourceUrl } =?
    useSourceLocaleUrls();
  const { withBaseUrl } = useBaseUrlUtils();

  // The pattern MUST carry `baseUrl`: under the `fr` locale the pathname is `/fr/blog/tags/<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}/blog/tags/:slug`,
    exact: true,
  });
  const rawTag = match?.params?.slug;?

  if (!rawTag) {
    return (
      <Layout>
        <div className="container">
          <p>
            <Translate id="blog.tagPage.noTag">No tag specified.</Translate>
          </p>
          <Link to="/blog/tags">
            <Translate id="blog.tagPage.backToTags">
              Go back to all tags
            </Translate>
          </Link>
        </div>
      </Layout>
    );
  }

  // Local helper, unrelated to `useTagLabel`: it reads the raw value out of a front-matter
  // entry, which may be a bare string or a `{ label }` object. What comes out is the KEY.
  const getTagKey = (t: Tag) => (typeof t === "string" ? t : t.label);?

  // Find original tag name based on slug
  let displayTag = rawTag;
  for (const post of posts) {
    const foundTag = (post.tags || []).find(
      (t) => createSlug(getTagKey(t)) === rawTag?
    );
    if (foundTag) {
      displayTag = getTagKey(foundTag);
      break;
    }
  }

  // `displayTag` is the front-matter KEY; this is what the reader sees. Resolving it here, once,
  // also closes the inconsistency noted below: the <h1> used to print the raw key ("ai") while
  // the feed button right under it printed the real label ("Artificial Intelligence (AI)").
  const displayLabel = tagLabel(displayTag);?

  // Filter and sort posts by slug-matched tag (most recent first)
  const taggedPosts = posts
    .filter((post) =>
      post.tags?.some((t) => createSlug(getTagKey(t)) === rawTag)
    )
    .sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime()); // Descending?

  if (taggedPosts.length === 0) {
    return (
      <Layout
        title={translate(
          { id: "blog.tagPage.metaTitle", message: "Tag: {label}" },
          { label: displayLabel }
        )}
      >
        <div className="container margin-top--lg margin-bottom--lg text--center">
          <h2>
            <Translate
              id="blog.tagPage.notFound"
              values={{ label: displayLabel }}
            >
              {'No articles found with tag "{label}"'}
            </Translate>
          </h2>
          <Link to="/blog/tags">
            <Translate id="blog.tagPage.browseTags">Browse all tags</Translate>
          </Link>
        </div>
      </Layout>
    );
  }

  const feedUrl = `/blog/tags/${rawTag}/rss.xml`;

  return (
    <Layout
      title={translate(
        { id: "blog.tagPage.metaTitle", message: "Tag: {label}" },
        { label: displayLabel }
      )}
    >
      <div className="container margin-top--lg margin-bottom--lg">
        <h1>
          <Translate id="blog.tagPage.title" values={{ label: displayLabel }}>
            {"Articles tagged: {label}"}
          </Translate>
        </h1>
        {/*
          This route is registered by docusaurus-plugin-tag-route, not by the
          blog plugin, so Docusaurus injects no feed autodiscovery of its own
          here — same reasoning as src/components/MarkdownAlternate.
        */}
        <Head>
          {/* `feedUrl` is a hand-built path to a per-locale static file, so it needs the
              prefix; the second <link> points at the source language, which covers the whole
              blog. Helmet de-duplicates <link> on `href`, so both are kept. */}
          <link
            rel="alternate"
            type="application/rss+xml"
            href={withBaseUrl(feedUrl)}
            title={translate(
              { id: "feed.linkTitle", message: "{name} — RSS feed" },
              { name: displayLabel },
            )}
          />
          {!isDefaultLocale && (?
            <link
              rel="alternate"
              type="application/rss+xml"
              href={sourceUrl(feedUrl)}
              hrefLang={sourceLocale}
              title={translate(
                {
                  id: "feed.linkTitleSourceBlog",
                  message: "{name} — RSS feed ({language} — the whole blog)",
                },
                { name: displayLabel, language: sourceLabel },
              )}
            />
          )}
        </Head>
        <FollowFeed feedUrl={feedUrl} label={displayLabel} />
        <div className={styles.postRow}>
          {taggedPosts.map((post) => (
            <PostCard key={post.permalink} post={post} />
          ))}
        </div>
      </div>
    </Layout>
  );
}

/**
 * 🧠 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 './getBlogMetadata';
 * const posts = getBlogMetadata();
 * ```
 *
 * ⚠️ Note:
 * This function is intended for use in static site generation or client-side rendering
 * where Webpack's `require.context` is available.
 */

export interface BlogPostMetadata {
  title: string;
  description?: string;
  image?: string;
  draft: boolean;
  unlisted: boolean;
  permalink: string;
  tags: string[];
  mainTag: string | null;
  authors: string[];
  date?: string;
  series: string | null;
}

const posts = require.context("../../../../blog", true, /\.mdx?$/);?

export function getBlogMetadata(): BlogPostMetadata[] {
  return posts
    .keys()
    .map((key): BlogPostMetadata => {
      const post = posts(key) as { frontMatter: Record<string, unknown> };?

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

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

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

      return {
        title: post.frontMatter.title as string,
        description: post.frontMatter.description as string | undefined,
        image: imageUrl,
        draft: Boolean(post.frontMatter.draft),?
        unlisted: Boolean(post.frontMatter.unlisted),
        permalink,
        tags: (post.frontMatter.tags as string[]) || [],?
        mainTag: (post.frontMatter.mainTag as string) || null,
        authors: (post.frontMatter.authors as string[]) || [],
        date: post.frontMatter.date as string | undefined,
        series: (post.frontMatter.series as string) || null,
      };
    })
    .filter(Boolean);?
}

/**
 * ♣️ PostCard component
 *
 * A reusable Docusaurus component that displays a blog post preview card.
 * It shows the post image (with fallback), title (as a link), and description.
 *
 * Accessibility:
 * - The title is wrapped in a semantic link with an aria-label for screen readers.
 * - The image includes alt and title attributes.
 *
 * Styling:
 * - Uses Infima utility classes for layout and spacing.
 * - Custom styles can be applied via `styles.module.css`.
 *
 * Location: src/components/Blog/PostCard/index.tsx
 */

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 styles from "./styles.module.css";

interface FormattedDateProps {
  date?: string;
  layout: "big" | "small";
}

/** Renders a formatted date string. */
function FormattedDate({ date, layout }: FormattedDateProps): JSX.Element | null {?
  if (!date) {
    return null;
  }
  return (
    <p
      className={layout === "small" ? "" : styles.date}?
      style={layout === "small" ? { color: "#888", fontSize: "0.95em", marginBottom: 8 } : {}}
    >
      <span>
        {new Date(date).toLocaleDateString("en-US", {?
          year: "numeric",
          month: "long",
          day: "numeric",
        })}
      </span>
    </p>
  );
}

interface Post {
  permalink: string;
  image?: string;
  title: string;
  description?: string;
  date?: string;
}

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

export default function PostCard({
  post,
  layout = "big",?
  defaultImage = "/img/default.jpg",?
}: Props): JSX.Element {
  const { permalink, image, title, description, date } = post;

  if (layout === "small") {?
    return (
      <div className="col col--4" style={{ marginBottom: "2rem", display: "flex" }}>?
        <div
          className="card"
          style={{
            width: "100%",
            display: "flex",
            flexDirection: "column",
            height: "100%",
          }}
        >
          <div className="card__image">
            <img
              src={image || defaultImage}?
              alt={title}
              style={{
                width: "100%",
                height: 180,
                objectFit: "cover",
                borderTopLeftRadius: 8,
                borderTopRightRadius: 8,
              }}
            />
          </div>
          <div className="card__body" style={{ flex: 1 }}>?
            <h3>
              <Link to={permalink}>{title}</Link>
            </h3>
            {description && (
              <div
                style={{
                  color: "#6c63ff",
                  fontWeight: "bold",
                  marginBottom: 6,
                }}
              >
                {description}
              </div>
            )}
            <FormattedDate date={date} layout={layout} />
          </div>
          <div className="card__footer" style={{ textAlign: "right" }}>
            <Link className="button button--primary button--sm" to={permalink}>
              Read more
            </Link>
          </div>
        </div>
      </div>
    );
  }

  // Default "big" layout
  return (
    <div className="col col--3 margin-bottom--lg">?
      <Card shadow="md">
        <CardImage cardImageUrl={image || defaultImage} alt={title} title={title} />
        <CardBody className="padding-vert--md text--center" textAlign="center">
          <h3>
            <Link href={permalink} aria-label={`Read article: ${title}`}>?
              {title}&nbsp;→
            </Link>
          </h3>
          {description && <p className={styles.description}>{description}</p>}
          <FormattedDate date={date} layout={layout} />
        </CardBody>
      </Card>
    </div>
  );
}

import { createSlug } from "@site/src/components/Blog/utils/slug";
import { getBlogMetadata } from "@site/src/components/Blog/utils/posts";
import { useLocation } from "@docusaurus/router";
import Layout from "@theme/Layout";
import Link from "@docusaurus/Link";
import PostCard from "@site/src/components/Blog/PostCard";

function getTagFromPathname(pathname: string): string | null {
  const match = pathname.match(/\/blog\/tags\/([^/]+)/);?
  return match ? decodeURIComponent(match[1]) : null;?
}

export default function TagArticlesPage() {
  const location = useLocation();?
  const rawTag = getTagFromPathname(location.pathname);

  if (!rawTag) {
    return (
      <Layout>
        <div className="container">
          <p>No tag specified.</p>
          <Link href="/blog/tags">Go back to all tags</Link>
        </div>
      </Layout>
    );
  }

  const posts = getBlogMetadata();

  // Find original tag name based on slug
  const allTags = Array.from(new Set(posts.flatMap((post) => post.tags || [])));?
  const displayTag = allTags.find((t) => createSlug(String(t)) === rawTag) || rawTag;?

  // highlight-start
  // Filter and sort posts by slug-matched tag (most recent first)
  const taggedPosts = posts
    .filter((post) => post.tags?.some((t) => createSlug(String(t)) === rawTag))?
    .sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime()); // Descending?
  // highlight-end

  if (taggedPosts.length === 0) {
    return (
      <Layout title={`Tag: ${displayTag}`}>
        <div className="container margin-top--lg margin-bottom--lg text--center">
          <h2>No articles found with tag &quot;{displayTag}&quot;</h2>
          <Link href="/blog/tags">Browse all tags</Link>
        </div>
      </Layout>
    );
  }

  return (
    <Layout title={`Tag: ${displayTag}`}>
      <div className="container margin-top--lg margin-bottom--lg">
        <h1>Articles tagged: {displayTag}</h1>
        <div className="row">
          {taggedPosts.map((post) => (
            <PostCard key={post.title} post={post} />
          ))}
        </div>
      </div>
    </Layout>
  );
}