6.x: Improve documentation navigation and homepage

.github/.markdownlint-cli2.jsonc

@@ -18,6 +18,10 @@
     "no-inline-html": {
       "allowed_elements": [
         "Badge",
+        "HomeWelcome",
+        "HomeCard",
+        "script",
+        "h3",
         "div",
         "span",
         "br",

.vitepress/theme/components/HomeCard.vue

@@ -0,0 +1,17 @@
+<script setup>
+import { computed } from 'vue'
+import { withBase } from 'vitepress'
+
+const props = defineProps({
+  href: { type: String, required: true },
+})
+
+const destination = computed(() => withBase(props.href))
+</script>
+
+<template>
+  <a class="home-card" :href="destination">
+    <div class="home-card-copy"><slot /></div>
+    <span class="home-card-arrow" aria-hidden="true">→</span>
+  </a>
+</template>

.vitepress/theme/components/HomeWelcome.vue

@@ -0,0 +1,22 @@
+<script setup>
+import { withBase } from 'vitepress'
+</script>
+
+<template>
+  <div class="home-welcome">
+    <div class="home-welcome-copy">
+      <slot />
+      <div class="home-actions">
+        <a class="home-button home-button-primary" :href="withBase('/quickstart.html')">
+          Get started <span aria-hidden="true">→</span>
+        </a>
+        <a class="home-button home-button-secondary" :href="withBase('/installation.html')">
+          Installation
+        </a>
+      </div>
+    </div>
+    <div class="home-welcome-art" aria-hidden="true">
+      <img :src="withBase('/logo.svg')" alt="" width="112" height="88" />
+    </div>
+  </div>
+</template>

.vitepress/theme/homepage.css

@@ -0,0 +1,286 @@
+.docs-home {
+  --home-surface: #f6f3ef;
+  --home-border: #cfc3b8;
+  --home-accent-surface: #f9eae3;
+}
+
+.dark .docs-home {
+  --home-surface: #242120;
+  --home-border: #3d3532;
+  --home-accent-surface: #382623;
+}
+
+.docs-home .VPDoc {
+  padding-top: 24px;
+}
+
+.docs-home .VPDoc .content-container {
+  width: 100%;
+  max-width: none;
+}
+
+.docs-home .VPDoc .content {
+  min-width: 0;
+}
+
+.docs-home .vp-doc h1 {
+  max-width: 560px;
+  margin: 12px 0 18px;
+  font-size: clamp(30px, 3vw, 44px);
+  line-height: 1.15;
+  letter-spacing: -0.035em;
+  text-wrap: balance;
+}
+
+.docs-home .home-welcome h1 .header-anchor {
+  display: none;
+}
+
+.docs-home .vp-doc h2 {
+  margin: 40px 0 8px;
+  padding: 0;
+  border: 0;
+  font-size: 23px;
+  letter-spacing: -0.025em;
+}
+
+.docs-home .vp-doc h2 .header-anchor {
+  top: 0;
+}
+
+.docs-home .vp-doc p {
+  color: var(--vp-c-text-2);
+}
+
+.docs-home .home-welcome {
+  display: flex;
+  align-items: center;
+  gap: 24px;
+  padding: 36px;
+  border: 1px solid var(--home-border);
+  border-radius: 16px;
+  background: var(--home-surface);
+}
+
+.docs-home .home-welcome-copy {
+  flex: 1;
+  min-width: 0;
+}
+
+.docs-home .home-welcome-copy > p {
+  max-width: 480px;
+  margin: 0;
+  font-size: 16px;
+  line-height: 1.7;
+}
+
+.docs-home .home-welcome-copy .home-version {
+  display: inline-block;
+  color: var(--vp-c-brand-1);
+  font-size: 13px;
+  font-weight: 600;
+}
+
+.docs-home .home-welcome-art {
+  display: grid;
+  flex: 0 0 160px;
+  place-items: center;
+  height: 160px;
+  border-radius: 50%;
+  background: var(--home-accent-surface);
+}
+
+.docs-home .home-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+  margin-top: 24px;
+}
+
+.docs-home .vp-doc .home-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 12px;
+  min-height: 44px;
+  padding: 10px 20px;
+  border: 1px solid transparent;
+  border-radius: 8px;
+  font-size: 14px;
+  font-weight: 600;
+  line-height: 1.5;
+  text-decoration: none;
+}
+
+.docs-home .vp-doc .home-button-primary {
+  color: #fff;
+  background: var(--vp-c-brand-3);
+}
+
+.docs-home .vp-doc .home-button-primary:hover {
+  background: var(--vp-c-brand-2);
+}
+
+.docs-home .vp-doc .home-button-secondary {
+  color: var(--vp-c-text-1);
+  border-color: var(--home-border);
+  background: var(--vp-c-bg);
+}
+
+.docs-home .home-grid {
+  display: grid;
+  gap: 12px;
+  margin-top: 20px;
+}
+
+.docs-home .home-paths {
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+}
+
+.docs-home .home-guides {
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+}
+
+.docs-home .vp-doc .home-card {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 22px;
+  border: 1px solid var(--home-border);
+  border-radius: 12px;
+  color: var(--vp-c-text-1);
+  text-decoration: none;
+  background: var(--vp-c-bg);
+}
+
+.docs-home .vp-doc .home-paths .home-card {
+  background: var(--home-surface);
+}
+
+.docs-home .vp-doc .home-card:hover,
+.docs-home .vp-doc .home-button-secondary:hover {
+  border-color: var(--vp-c-brand-1);
+  background: var(--home-accent-surface);
+}
+
+.docs-home .vp-doc .home-card h3 {
+  margin: 0 0 8px;
+  font-size: 16px;
+  line-height: 1.45;
+  letter-spacing: -0.015em;
+}
+
+.docs-home .home-card p {
+  margin: 0;
+  font-size: 14px;
+  line-height: 1.65;
+}
+
+.docs-home .home-card-arrow {
+  flex-shrink: 0;
+  color: var(--vp-c-brand-1);
+  line-height: 24px;
+}
+
+.docs-home .home-more {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px 24px;
+  margin: 18px 0 0;
+  font-size: 14px;
+}
+
+.docs-home .home-quickstart {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1.5fr);
+  gap: 24px;
+  margin-top: 40px;
+  padding: 24px;
+  border: 1px solid var(--home-border);
+  border-radius: 12px;
+  background: var(--home-surface);
+}
+
+.docs-home .home-quickstart h2 {
+  margin: 0 0 12px;
+}
+
+.docs-home .home-quickstart p {
+  margin: 12px 0 0;
+  font-size: 14px;
+}
+
+.docs-home .home-quickstart [class*='language-'] {
+  margin: 0;
+}
+
+.docs-home .home-help {
+  margin-top: 40px;
+  padding: 24px;
+  border: 1px solid var(--home-border);
+  border-radius: 12px;
+  background: var(--home-surface);
+}
+
+.docs-home .home-help h2 {
+  margin: 0 0 8px;
+  font-size: 20px;
+}
+
+.docs-home .home-help p {
+  margin: 0;
+  font-size: 14px;
+}
+
+.docs-home .home-help .home-more {
+  margin-top: 12px;
+}
+
+.docs-home .vp-doc a:focus-visible {
+  outline: 3px solid var(--vp-c-brand-1);
+  outline-offset: 4px;
+}
+
+@media (min-width: 960px) {
+  .docs-home .VPDoc .content {
+    padding-right: 0;
+    padding-left: 0;
+  }
+}
+
+@media (max-width: 1100px) {
+  .docs-home .home-quickstart {
+    grid-template-columns: 1fr;
+    gap: 16px;
+  }
+
+  .docs-home .home-welcome-art {
+    flex-basis: 112px;
+    height: 112px;
+  }
+
+  .docs-home .home-welcome-art img {
+    width: 80px;
+    height: auto;
+  }
+}
+
+@media (max-width: 639px) {
+  .docs-home .home-welcome {
+    padding: 24px;
+  }
+
+  .docs-home .home-welcome-art {
+    display: none;
+  }
+
+  .docs-home .home-paths,
+  .docs-home .home-guides {
+    grid-template-columns: 1fr;
+  }
+
+  .docs-home .vp-doc h2 {
+    font-size: 21px;
+  }
+}

.vitepress/theme/index.js

@@ -1 +1,6 @@
-export { default } from '@cakephp/docs-skeleton'
+import CakeTheme from '@cakephp/docs-skeleton'
+import './homepage.css'
+
+export default {
+  extends: CakeTheme,
+}