website/docs: Update Docusaurus config. Prep for version picker. (#14401)

* website/docs: Clean up config. Add types.

* website/docs: Format MDX.

* website: Fix build warnings. Lint badges frontmatter.

website/src/components/SupportBadge.tsx

@@ -1,4 +1,4 @@
-import { SupportLevelToLabel, isSupportLevel } from "@site/remark/support-directive";
+import { SupportLevelToLabel, isSupportLevel } from "@site/remark/support-directive.mjs";
 import React from "react";
 
 export interface SupportBadgeProps {

website/src/theme/DocItem/Content/index.tsx

@@ -1,3 +1,4 @@
+/// <reference types="@docusaurus/plugin-content-docs" />
 /**
  * @file Swizzled DocItemContent component.
  *
@@ -7,8 +8,7 @@
  * the content of a documentation page. However, it also adds support for
  * support badges, and Authentik version badges.
  */
-import { DocFrontMatter } from "@docusaurus/plugin-content-docs";
-import { DocContextValue, useDoc } from "@docusaurus/plugin-content-docs/client";
+import { useDoc } from "@docusaurus/plugin-content-docs/client";
 import { ThemeClassNames } from "@docusaurus/theme-common";
 import { SupportBadge } from "@site/src/components/SupportBadge";
 import { VersionBadge } from "@site/src/components/VersionBadge";
@@ -17,24 +17,25 @@ import type { Props } from "@theme/DocItem/Content";
 import Heading from "@theme/Heading";
 import MDXContent from "@theme/MDXContent";
 import clsx from "clsx";
-import React from "react";
+import React, { useEffect } from "react";
 
-interface SwizzledDocFrontMatter extends DocFrontMatter {
-    support_level?: string;
-    authentik_version?: string;
-    authentik_preview: boolean;
-    authentik_enterprise: boolean;
-}
-
-interface SwizzledDocContextValue extends DocContextValue {
-    frontMatter: SwizzledDocFrontMatter;
+class MarkdownLintError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = "MarkdownLintError";
+    }
 }
 
 const DocItemContent: React.FC<Props> = ({ children }) => {
     const syntheticTitle = useSyntheticTitle();
-    const { frontMatter } = useDoc() as SwizzledDocContextValue;
-    const { support_level, authentik_version, authentik_enterprise, authentik_preview } =
-        frontMatter;
+    const { frontMatter, metadata, contentTitle } = useDoc();
+    const {
+        // ---
+        support_level,
+        authentik_version,
+        authentik_enterprise,
+        authentik_preview,
+    } = frontMatter;
 
     const badges: JSX.Element[] = [];
 
@@ -54,6 +55,35 @@ const DocItemContent: React.FC<Props> = ({ children }) => {
         badges.push(<span className="badge badge--primary">Enterprise</span>);
     }
 
+    if (badges.length && !syntheticTitle) {
+        throw new MarkdownLintError(
+            `${metadata.id}: ${badges.length} Badge(s) found with a missing synthetic title. Remove the page heading and set it via the frontmatter.`,
+        );
+    }
+
+    if (frontMatter.title && contentTitle && frontMatter.title === contentTitle) {
+        throw new MarkdownLintError(
+            `${metadata.id}: Synthetic title "${frontMatter.title}" and content title "${contentTitle}" are the same. Remove the first heading and let the frontmatter set the title.`,
+        );
+    }
+
+    useEffect(() => {
+        const invalidBadges = document.querySelectorAll(`.theme-doc-markdown > header + .badge,
+            .theme-doc-markdown .markdown > .badge
+            `);
+
+        if (!invalidBadges.length) return;
+
+        console.error(
+            `Found ${invalidBadges.length} invalid badges on ${metadata.id}`,
+            invalidBadges,
+        );
+
+        throw new MarkdownLintError(
+            `${metadata.id}: ${invalidBadges.length} Badge(s) defined in markdown content instead of the frontmatter.`,
+        );
+    }, []);
+
     return (
         <div className={clsx(ThemeClassNames.docs.docMarkdown, "markdown")}>
             {syntheticTitle ? (

website/src/theme/EditMetaRow/index.tsx

@@ -1,11 +1,10 @@
 import Translate from "@docusaurus/Translate";
 import Admonition from "@theme/Admonition";
-import IconNote from "@theme/Admonition/Icon/Note";
 import type { Props } from "@theme/EditMetaRow";
 import EditThisPage from "@theme/EditThisPage";
 import LastUpdated from "@theme/LastUpdated";
 import clsx from "clsx";
-import React, { type ReactNode } from "react";
+import React from "react";
 
 import styles from "./styles.module.css";
 
@@ -49,11 +48,11 @@ const EditMetaRow: React.FC<Props> = ({
                 <div className="row">
                     <div className="col col--12">
                         <ul>
-                            {editUrl && (
+                            {editUrl ? (
                                 <li>
                                     <EditThisPage editUrl={editUrl} />
                                 </li>
-                            )}
+                            ) : null}
 
                             <li>
                                 <a
@@ -106,9 +105,9 @@ const EditMetaRow: React.FC<Props> = ({
 
             <div className="row">
                 <div className={clsx("col", styles.lastUpdated)}>
-                    {(lastUpdatedAt || lastUpdatedBy) && (
+                    {lastUpdatedAt || lastUpdatedBy ? (
                         <LastUpdated lastUpdatedAt={lastUpdatedAt} lastUpdatedBy={lastUpdatedBy} />
-                    )}
+                    ) : null}
                 </div>
             </div>
         </>