Skip to content

Commit 055501e

Browse files
onmaxonmax
committed
feat: add 'Layout Types' section to documentation and update frontmatter options for layout
1 parent 672a82d commit 055501e

File tree

4 files changed

+261
-14
lines changed

4 files changed

+261
-14
lines changed

‎docs/.vitepress/config.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,7 @@ export default defineNimiqVitepressConfig({
107107
{
108108
items: [
109109
{ text: 'Getting Started', link: '/vitepress-theme', icon: 'i-tabler:arrow-guide ' },
110+
{ text: 'Layout Types', link: '/vitepress-theme/layouts', icon: 'i-tabler:layout-grid ' },
110111
{ text: 'Frontmatter', link: '/vitepress-theme/frontmatter', icon: 'i-tabler:file-description ' },
111112
{ text: 'Hiding Modules', link: '/vitepress-theme/hiding-modules', icon: 'i-tabler:eye-off ' },
112113
{

‎docs/vitepress-theme/frontmatter.md‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -26,20 +26,20 @@ The Nimiq Vitepress theme supports the following frontmatter options:
2626

2727
### Layout Options
2828

29-
| Option | Type | Default | Description |
30-
| ---------------------- | --------------------- | ----------------------------------------------- | --------------------------------------------------------- |
31-
| `layout` | `'home' \| 'docs'` | `'docs'` | Layout type to use for the page |
32-
| `sidebar` | `boolean` | `true` for docs layout | Whether to show the sidebar |
33-
| `breadcrumbs` | `boolean` | `true` for docs layout, `false` for home layout | Whether to show the breadcrumbs navigation |
34-
| `outline` | `boolean` | `true` if headings exist | Whether to show the outline (table of contents) |
35-
| `secondarySidebar` | `boolean` | `true` for docs layout, `false` for home layout | Whether to show the secondary sidebar |
36-
| `widget` | `boolean` | `true` for docs layout, `false` for home layout | Whether to show the widget area in the secondary sidebar |
37-
| `changelog` | `boolean` | `true` for docs layout, `false` for home layout | Whether to show the changelog in the secondary sidebar |
38-
| `sourceCode` | `boolean \| string` | `true` for docs layout, `false` for home layout | Show source code controls. Can be a custom URL or boolean |
39-
| `sourceCodeLabel` | `string` | `'View Source'` | Label for the source code button |
40-
| `sourceCodePathPrefix` | `string \| undefined` | Auto-detected | Path prefix for source code URLs (e.g., `'docs'` or `''`) |
41-
| `copyMarkdown` | `boolean` | Same as `sourceCode` | Show the copy markdown button independently |
42-
| `wide` | `boolean` | `false`, `true` if `secondarySidebar` is set | Remove max-width constraint on prose content |
29+
| Option | Type | Default | Description |
30+
| ---------------------- | -------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------- |
31+
| `layout` | `'home' \| 'docs' \| 'overview'` | `'docs'` | Layout type to use for the page ([see layouts guide](./layouts.md)) |
32+
| `sidebar` | `boolean` | `true` for docs layout | Whether to show the sidebar |
33+
| `breadcrumbs` | `boolean` | `true` for docs layout, `false` for home layout | Whether to show the breadcrumbs navigation |
34+
| `outline` | `boolean` | `true` if headings exist | Whether to show the outline (table of contents) |
35+
| `secondarySidebar` | `boolean` | `true` for docs layout, `false` for home layout | Whether to show the secondary sidebar |
36+
| `widget` | `boolean` | `true` for docs layout, `false` for home layout | Whether to show the widget area in the secondary sidebar |
37+
| `changelog` | `boolean` | `true` for docs layout, `false` for home layout | Whether to show the changelog in the secondary sidebar |
38+
| `sourceCode` | `boolean \| string` | `true` for docs layout, `false` for home layout | Show source code controls. Can be a custom URL or boolean |
39+
| `sourceCodeLabel` | `string` | `'View Source'` | Label for the source code button |
40+
| `sourceCodePathPrefix` | `string \| undefined` | Auto-detected | Path prefix for source code URLs (e.g., `'docs'` or `''`) |
41+
| `copyMarkdown` | `boolean` | Same as `sourceCode` | Show the copy markdown button independently |
42+
| `wide` | `boolean` | `false`, `true` if `secondarySidebar` is set | Remove max-width constraint on prose content |
4343

4444
## Wide Layout
4545

‎docs/vitepress-theme/layouts.md‎

Lines changed: 245 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
# Layout Types
2+
3+
The Nimiq VitePress theme provides three distinct layout types to accommodate different content needs and use cases. Each layout offers a unique combination of navigation elements, content structure, and styling approach.
4+
5+
## Overview
6+
7+
| Layout | Use Case | Sidebar | Secondary Sidebar | Breadcrumbs | Container | Static Content CSS |
8+
| ------------ | ------------------- | ------- | ----------------- | ----------- | ------------- | ------------------ |
9+
| **docs** | Documentation pages | ✅ | ✅ | ✅ | ✅ Padded | ❌ |
10+
| **home** | Landing pages | ❌ | ❌ | ❌ | ❌ | ❌ |
11+
| **overview** | Module entry pages | ✅ | ❌ | ❌ | ❌ Full-width | ✅ |
12+
13+
## Documentation Layout (Default)
14+
15+
The standard layout for documentation pages with full navigation features and optimized reading experience.
16+
17+
### Features
18+
19+
- **Primary sidebar** with navigation menu
20+
- **Secondary sidebar** with table of contents and widgets
21+
- **Breadcrumbs** navigation at the top
22+
- **Page actions** (Copy MD, View Source buttons)
23+
- **Container padding** for optimal reading width
24+
- **Responsive design** with mobile navigation
25+
26+
### Usage
27+
28+
```yaml
29+
---
30+
# Default layout - no layout specified
31+
title: Documentation Page
32+
---
33+
34+
# Your Documentation Content
35+
36+
This will render with the full documentation layout including sidebars, breadcrumbs, and page actions.
37+
```
38+
39+
### Best For
40+
41+
- API documentation
42+
- Guides and tutorials
43+
- Reference materials
44+
- Technical documentation
45+
46+
## Home Layout
47+
48+
A clean, minimal layout designed for landing pages and home screens.
49+
50+
### Features
51+
52+
- **No sidebars** for clean presentation
53+
- **Desktop header** with navigation
54+
- **No breadcrumbs** or page actions
55+
- **Mobile navigation** at the bottom
56+
- **Full creative control** over layout
57+
58+
### Usage
59+
60+
```yaml
61+
---
62+
layout: home
63+
title: Welcome to Our Documentation
64+
---
65+
66+
# Welcome
67+
68+
Landing page content with full design freedom.
69+
```
70+
71+
### Best For
72+
73+
- Project landing pages
74+
- Welcome screens
75+
- Marketing content
76+
- Overview dashboards
77+
78+
## Overview Layout
79+
80+
Perfect for module entry pages that need navigation but maximum content flexibility.
81+
82+
### Features
83+
84+
- **Primary sidebar** for navigation context
85+
- **No secondary sidebar** for clean content area
86+
- **No breadcrumbs** or page actions for minimal UI
87+
- **Full-width content** without container constraints
88+
- **Static content CSS** for enhanced typography and sections
89+
- **Mobile navigation** with outline accordion
90+
91+
### Usage
92+
93+
```yaml
94+
---
95+
layout: overview
96+
title: Module Overview
97+
---
98+
99+
# Module Name
100+
101+
<section bg-neutral-100>
102+
<h2>Getting Started</h2>
103+
<p>This content uses static-content CSS for enhanced typography and section styling.</p>
104+
</section>
105+
106+
<section bg-darkblue>
107+
<h2>Features</h2>
108+
<p>Full-width sections with fluid spacing and typography.</p>
109+
</section>
110+
```
111+
112+
### Best For
113+
114+
- Module landing pages
115+
- Feature overviews
116+
- Product showcases
117+
- Marketing sections within documentation
118+
119+
## Customizing Layouts
120+
121+
### Sidebar Control
122+
123+
All layouts support sidebar customization via frontmatter:
124+
125+
```yaml
126+
---
127+
layout: overview
128+
sidebar: false # Hide the primary sidebar
129+
---
130+
```
131+
132+
```yaml
133+
---
134+
layout: docs
135+
secondarySidebar: false # Hide the secondary sidebar only
136+
---
137+
```
138+
139+
### Wide Content
140+
141+
For documentation that needs more horizontal space:
142+
143+
```yaml
144+
---
145+
layout: docs
146+
wide: true # Expands content width
147+
---
148+
```
149+
150+
## Static Content CSS
151+
152+
The overview layout automatically imports the static-content CSS module which provides:
153+
154+
### Enhanced Typography
155+
156+
- Fluid font sizing that scales with viewport
157+
- Optimized line heights and spacing
158+
- Consistent heading hierarchy
159+
160+
### Section Styling
161+
162+
- Automatic section padding and margins
163+
- Background color transitions
164+
- Responsive spacing system
165+
166+
### Usage Examples
167+
168+
```html
169+
<!-- Fluid sections with automatic spacing -->
170+
<section bg-neutral-100>
171+
<h1>Main Heading</h1>
172+
<p>Automatic typography scaling</p>
173+
</section>
174+
175+
<section bg-darkblue>
176+
<h2>Feature Section</h2>
177+
<p>Enhanced section spacing</p>
178+
</section>
179+
180+
<!-- Wide sections without constraints -->
181+
<section nq-wide bg-neutral-0>
182+
<h2>Full Width Content</h2>
183+
</section>
184+
```
185+
186+
## Responsive Behavior
187+
188+
### Desktop (≥1224px)
189+
190+
- **docs**: Full sidebar layout with secondary sidebar
191+
- **home**: Header navigation with full content
192+
- **overview**: Sidebar + full-width main content
193+
194+
### Mobile/Tablet (<1224px)
195+
196+
- **docs**: Collapsible navigation with bottom mobile nav
197+
- **home**: Mobile nav at bottom
198+
- **overview**: Outline accordion + mobile nav at bottom
199+
200+
## Migration Guide
201+
202+
### From docs to overview
203+
204+
```yaml
205+
# Before
206+
---
207+
layout: docs # or no layout specified
208+
title: Module Guide
209+
---
210+
211+
# After
212+
---
213+
layout: overview
214+
title: Module Guide
215+
---
216+
```
217+
218+
This changes:
219+
220+
- ❌ Removes secondary sidebar and breadcrumbs
221+
- ❌ Removes container padding
222+
- ✅ Adds static-content CSS styling
223+
- ✅ Enables full-width design flexibility
224+
225+
### From home to overview
226+
227+
```yaml
228+
# Before
229+
---
230+
layout: home
231+
title: Module Landing
232+
---
233+
234+
# After
235+
---
236+
layout: overview
237+
title: Module Landing
238+
---
239+
```
240+
241+
This changes:
242+
243+
- ✅ Adds primary sidebar for navigation
244+
- ✅ Adds static-content CSS styling
245+
- ✅ Maintains clean, container-free design

‎packages/nimiq-vitepress-theme/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ A modern, beautiful VitePress theme with Nimiq branding and design patterns.
1717
- 🧭 Smart navigation with breadcrumbs
1818
- 📝 Rich typography and code highlighting
1919
- 🎯 Custom components (NqCard, NqGrid, NqHeadline, etc.)
20+
2021
- **🚨 Beautiful custom 404 error page**
2122

2223
## Components

0 commit comments

Comments
 (0)