From b8e476626f3cbaeda149b6330944a05df17d40b3 Mon Sep 17 00:00:00 2001
From: Jade Ellis <jade@ellis.link>
Date: Wed, 11 Feb 2026 18:25:11 +0000
Subject: [PATCH] docs: Add links to matrix guides

---
 docs/index.mdx    | 10 ++++++++
 package-lock.json | 11 ++------
 theme/index.css   | 65 +++++++++++++++++++++++++++++++++++++++++++++++
 theme/index.tsx   | 17 +++++++++++++
 4 files changed, 94 insertions(+), 9 deletions(-)

diff --git a/docs/index.mdx b/docs/index.mdx
index 72da7ec1..1ede4488 100644
--- a/docs/index.mdx
+++ b/docs/index.mdx
@@ -19,6 +19,16 @@ hero:
     src: /assets/logo.svg
     alt: continuwuity logo
 
+beforeFeatures:
+  - title: Matrix for Discord users
+    details: New to Matrix? Learn how Matrix compares to Discord
+    link: https://joinmatrix.org/guide/matrix-vs-discord/
+    buttonText: Find Out the Difference
+  - title: How Matrix Works
+    details: Learn how Matrix works under the hood, and what that means
+    link: https://matrix.org/docs/matrix-concepts/elements-of-matrix/
+    buttonText: Read the Guide
+
 features:
   - title: 🚀 High Performance
     details: Built with Rust for exceptional speed and efficiency. Designed to run smoothly even on modest hardware.
diff --git a/package-lock.json b/package-lock.json
index 009a013c..ee5e84b6 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -124,7 +124,6 @@
       "integrity": "sha512-m7L3oi4evTDODcY+Qk3cmY/p7GCaauSRe00D0AkXVohNvxFBt7F49uPwBSThS24I9d31zFuAED2jFqBeBlDqWw==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@rspack/core": "2.0.0-alpha.1",
         "@swc/helpers": "^0.5.18",
@@ -377,7 +376,6 @@
       "integrity": "sha512-tU8rUVaPyC8o8k4ezgigRVQuZhBAC41KWdwZZ0BldN6o+QXSEIb722RnxCTpa9FGK2riqcwJgM+OqqcqXsFpmw==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@mdx-js/mdx": "^3.1.1",
         "@mdx-js/react": "^3.1.1",
@@ -564,7 +562,6 @@
       "integrity": "sha512-TXTnIcNJQEKwThMMqBXsZ4VGAza6bvN4pa41Rkqoio6QBKMvo+5lexeTMScGCIxtzgQJzElcvIltani+adC5PQ==",
       "dev": true,
       "license": "Apache-2.0",
-      "peer": true,
       "dependencies": {
         "tslib": "^2.8.0"
       }
@@ -688,7 +685,6 @@
       "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -942,7 +938,8 @@
       "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz",
       "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==",
       "dev": true,
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/debug": {
       "version": "4.4.3",
@@ -2972,7 +2969,6 @@
       "integrity": "sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=0.10.0"
       }
@@ -2983,7 +2979,6 @@
       "integrity": "sha512-AXJdLo8kgMbimY95O2aKQqsz2iWi9jMgKJhRBAxECE4IFxfcazB2LmzloIoibJI3C12IlY20+KFaLv+71bUJeQ==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "scheduler": "^0.27.0"
       },
@@ -3020,7 +3015,6 @@
       "integrity": "sha512-QgT5//D3jfjJb6Gsjxv0Slpj23ip+HtOpnNgnb2S5zU3CB26G/IDPGoy4RJB42wzFE46DRsstbW6tKHoKbhAxw==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=0.10.0"
       }
@@ -3488,7 +3482,6 @@
       "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=12"
       },
diff --git a/theme/index.css b/theme/index.css
index 94501b05..c31bd06c 100644
--- a/theme/index.css
+++ b/theme/index.css
@@ -105,3 +105,68 @@ body:not(.notTopArrived) header.rp-nav {
 .rspress-logo {
     height: 32px;
 }
+
+/* pre-hero */
+.custom-section {
+    padding: 4rem 1.5rem;
+    background: var(--rp-c-bg);
+}
+
+.custom-cards {
+    display: flex;
+    gap: 2rem;
+    max-width: 800px;
+    margin: 0 auto;
+    justify-content: center;
+    flex-wrap: wrap;
+}
+
+.custom-card {
+    padding: 2rem;
+    border: 1px solid var(--rp-c-divider-light);
+    border-radius: 12px;
+    background: var(--rp-c-bg-soft);
+    text-decoration: none;
+    color: var(--rp-c-text-1);
+    transition: all 0.3s ease;
+    display: flex;
+    flex-direction: column;
+    flex: 1;
+    min-width: 280px;
+    max-width: 350px;
+}
+
+.custom-card:hover {
+    border-color: var(--rp-c-brand);
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
+    transform: translateY(-2px);
+}
+
+.custom-card h3 {
+    margin: 0 0 1rem 0;
+    font-size: 1.25rem;
+    font-weight: 600;
+    color: var(--rp-c-text-0);
+}
+
+.custom-card p {
+    margin: 0 0 1.5rem 0;
+    color: var(--rp-c-text-2);
+    line-height: 1.6;
+    flex: 1;
+}
+
+.custom-card-button {
+    display: inline-block;
+    padding: 0.5rem 1.5rem;
+    background: var(--rp-c-brand);
+    color: white;
+    border-radius: 6px;
+    font-weight: 500;
+    text-align: center;
+    transition: background 0.2s ease;
+}
+
+.custom-card:hover .custom-card-button {
+    background: var(--rp-c-brand-light);
+}
diff --git a/theme/index.tsx b/theme/index.tsx
index 148f7bef..2c9250c5 100644
--- a/theme/index.tsx
+++ b/theme/index.tsx
@@ -12,6 +12,23 @@ function HomeLayout(props: HomeLayoutProps) {
 
     return (
         <BasicHomeLayout
+            beforeFeatures={
+                frontmatter.beforeFeatures ? (
+                    <section className="custom-section">
+                        <div className="rp-container">
+                            <div className="custom-cards">
+                                {frontmatter.beforeFeatures.map((item: any, index: number) => (
+                                    <a key={index} href={item.link} className="custom-card" target="_blank" rel="noopener noreferrer">
+                                        <h3>{item.title}</h3>
+                                        <p>{item.details}</p>
+                                        <span className="custom-card-button">{item.buttonText || 'Learn More'} →</span>
+                                    </a>
+                                ))}
+                            </div>
+                        </div>
+                    </section>
+                ) : <></>
+            }
             afterFeatures={
                 (frontmatter.doc) ?
                 <main className="rp-doc-layout__doc-container">