Skip to content

Commit cb0d60d

Browse files
onmaxonmax
committed
feat: add 'Hiding Modules' section to documentation and introduce 'wide' frontmatter option for improved layout flexibility; enhance sidebar and navigation logic to support hidden items
1 parent 4e797df commit cb0d60d

File tree

20 files changed

+736
-56
lines changed

20 files changed

+736
-56
lines changed

‎docs/.vitepress/config.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,7 @@ export default defineNimiqVitepressConfig({
108108
items: [
109109
{ text: 'Getting Started', link: '/vitepress-theme', icon: 'i-tabler:arrow-guide ' },
110110
{ text: 'Frontmatter', link: '/vitepress-theme/frontmatter', icon: 'i-tabler:file-description ' },
111+
{ text: 'Hiding Modules', link: '/vitepress-theme/hiding-modules', icon: 'i-tabler:eye-off ' },
111112
{
112113
text: 'Available Components',
113114
icon: 'i-nimiq:widget',

‎docs/vitepress-theme/frontmatter.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,40 @@ The Nimiq Vitepress theme supports the following frontmatter options:
3939
| `sourceCodeLabel` | `string` | `'View Source'` | Label for the source code button |
4040
| `sourceCodePathPrefix` | `string \| undefined` | Auto-detected | Path prefix for source code URLs (e.g., `'docs'` or `''`) |
4141
| `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 |
43+
44+
## Wide Layout
45+
46+
The `wide` option controls whether prose content should use the full available width or be constrained to a maximum width for better readability.
47+
48+
**Default behavior:**
49+
50+
- `wide: false` by default - content is constrained to approximately 78 characters per line for optimal reading
51+
- `wide: true` automatically when `secondarySidebar` is explicitly set - provides more space for complex content
52+
53+
**Enable wide layout:**
54+
55+
```yaml
56+
---
57+
wide: true
58+
---
59+
```
60+
61+
**Disable wide layout (even when secondarySidebar is set):**
62+
63+
```yaml
64+
---
65+
secondarySidebar: true
66+
wide: false
67+
---
68+
```
69+
70+
**Use cases for wide layout:**
71+
72+
- API documentation with long code examples
73+
- Tables that need more horizontal space
74+
- Technical content that benefits from wider presentation
75+
- Pages with complex diagrams or wide visual content
4276

4377
### Navigation Options
4478

@@ -93,6 +127,27 @@ changelog: true
93127
---
94128
```
95129

130+
#### Wide Layout for Technical Documentation
131+
132+
```yaml
133+
---
134+
# Automatically uses wide layout since secondarySidebar is set
135+
secondarySidebar: true
136+
outline: true
137+
widget: false
138+
---
139+
```
140+
141+
#### Force Wide Layout Without Secondary Sidebar
142+
143+
```yaml
144+
---
145+
# Explicitly enable wide layout for full-width content
146+
wide: true
147+
secondarySidebar: false
148+
---
149+
```
150+
96151
## Source Code Controls
97152

98153
The theme includes source code controls next to the breadcrumbs, allowing users to view the source of the current page and copy the raw markdown content. These controls are enabled by default for documentation pages.

‎docs/vitepress-theme/hiding-modules.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# Hiding Modules from Navigation
2+
3+
The Nimiq VitePress theme allows you to hide specific modules from the navigation while keeping them accessible for legacy reasons and SEO purposes.
4+
5+
## Basic Usage
6+
7+
To hide a module from both the sidebar and header navigation, add the `hidden: true` property to the module configuration:
8+
9+
```ts
10+
// .vitepress/config.ts
11+
export default defineNimiqVitepressConfig({
12+
themeConfig: {
13+
modules: [
14+
{
15+
text: 'Visible Module',
16+
subpath: 'visible-module',
17+
defaultPageLink: '/visible-module/',
18+
description: 'This module appears in navigation',
19+
sidebar: [
20+
// ... sidebar config
21+
],
22+
},
23+
{
24+
text: 'Hidden Module',
25+
subpath: 'hidden-module',
26+
defaultPageLink: '/hidden-module/',
27+
description: 'This module is hidden from navigation',
28+
hidden: true, // This module won't appear in navigation
29+
sidebar: [
30+
// ... sidebar config
31+
],
32+
},
33+
],
34+
},
35+
})
36+
```
37+
38+
## What Gets Hidden
39+
40+
When a module is marked as `hidden: true`, it will be filtered out from:
41+
42+
- **Sidebar module selector** - The dropdown list in the sidebar
43+
- **Header navigation** - The navigation links in the home layout header
44+
- **Module grid** - The grid of modules displayed on the home page
45+
- **404 page modules** - The module list shown on the 404 page
46+
47+
## Hiding Sidebar Items
48+
49+
You can also hide individual sidebar items (submodules) within a module's sidebar by adding the `hidden: true` property to specific sidebar items:
50+
51+
```ts
52+
// .vitepress/config.ts
53+
export default defineNimiqVitepressConfig({
54+
themeConfig: {
55+
modules: [
56+
{
57+
text: 'API Documentation',
58+
subpath: 'api',
59+
defaultPageLink: '/api/',
60+
sidebar: [
61+
{
62+
label: 'Core API',
63+
items: [
64+
{ text: 'Getting Started', link: '/api/getting-started', icon: 'i-tabler:rocket' },
65+
{ text: 'Authentication', link: '/api/auth', icon: 'i-tabler:lock' },
66+
// This item will be hidden from the sidebar
67+
{ text: 'Legacy Methods', link: '/api/legacy', icon: 'i-tabler:archive', hidden: true },
68+
{
69+
text: 'Advanced Features',
70+
icon: 'i-tabler:settings',
71+
items: [
72+
{ text: 'Webhooks', link: '/api/webhooks' },
73+
// This nested item will be hidden
74+
{ text: 'Deprecated Endpoints', link: '/api/deprecated', hidden: true },
75+
{ text: 'Rate Limiting', link: '/api/rate-limiting' },
76+
],
77+
},
78+
],
79+
},
80+
],
81+
},
82+
],
83+
},
84+
})
85+
```
86+
87+
Hidden sidebar items are also filtered from:
88+
89+
- **Sidebar navigation** - The nested navigation items won't appear
90+
- **Previous/Next navigation** - Hidden items are skipped in page navigation
91+
92+
## What Remains Accessible
93+
94+
Hidden modules remain fully accessible through:
95+
96+
- **Direct links** - Users can still navigate to hidden modules via direct URLs
97+
- **Search functionality** - Hidden modules appear in search results
98+
- **SEO crawling** - Search engines can still index hidden module pages
99+
- **Internal navigation** - Navigation within the hidden module works normally
100+
101+
## Use Cases
102+
103+
### Legacy Support
104+
105+
Hide deprecated modules while keeping them accessible for existing users:
106+
107+
```ts
108+
const legacyModule = {
109+
text: 'Legacy API v1',
110+
subpath: 'legacy-api-v1',
111+
defaultPageLink: '/legacy-api-v1/',
112+
description: 'Deprecated API - use v2 instead',
113+
hidden: true,
114+
sidebar: [
115+
// ... legacy documentation
116+
],
117+
}
118+
```
119+
120+
### Work in Progress
121+
122+
Hide modules that are under development:
123+
124+
```ts
125+
const experimentalModule = {
126+
text: 'Experimental Features',
127+
subpath: 'experimental',
128+
defaultPageLink: '/experimental/',
129+
description: 'Features under development',
130+
hidden: true,
131+
sidebar: [
132+
// ... experimental documentation
133+
],
134+
}
135+
```
136+
137+
### Conditional Visibility
138+
139+
You can conditionally hide modules based on environment or other factors:
140+
141+
```ts
142+
const internalModule = {
143+
text: 'Internal Tools',
144+
subpath: 'internal',
145+
defaultPageLink: '/internal/',
146+
description: 'Internal development tools',
147+
hidden: process.env.NODE_ENV === 'production',
148+
sidebar: [
149+
// ... internal documentation
150+
],
151+
}
152+
```
153+
154+
## Best Practices
155+
156+
1. **Use sparingly** - Only hide modules when there's a specific need
157+
2. **Provide alternatives** - If hiding a module, ensure users can find replacement functionality
158+
3. **Document the change** - Consider adding a note about hidden modules in your changelog
159+
4. **Test accessibility** - Ensure hidden modules remain accessible via search and direct links
160+
5. **Consider redirects** - For deprecated modules, consider adding redirects to newer alternatives
161+
162+
## Technical Implementation
163+
164+
The hiding functionality works by:
165+
166+
1. Adding a `hidden?: boolean` property to the module configuration
167+
2. Filtering modules in navigation components using the `useVisibleModules` composable
168+
3. Keeping the original module list intact for search and direct access
169+
4. Maintaining full functionality for hidden modules when accessed directly
170+
171+
This approach ensures that hiding modules only affects navigation visibility, not the actual accessibility or functionality of the modules themselves.

‎docs/vitepress-theme/test-normal-layout.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
title: Normal Layout Test
3+
description: Testing the default layout behavior (no wide setting)
4+
wide: false
5+
---
6+
7+
# Normal Layout Test
8+
9+
This page demonstrates the default layout behavior without the `wide` setting. The prose content should be constrained to approximately 78 characters per line for optimal readability.
10+
11+
## Normal Content
12+
13+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
14+
15+
## Constrained Tables
16+
17+
In the default layout, tables might overflow or wrap differently:
18+
19+
| Property | Type | Default | Description | Example Usage | Notes |
20+
| ------------------ | --------- | -------------------------------------------- | -------------------------------------------- | ------------------------- | ------------------------------------------ |
21+
| `wide` | `boolean` | `false`, `true` if `secondarySidebar` is set | Remove max-width constraint on prose content | `wide: true` | Useful for technical documentation |
22+
| `secondarySidebar` | `boolean` | `true` for docs layout | Whether to show the secondary sidebar | `secondarySidebar: false` | Automatically enables wide layout when set |
23+
| `outline` | `boolean` | `true` if headings exist | Whether to show the outline | `outline: false` | Controls table of contents |
24+
25+
## Code Examples
26+
27+
Code blocks in normal layout:
28+
29+
```javascript
30+
// This code block has the standard max-width constraint
31+
function processComplexConfiguration(config) {
32+
return {
33+
apiEndpoint: config.apiEndpoint || 'https://api.example.com/v1',
34+
timeout: config.timeout || 5000,
35+
retries: config.retries || 3,
36+
headers: {
37+
'User-Agent': config.userAgent || 'MyApp/1.0.0',
38+
'Accept': 'application/json',
39+
'Content-Type': 'application/json',
40+
...config.customHeaders
41+
},
42+
authentication: {
43+
type: config.auth?.type || 'bearer',
44+
token: config.auth?.token || process.env.API_TOKEN,
45+
refreshUrl: config.auth?.refreshUrl || 'https://api.example.com/v1/auth/refresh'
46+
}
47+
}
48+
}
49+
```
50+
51+
## Comparison
52+
53+
Compare this page with the "Wide Layout Test" page to see the difference in content width. The normal layout provides better readability for text-heavy content, while the wide layout is better for technical documentation with tables and code examples.

‎docs/vitepress-theme/test-secondary-sidebar-layout.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
title: Secondary Sidebar Layout Test
3+
description: Testing automatic wide layout when secondarySidebar is set
4+
secondarySidebar: true
5+
outline: true
6+
widget: false
7+
---
8+
9+
# Secondary Sidebar Layout Test
10+
11+
This page demonstrates the automatic wide layout behavior when `secondarySidebar` is explicitly set (without needing `wide: true`). Since `secondarySidebar: true` is set in the frontmatter, the prose content should automatically use the wide layout.
12+
13+
## How It Works
14+
15+
According to the logic:
16+
17+
1. If `wide` is explicitly set, use that value
18+
2. If `secondarySidebar` is present (true or false), default to wide layout (`true`)
19+
3. Otherwise, default to false
20+
21+
Since this page has `secondarySidebar: true` but no explicit `wide` setting, it should automatically use the wide layout.
22+
23+
## Secondary Sidebar Content
24+
25+
You should see the secondary sidebar on the right with:
26+
27+
- Table of contents (outline)
28+
- No widget area (since `widget: false`)
29+
30+
## Wide Content Example
31+
32+
This content should be wide even though we didn't explicitly set `wide: true`:
33+
34+
| Property | Type | Default | Description | Notes |
35+
| --------------------- | ------------------------------ | ------------------------------------ | ------------------------------------------------- | ----- |
36+
| Automatic wide layout | When `secondarySidebar` is set | Makes sense for technical docs | Pages with sidebars often need more content space |
37+
| Manual override | `wide: false` can disable | Even when `secondarySidebar` is true | Provides full control to authors |
38+
39+
## Code in Wide Layout
40+
41+
```typescript
42+
// This code should have more horizontal space due to automatic wide layout
43+
interface WideLayoutConfiguration {
44+
secondarySidebar: boolean | undefined
45+
wide: boolean | undefined
46+
automaticBehavior: 'wide when secondarySidebar is set' | 'narrow by default'
47+
}
48+
49+
function determineLayout(config: WideLayoutConfiguration): boolean {
50+
// Explicit wide setting takes precedence
51+
if (config.wide !== undefined) {
52+
return config.wide
53+
}
54+
55+
// If secondarySidebar is explicitly set, default to wide
56+
if (config.secondarySidebar !== undefined) {
57+
return true
58+
}
59+
60+
// Default to narrow layout
61+
return false
62+
}
63+
```
64+
65+
## Testing Override
66+
67+
You can test overriding this behavior by setting `wide: false` in a page that also has `secondarySidebar: true` - the explicit `wide: false` should take precedence.

0 commit comments

Comments
 (0)