Skip to content

Commit 0a7739a

Browse files
ioncakephperioncakephper
committed
Add root-level metadata support and create integration guide
- Extend sidebar schema to support commonMeta properties at root level - Add required sidebars property with proper validation - Create comprehensive integration guide with examples for static site generators - Add meta-valid-sample.yaml demonstrating all schema features including root metadata - Update README with corrected file references and improved documentation structure
1 parent e789b91 commit 0a7739a

File tree

4 files changed

+276
-19
lines changed

4 files changed

+276
-19
lines changed

‎README.md‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -24,18 +24,23 @@ Whether you’re building a static site generator, documentation renderer, or a
2424
.
2525
├── README.md
2626
├── CHANGELOG.md
27+
├── CODE_OF_CONDUCT.md
28+
├── CONTRIBUTING.md
29+
├── LICENSE
2730
├── schema/
2831
│ ├── v1.0.0/
2932
│ │ ├── sidebar.schema.json
3033
│ │ └── samples/
31-
│ │ └── example.yaml
34+
│ │ ├── meta-valid-sample.yaml
35+
│ │ └── valid-sample.yaml
3236
│ └── latest/
3337
│ ├── sidebar.schema.json
3438
│ └── samples/
35-
│ └── example.yaml
39+
│ ├── meta-valid-sample.yaml
40+
│ └── valid-sample.yaml
3641
├── docs/
3742
│ ├── definitions.md
38-
│ ├── integrations-guide.md
43+
│ ├── integration-guide.md
3944
│ └── overview.md
4045
```
4146

@@ -69,7 +74,7 @@ Explore:
6974

7075
- [`overview.md`](./docs/overview.md): High-level schema purpose and structure
7176
- [`definitions.md`](./docs/definitions.md): Breakdown of reusable components
72-
- [`integrations-guide.md`](./docs/integrations-guide.md): How to integrate with static site generators or client apps
77+
- [`integration-guide.md`](./docs/integration-guide.md): How to integrate with static site generators or client apps
7378

7479
---
7580

@@ -81,7 +86,7 @@ We follow [Semantic Versioning](https://semver.org/) for schema releases. Refer
8186

8287
## 🤝 Contributing
8388

84-
Contributions are welcome! For details on how to get started, please read our [contributing guide](CONTRIBUTING.md).
89+
Contributions are welcome! See our [contributing guide](CONTRIBUTING.md) to get started.
8590

8691
---
8792

@@ -96,6 +101,6 @@ Have a question or feedback? Please use one of the following channels:
96101

97102
## 📄 License
98103

99-
Released under the [MIT License](LICENSE). Use it freely in commercial and open source projects.
104+
Released under the [MIT License](LICENSE). Use it freely in commercial and open-source projects.
100105

101106
---

‎docs/integration-guide.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# 📚 Sidebar Navigation Model — Integration Guide
2+
3+
This guide explains how to integrate the Sidebar Navigation Model schema into your project, whether you are using a static site generator, documentation tool, CMS, or a custom application. The schema is designed to be flexible and easy to adopt in a variety of environments.
4+
5+
---
6+
7+
## 1. Overview
8+
9+
The Sidebar Navigation Model is a JSON Schema specification for defining hierarchical navigation structures. It enables you to describe sidebars with nested categories, headings, and links in a consistent, machine-validated format.
10+
11+
---
12+
13+
## 2. Getting Started
14+
15+
### a. Clone or Download the Schema
16+
17+
Clone the repository or download the schema files directly:
18+
19+
```bash
20+
git clone https://github.com/your-username/sidebar-navigation-model.git
21+
```
22+
23+
Or download the latest schema from:
24+
25+
```
26+
schema/latest/sidebar.schema.json
27+
```
28+
29+
### b. Add to Your Project
30+
31+
Copy the relevant schema file(s) into your project, or reference them directly from this repository.
32+
33+
---
34+
35+
## 3. Defining Your Sidebar
36+
37+
Create a JSON or YAML file that describes your sidebar structure. Example (YAML):
38+
39+
```yaml
40+
- sidebars:
41+
- label: docsSidebar ## a single sidebar defined in this outline
42+
items:
43+
- label: Getting Started # category with two links
44+
items:
45+
- label: Introduction
46+
href: /docs/intro
47+
- label: Installation
48+
href: /docs/install
49+
- label: Guides # category with a topic
50+
items:
51+
- label: Basic Usage
52+
href: /docs/usage
53+
```
54+
55+
---
56+
57+
## 4. Validating Your Sidebar
58+
59+
Use a JSON Schema validator to ensure your sidebar file conforms to the schema. Popular tools include:
60+
61+
- [AJV (JavaScript)](https://ajv.js.org/)
62+
- [jsonschema (Python)](https://python-jsonschema.readthedocs.io/)
63+
- [YAML Validator](https://www.jsonschemavalidator.net/)
64+
65+
### Example (AJV):
66+
67+
```js
68+
const Ajv = require('ajv');
69+
const schema = require('./schema/latest/sidebar.schema.json');
70+
const sidebar = require('./sidebar.yaml'); // Convert YAML to JSON first
71+
72+
const ajv = new Ajv();
73+
const validate = ajv.compile(schema);
74+
const valid = validate(sidebar);
75+
76+
if (!valid) console.error(validate.errors);
77+
```
78+
79+
---
80+
81+
## 5. Integrating with Static Site Generators
82+
83+
Many static site generators (e.g., Docusaurus, VuePress, MkDocs) support custom sidebar structures. You can:
84+
85+
- Convert your sidebar YAML/JSON to the format expected by your generator.
86+
- Use the schema to validate sidebar files before build/deploy.
87+
- Automate sidebar generation from content metadata.
88+
89+
### Example: Docusaurus
90+
91+
1. Define your sidebar in YAML/JSON using the schema.
92+
2. Write a script to transform it into the Docusaurus sidebar format.
93+
3. Validate before build.
94+
95+
---
96+
97+
## 6. Custom Applications
98+
99+
For custom UIs or CMS integrations:
100+
101+
- Parse the sidebar file at runtime or build time.
102+
- Use the schema to enforce structure and catch errors early.
103+
- Render navigation dynamically based on the parsed structure.
104+
105+
---
106+
107+
## 7. Best Practices
108+
109+
- **Version Pinning:** Reference a specific schema version for stability.
110+
- **Validation:** Always validate sidebar files during CI/CD or before deployment.
111+
- **Extensibility:** Use `$defs` and `allOf` for advanced schema composition.
112+
- **Documentation:** Keep sidebar files close to your content for easier maintenance.
113+
114+
---
115+
116+
## 8. Resources
117+
118+
- [JSON Schema Documentation](https://json-schema.org/)
119+
- [AJV Validator](https://ajv.js.org/)
120+
- [YAML Validator](https://www.jsonschemavalidator.net/)
121+
- [Sidebar Navigation Model GitHub](https://github.com/your-username/sidebar-navigation-model)
122+
123+
---
124+
125+
For further questions, see the [README](../README.md) or open an issue on GitHub.

‎schema/latest/samples/meta-valid-sample.yaml‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
description: Full sample of a sidebar navigation config
2+
summary: Demonstrates all supported structures
3+
brief: Nested and linked documentation config
4+
title: Full Navigation Example
5+
id: sidebar-v1
6+
slug: sidebar-navigation
7+
path: /docs/navigation
8+
9+
sidebars:
10+
- "intro" # visibleString
11+
- label: "Getting Started"
12+
description: Basic onboarding section
13+
summary: For new users
14+
brief: Welcome and install info
15+
title: Getting Started
16+
id: start-here
17+
slug: getting-started
18+
path: /docs/start
19+
items: [] # emptySidebar
20+
21+
- label: "Advanced Guides"
22+
description: Deep dive tutorials
23+
summary: Configuration and usage scenarios
24+
brief: For power users
25+
title: Advanced Guides
26+
id: advanced-section
27+
slug: advanced-guides
28+
path: /docs/advanced
29+
items:
30+
- label: "Configuration"
31+
description: Setup options
32+
summary: Customize settings
33+
brief: UI and backend tweaks
34+
title: Config
35+
id: cfg-options
36+
slug: config
37+
path: /docs/advanced/config
38+
items: [] # leafHeading
39+
40+
- label: "Features"
41+
description: All feature sets
42+
summary: Component overview
43+
brief: Widget and module functionality
44+
title: Feature List
45+
id: feat-list
46+
slug: features
47+
path: /docs/advanced/features
48+
items:
49+
- "feature-auth"
50+
- "feature-theme"
51+
52+
- label: "API Reference"
53+
description: REST & GraphQL APIs
54+
summary: All available endpoints
55+
brief: Integrate with services
56+
title: API Docs
57+
id: api-ref
58+
slug: api
59+
path: /docs/advanced/api
60+
items:
61+
- label: "Authentication"
62+
description: Login and token flow
63+
summary: Secure access
64+
brief: OAuth, API keys
65+
title: Auth
66+
id: api-auth
67+
slug: authentication
68+
path: /docs/advanced/api/auth
69+
items: [] # leafHeading
70+
71+
- label: "Endpoints"
72+
description: CRUD operations
73+
summary: RESTful routes
74+
brief: Create, Read, Update, Delete
75+
title: Endpoints
76+
id: api-endpoints
77+
slug: endpoints
78+
path: /docs/advanced/api/endpoints
79+
items:
80+
- "getUser"
81+
- "createPost"
82+
83+
- label: "Resources"
84+
description: External and internal links
85+
summary: Useful materials
86+
brief: Docs and guides
87+
title: Resources
88+
id: res-section
89+
slug: resources
90+
path: /docs/advanced/resources
91+
items:
92+
- label: "Official Site"
93+
description: Homepage
94+
summary: Visit the platform
95+
brief: External link
96+
title: Main Site
97+
id: site-link
98+
slug: official-site
99+
path: /external
100+
href: https://example.com
101+
102+
- label: "SDK Docs"
103+
description: Developer guide
104+
summary: SDK usage
105+
brief: Setup and methods
106+
title: SDK Reference
107+
id: sdk-docs
108+
slug: sdk
109+
path: /external/sdk
110+
href: https://example.com/sdk
111+
112+
- label: "Community Forum"
113+
description: Ask questions
114+
summary: Chat with others
115+
brief: Get support
116+
title: Forum
117+
id: forum-link
118+
slug: community
119+
path: /external/forum
120+
href: https://community.example.com

‎schema/latest/sidebar.schema.json‎

Lines changed: 20 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -4,20 +4,27 @@
44
"version": "v1.0.0",
55
"description": "Schema defining nested navigational structures with reusable sidebar components and metadata.",
66
"type": "object",
7-
"properties": {
8-
"sidebars": {
9-
"type": "array",
10-
"minItems": 0,
11-
"items": {
12-
"anyOf": [
13-
{ "$ref": "#/$defs/visibleString" },
14-
{ "$ref": "#/$defs/emptySidebar" },
15-
{ "$ref": "#/$defs/populatedSidebar" }
16-
]
17-
}
7+
"allOf": [
8+
{ "$ref": "#/$defs/commonMeta" },
9+
{
10+
"type": "object",
11+
"properties": {
12+
"sidebars": {
13+
"type": "array",
14+
"minItems": 0,
15+
"items": {
16+
"anyOf": [
17+
{ "$ref": "#/$defs/visibleString" },
18+
{ "$ref": "#/$defs/emptySidebar" },
19+
{ "$ref": "#/$defs/populatedSidebar" }
20+
]
21+
}
22+
}
23+
},
24+
"required": ["sidebars"],
25+
"additionalProperties": false
1826
}
19-
},
20-
"additionalProperties": false,
27+
],
2128
"$defs": {
2229
"visibleString": {
2330
"type": "string",

0 commit comments

Comments
 (0)