Skip to content

Commit 8436696

Browse files
markstorymarkstory
authored
Merge pull request #8346 from cakephp/improve-docs-navigation-homepage
6.x: Improve documentation navigation and homepage
2 parents a3bfd62 + 0e3b768 commit 8436696

9 files changed

Lines changed: 1262 additions & 1029 deletions

File tree

‎.github/.markdownlint-cli2.jsonc‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,10 @@
1818
"no-inline-html": {
1919
"allowed_elements": [
2020
"Badge",
21+
"HomeWelcome",
22+
"HomeCard",
23+
"script",
24+
"h3",
2125
"div",
2226
"span",
2327
"br",

‎.vitepress/theme/components/HomeCard.vue‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
<script setup>
2+
import { computed } from 'vue'
3+
import { withBase } from 'vitepress'
4+
5+
const props = defineProps({
6+
href: { type: String, required: true },
7+
})
8+
9+
const destination = computed(() => withBase(props.href))
10+
</script>
11+
12+
<template>
13+
<a class="home-card" :href="destination">
14+
<div class="home-card-copy"><slot /></div>
15+
<span class="home-card-arrow" aria-hidden="true">→</span>
16+
</a>
17+
</template>

‎.vitepress/theme/components/HomeWelcome.vue‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
<script setup>
2+
import { withBase } from 'vitepress'
3+
</script>
4+
5+
<template>
6+
<div class="home-welcome">
7+
<div class="home-welcome-copy">
8+
<slot />
9+
<div class="home-actions">
10+
<a class="home-button home-button-primary" :href="withBase('/quickstart.html')">
11+
Get started <span aria-hidden="true">→</span>
12+
</a>
13+
<a class="home-button home-button-secondary" :href="withBase('/installation.html')">
14+
Installation
15+
</a>
16+
</div>
17+
</div>
18+
<div class="home-welcome-art" aria-hidden="true">
19+
<img :src="withBase('/logo.svg')" alt="" width="112" height="88" />
20+
</div>
21+
</div>
22+
</template>

‎.vitepress/theme/homepage.css‎

Lines changed: 286 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,286 @@
1+
.docs-home {
2+
--home-surface: #f6f3ef;
3+
--home-border: #cfc3b8;
4+
--home-accent-surface: #f9eae3;
5+
}
6+
7+
.dark .docs-home {
8+
--home-surface: #242120;
9+
--home-border: #3d3532;
10+
--home-accent-surface: #382623;
11+
}
12+
13+
.docs-home .VPDoc {
14+
padding-top: 24px;
15+
}
16+
17+
.docs-home .VPDoc .content-container {
18+
width: 100%;
19+
max-width: none;
20+
}
21+
22+
.docs-home .VPDoc .content {
23+
min-width: 0;
24+
}
25+
26+
.docs-home .vp-doc h1 {
27+
max-width: 560px;
28+
margin: 12px 0 18px;
29+
font-size: clamp(30px, 3vw, 44px);
30+
line-height: 1.15;
31+
letter-spacing: -0.035em;
32+
text-wrap: balance;
33+
}
34+
35+
.docs-home .home-welcome h1 .header-anchor {
36+
display: none;
37+
}
38+
39+
.docs-home .vp-doc h2 {
40+
margin: 40px 0 8px;
41+
padding: 0;
42+
border: 0;
43+
font-size: 23px;
44+
letter-spacing: -0.025em;
45+
}
46+
47+
.docs-home .vp-doc h2 .header-anchor {
48+
top: 0;
49+
}
50+
51+
.docs-home .vp-doc p {
52+
color: var(--vp-c-text-2);
53+
}
54+
55+
.docs-home .home-welcome {
56+
display: flex;
57+
align-items: center;
58+
gap: 24px;
59+
padding: 36px;
60+
border: 1px solid var(--home-border);
61+
border-radius: 16px;
62+
background: var(--home-surface);
63+
}
64+
65+
.docs-home .home-welcome-copy {
66+
flex: 1;
67+
min-width: 0;
68+
}
69+
70+
.docs-home .home-welcome-copy > p {
71+
max-width: 480px;
72+
margin: 0;
73+
font-size: 16px;
74+
line-height: 1.7;
75+
}
76+
77+
.docs-home .home-welcome-copy .home-version {
78+
display: inline-block;
79+
color: var(--vp-c-brand-1);
80+
font-size: 13px;
81+
font-weight: 600;
82+
}
83+
84+
.docs-home .home-welcome-art {
85+
display: grid;
86+
flex: 0 0 160px;
87+
place-items: center;
88+
height: 160px;
89+
border-radius: 50%;
90+
background: var(--home-accent-surface);
91+
}
92+
93+
.docs-home .home-actions {
94+
display: flex;
95+
flex-wrap: wrap;
96+
gap: 12px;
97+
margin-top: 24px;
98+
}
99+
100+
.docs-home .vp-doc .home-button {
101+
display: inline-flex;
102+
align-items: center;
103+
justify-content: center;
104+
gap: 12px;
105+
min-height: 44px;
106+
padding: 10px 20px;
107+
border: 1px solid transparent;
108+
border-radius: 8px;
109+
font-size: 14px;
110+
font-weight: 600;
111+
line-height: 1.5;
112+
text-decoration: none;
113+
}
114+
115+
.docs-home .vp-doc .home-button-primary {
116+
color: #fff;
117+
background: var(--vp-c-brand-3);
118+
}
119+
120+
.docs-home .vp-doc .home-button-primary:hover {
121+
background: var(--vp-c-brand-2);
122+
}
123+
124+
.docs-home .vp-doc .home-button-secondary {
125+
color: var(--vp-c-text-1);
126+
border-color: var(--home-border);
127+
background: var(--vp-c-bg);
128+
}
129+
130+
.docs-home .home-grid {
131+
display: grid;
132+
gap: 12px;
133+
margin-top: 20px;
134+
}
135+
136+
.docs-home .home-paths {
137+
grid-template-columns: repeat(3, minmax(0, 1fr));
138+
}
139+
140+
.docs-home .home-guides {
141+
grid-template-columns: repeat(2, minmax(0, 1fr));
142+
}
143+
144+
.docs-home .vp-doc .home-card {
145+
display: flex;
146+
align-items: flex-start;
147+
justify-content: space-between;
148+
gap: 12px;
149+
padding: 22px;
150+
border: 1px solid var(--home-border);
151+
border-radius: 12px;
152+
color: var(--vp-c-text-1);
153+
text-decoration: none;
154+
background: var(--vp-c-bg);
155+
}
156+
157+
.docs-home .vp-doc .home-paths .home-card {
158+
background: var(--home-surface);
159+
}
160+
161+
.docs-home .vp-doc .home-card:hover,
162+
.docs-home .vp-doc .home-button-secondary:hover {
163+
border-color: var(--vp-c-brand-1);
164+
background: var(--home-accent-surface);
165+
}
166+
167+
.docs-home .vp-doc .home-card h3 {
168+
margin: 0 0 8px;
169+
font-size: 16px;
170+
line-height: 1.45;
171+
letter-spacing: -0.015em;
172+
}
173+
174+
.docs-home .home-card p {
175+
margin: 0;
176+
font-size: 14px;
177+
line-height: 1.65;
178+
}
179+
180+
.docs-home .home-card-arrow {
181+
flex-shrink: 0;
182+
color: var(--vp-c-brand-1);
183+
line-height: 24px;
184+
}
185+
186+
.docs-home .home-more {
187+
display: flex;
188+
flex-wrap: wrap;
189+
gap: 8px 24px;
190+
margin: 18px 0 0;
191+
font-size: 14px;
192+
}
193+
194+
.docs-home .home-quickstart {
195+
display: grid;
196+
grid-template-columns: minmax(0, 1fr) minmax(0, 1.5fr);
197+
gap: 24px;
198+
margin-top: 40px;
199+
padding: 24px;
200+
border: 1px solid var(--home-border);
201+
border-radius: 12px;
202+
background: var(--home-surface);
203+
}
204+
205+
.docs-home .home-quickstart h2 {
206+
margin: 0 0 12px;
207+
}
208+
209+
.docs-home .home-quickstart p {
210+
margin: 12px 0 0;
211+
font-size: 14px;
212+
}
213+
214+
.docs-home .home-quickstart [class*='language-'] {
215+
margin: 0;
216+
}
217+
218+
.docs-home .home-help {
219+
margin-top: 40px;
220+
padding: 24px;
221+
border: 1px solid var(--home-border);
222+
border-radius: 12px;
223+
background: var(--home-surface);
224+
}
225+
226+
.docs-home .home-help h2 {
227+
margin: 0 0 8px;
228+
font-size: 20px;
229+
}
230+
231+
.docs-home .home-help p {
232+
margin: 0;
233+
font-size: 14px;
234+
}
235+
236+
.docs-home .home-help .home-more {
237+
margin-top: 12px;
238+
}
239+
240+
.docs-home .vp-doc a:focus-visible {
241+
outline: 3px solid var(--vp-c-brand-1);
242+
outline-offset: 4px;
243+
}
244+
245+
@media (min-width: 960px) {
246+
.docs-home .VPDoc .content {
247+
padding-right: 0;
248+
padding-left: 0;
249+
}
250+
}
251+
252+
@media (max-width: 1100px) {
253+
.docs-home .home-quickstart {
254+
grid-template-columns: 1fr;
255+
gap: 16px;
256+
}
257+
258+
.docs-home .home-welcome-art {
259+
flex-basis: 112px;
260+
height: 112px;
261+
}
262+
263+
.docs-home .home-welcome-art img {
264+
width: 80px;
265+
height: auto;
266+
}
267+
}
268+
269+
@media (max-width: 639px) {
270+
.docs-home .home-welcome {
271+
padding: 24px;
272+
}
273+
274+
.docs-home .home-welcome-art {
275+
display: none;
276+
}
277+
278+
.docs-home .home-paths,
279+
.docs-home .home-guides {
280+
grid-template-columns: 1fr;
281+
}
282+
283+
.docs-home .vp-doc h2 {
284+
font-size: 21px;
285+
}
286+
}

‎.vitepress/theme/index.js‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,6 @@
1-
export { default } from '@cakephp/docs-skeleton'
1+
import CakeTheme from '@cakephp/docs-skeleton'
2+
import './homepage.css'
3+
4+
export default {
5+
extends: CakeTheme,
6+
}

0 commit comments

Comments
 (0)