feat: add preamble to blog page

src/css/custom.scss

@@ -149,6 +149,29 @@ html {
   }
 }
 
+//warning msg for older blogs
+.warning {
+  background-color: var(--ifm-color-primary-lightest);
+  border: 1px solid var(--ifm-color-primary-light);
+  color: var(--ifm-color-primary-darkest);
+  padding: 1rem;
+  border-radius: 8px;
+  margin-bottom: 1.5rem;
+  box-shadow: var(--ifm-global-shadow-md);
+  font-size: 0.95rem;
+  line-height: 1.6;
+
+  strong {
+    color: var(--electron-color-secondary-light);
+  }
+
+  @media (prefers-color-scheme: dark) {
+    background-color: var(--ifm-color-primary-darker);
+    border-color: var(--ifm-color-primary-light);
+    color: var(--ifm-color-primary-lightest);
+  }
+}
+
 .footer {
   &--dark {
     --ifm-footer-background-color: --var(--electron-color-dark);

src/theme/BlogPostItem/Container/index.tsx

@@ -0,0 +1,9 @@
+import React, { type ReactNode } from 'react';
+import type { Props } from '@theme/BlogPostItem/Container';
+
+export default function BlogPostItemContainer({
+  children,
+  className,
+}: Props): ReactNode {
+  return <article className={className}>{children}</article>;
+}

src/theme/BlogPostItem/Footer/ReadMoreLink/index.tsx

@@ -0,0 +1,39 @@
+import React, { type ReactNode } from 'react';
+import Translate, { translate } from '@docusaurus/Translate';
+import Link from '@docusaurus/Link';
+import type { Props } from '@theme/BlogPostItem/Footer/ReadMoreLink';
+
+function ReadMoreLabel() {
+  return (
+    <b>
+      <Translate
+        id="theme.blog.post.readMore"
+        description="The label used in blog post item excerpts to link to full blog posts"
+      >
+        Read more
+      </Translate>
+    </b>
+  );
+}
+
+export default function BlogPostItemFooterReadMoreLink(
+  props: Props,
+): ReactNode {
+  const { blogPostTitle, ...linkProps } = props;
+  return (
+    <Link
+      aria-label={translate(
+        {
+          message: 'Read more about {title}',
+          id: 'theme.blog.post.readMoreLabel',
+          description:
+            'The ARIA label for the link to full blog posts from excerpts',
+        },
+        { title: blogPostTitle },
+      )}
+      {...linkProps}
+    >
+      <ReadMoreLabel />
+    </Link>
+  );
+}

src/theme/BlogPostItem/Footer/index.tsx

@@ -0,0 +1,85 @@
+import React, { type ReactNode } from 'react';
+import clsx from 'clsx';
+import { useBlogPost } from '@docusaurus/plugin-content-blog/client';
+import { ThemeClassNames } from '@docusaurus/theme-common';
+import EditMetaRow from '@theme/EditMetaRow';
+import TagsListInline from '@theme/TagsListInline';
+import ReadMoreLink from '@theme/BlogPostItem/Footer/ReadMoreLink';
+
+export default function BlogPostItemFooter(): ReactNode {
+  const { metadata, isBlogPostPage } = useBlogPost();
+  const {
+    tags,
+    title,
+    editUrl,
+    hasTruncateMarker,
+    lastUpdatedBy,
+    lastUpdatedAt,
+  } = metadata;
+
+  // A post is truncated if it's in the "list view" and it has a truncate marker
+  const truncatedPost = !isBlogPostPage && hasTruncateMarker;
+
+  const tagsExists = tags.length > 0;
+
+  const renderFooter = tagsExists || truncatedPost || editUrl;
+
+  if (!renderFooter) {
+    return null;
+  }
+
+  // BlogPost footer - details view
+  if (isBlogPostPage) {
+    const canDisplayEditMetaRow = !!(editUrl || lastUpdatedAt || lastUpdatedBy);
+
+    return (
+      <footer className="docusaurus-mt-lg">
+        {tagsExists && (
+          <div
+            className={clsx(
+              'row',
+              'margin-top--sm',
+              ThemeClassNames.blog.blogFooterEditMetaRow,
+            )}
+          >
+            <div className="col">
+              <TagsListInline tags={tags} />
+            </div>
+          </div>
+        )}
+        {canDisplayEditMetaRow && (
+          <EditMetaRow
+            className={clsx(
+              'margin-top--sm',
+              ThemeClassNames.blog.blogFooterEditMetaRow,
+            )}
+            editUrl={editUrl}
+            lastUpdatedAt={lastUpdatedAt}
+            lastUpdatedBy={lastUpdatedBy}
+          />
+        )}
+      </footer>
+    );
+  }
+  // BlogPost footer - list view
+  else {
+    return (
+      <footer className="row docusaurus-mt-lg">
+        {tagsExists && (
+          <div className={clsx('col', { 'col--9': truncatedPost })}>
+            <TagsListInline tags={tags} />
+          </div>
+        )}
+        {truncatedPost && (
+          <div
+            className={clsx('col text--right', {
+              'col--3': tagsExists,
+            })}
+          >
+            <ReadMoreLink blogPostTitle={title} to={metadata.permalink} />
+          </div>
+        )}
+      </footer>
+    );
+  }
+}

src/theme/BlogPostItem/Header/Authors/index.tsx

@@ -0,0 +1,49 @@
+import React, { type ReactNode } from 'react';
+import clsx from 'clsx';
+import { useBlogPost } from '@docusaurus/plugin-content-blog/client';
+import BlogAuthor from '@theme/Blog/Components/Author';
+import type { Props } from '@theme/BlogPostItem/Header/Authors';
+import styles from './styles.module.css';
+
+// Component responsible for the authors layout
+export default function BlogPostItemHeaderAuthors({
+  className,
+}: Props): ReactNode {
+  const {
+    metadata: { authors },
+    assets,
+  } = useBlogPost();
+  const authorsCount = authors.length;
+  if (authorsCount === 0) {
+    return null;
+  }
+  const imageOnly = authors.every(({ name }) => !name);
+  const singleAuthor = authors.length === 1;
+  return (
+    <div
+      className={clsx(
+        'margin-top--md margin-bottom--sm',
+        imageOnly ? styles.imageOnlyAuthorRow : 'row',
+        className,
+      )}
+    >
+      {authors.map((author, idx) => (
+        <div
+          className={clsx(
+            !imageOnly && (singleAuthor ? 'col col--12' : 'col col--6'),
+            imageOnly ? styles.imageOnlyAuthorCol : styles.authorCol,
+          )}
+          key={idx}
+        >
+          <BlogAuthor
+            author={{
+              ...author,
+              // Handle author images using relative paths
+              imageURL: assets.authorsImageUrls[idx] ?? author.imageURL,
+            }}
+          />
+        </div>
+      ))}
+    </div>
+  );
+}

src/theme/BlogPostItem/Header/Authors/styles.module.css

@@ -0,0 +1,13 @@
+.authorCol {
+  max-width: inherit !important;
+}
+
+.imageOnlyAuthorRow {
+  display: flex;
+  flex-flow: row wrap;
+}
+
+.imageOnlyAuthorCol {
+  margin-left: 0.3rem;
+  margin-right: 0.3rem;
+}

src/theme/BlogPostItem/Header/Info/index.tsx

@@ -0,0 +1,77 @@
+import React, { type ReactNode } from 'react';
+import clsx from 'clsx';
+import { translate } from '@docusaurus/Translate';
+import { usePluralForm } from '@docusaurus/theme-common';
+import { useDateTimeFormat } from '@docusaurus/theme-common/internal';
+import { useBlogPost } from '@docusaurus/plugin-content-blog/client';
+import type { Props } from '@theme/BlogPostItem/Header/Info';
+
+import styles from './styles.module.css';
+
+// Very simple pluralization: probably good enough for now
+function useReadingTimePlural() {
+  const { selectMessage } = usePluralForm();
+  return (readingTimeFloat: number) => {
+    const readingTime = Math.ceil(readingTimeFloat);
+    return selectMessage(
+      readingTime,
+      translate(
+        {
+          id: 'theme.blog.post.readingTime.plurals',
+          description:
+            'Pluralized label for "{readingTime} min read". Use as much plural forms (separated by "|") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)',
+          message: 'One min read|{readingTime} min read',
+        },
+        { readingTime },
+      ),
+    );
+  };
+}
+
+function ReadingTime({ readingTime }: { readingTime: number }) {
+  const readingTimePlural = useReadingTimePlural();
+  return <>{readingTimePlural(readingTime)}</>;
+}
+
+function DateTime({
+  date,
+  formattedDate,
+}: {
+  date: string;
+  formattedDate: string;
+}) {
+  return <time dateTime={date}>{formattedDate}</time>;
+}
+
+function Spacer() {
+  return <>{' · '}</>;
+}
+
+export default function BlogPostItemHeaderInfo({
+  className,
+}: Props): ReactNode {
+  const { metadata } = useBlogPost();
+  const { date, readingTime } = metadata;
+
+  const dateTimeFormat = useDateTimeFormat({
+    day: 'numeric',
+    month: 'long',
+    year: 'numeric',
+    timeZone: 'UTC',
+  });
+
+  const formatDate = (blogDate: string) =>
+    dateTimeFormat.format(new Date(blogDate));
+
+  return (
+    <div className={clsx(styles.container, 'margin-vert--md', className)}>
+      <DateTime date={date} formattedDate={formatDate(date)} />
+      {typeof readingTime !== 'undefined' && (
+        <>
+          <Spacer />
+          <ReadingTime readingTime={readingTime} />
+        </>
+      )}
+    </div>
+  );
+}

src/theme/BlogPostItem/Header/Info/styles.module.css

@@ -0,0 +1,3 @@
+.container {
+  font-size: 0.9rem;
+}

src/theme/BlogPostItem/Header/Title/index.tsx

@@ -0,0 +1,20 @@
+import React, { type ReactNode } from 'react';
+import clsx from 'clsx';
+import Link from '@docusaurus/Link';
+import { useBlogPost } from '@docusaurus/plugin-content-blog/client';
+import type { Props } from '@theme/BlogPostItem/Header/Title';
+
+import styles from './styles.module.css';
+
+export default function BlogPostItemHeaderTitle({
+  className,
+}: Props): ReactNode {
+  const { metadata, isBlogPostPage } = useBlogPost();
+  const { permalink, title } = metadata;
+  const TitleHeading = isBlogPostPage ? 'h1' : 'h2';
+  return (
+    <TitleHeading className={clsx(styles.title, className)}>
+      {isBlogPostPage ? title : <Link to={permalink}>{title}</Link>}
+    </TitleHeading>
+  );
+}

src/theme/BlogPostItem/Header/Title/styles.module.css

@@ -0,0 +1,12 @@
+.title {
+  font-size: 3rem;
+}
+
+/**
+  Blog post title should be smaller on smaller devices
+**/
+@media (max-width: 576px) {
+  .title {
+    font-size: 2rem;
+  }
+}

src/theme/BlogPostItem/Header/index.tsx

@@ -0,0 +1,14 @@
+import React, { type ReactNode } from 'react';
+import BlogPostItemHeaderTitle from '@theme/BlogPostItem/Header/Title';
+import BlogPostItemHeaderInfo from '@theme/BlogPostItem/Header/Info';
+import BlogPostItemHeaderAuthors from '@theme/BlogPostItem/Header/Authors';
+
+export default function BlogPostItemHeader(): ReactNode {
+  return (
+    <header>
+      <BlogPostItemHeaderTitle />
+      <BlogPostItemHeaderInfo />
+      <BlogPostItemHeaderAuthors />
+    </header>
+  );
+}