sidebar-navigation-model

A modular and extensible JSON Schema for defining hierarchical sidebar navigation structures in content platforms, documentation tools, and UI frameworks.

Ideal for static site generators, developer portals, CMS integrations, or schema-driven UIs.

📘 Overview

This repository contains a versioned specification for sidebar layout models. Built with composability and clarity in mind, the schema supports:

🔹 Flat and nested sidebar items
🔸 Categories and topics with structured children
🧭 Headings and hierarchical depth
🔗 Link items with URI validation
✅ Rich validation through JSON Schema

Whether you’re building a static site generator, documentation renderer, or a dynamic navigation engine—this model is adaptable to your workflow.

📁 Repository Structure

.
├── README.md
├── CHANGELOG.md
├── package.json
├── docs/
│   ├── definitions.md
│   ├── integrations-guide.md
│   └── overview.md
├── schema/
│   ├── v1.0.0/
│   │   ├── sidebar.schema.json
│   │   └── samples/
│   │       └── example.yaml
│   └── latest/
│       ├── sidebar.schema.json
│       └── samples/
│           └── example.yaml
├── scripts/
│   ├── yamlToMarkdown.js
│   └── markdownToYaml.js

latest/ is a pointer to the most recent version of the schema for easy integration. Update it manually on each release, or use a script/symlink strategy.

📘 Features

Recursive sidebar modeling
Component inheritance via $defs and allOf
Regex-validated metadata: id (filename-like), slug, and flexible path
Deeply nested headings and categories
Ready for version tracking and changelog support

🛠️ Conversion Scripts

`yamlToMarkdown.js`

Description:
Converts sidebar YAML files (matching the schema) into readable, structured Markdown navigation lists.
Supports preservation of YAML comments (before each sidebar entry) as Markdown paragraphs, and includes metadata such as the YAML filename and timestamp as Markdown comments.

Features:

Converts all sidebar structure, including nested items, headings, and tags, into Markdown.
Scalar properties (string, number, boolean) are rendered as _property_: value.
Tags arrays are rendered as Markdown sub-lists.
YAML comments before each sidebar entry are rendered as Markdown paragraphs after the heading.
Prepends Markdown comments for the YAML filename and timestamp.

Usage Example:

const fs = require('fs');
const { parseYamlWithSidebarComments, convertDataToMarkdown } = require('./scripts/yamlToMarkdown');

const yamlContent = fs.readFileSync('sidebars.yaml', 'utf8');
const data = parseYamlWithSidebarComments(yamlContent);

convertDataToMarkdown(data, { yamlFilePath: 'sidebars.yaml' }).then(markdown => {
  fs.writeFileSync('sidebars.md', markdown);
});

`markdownToYaml.js`

Description:
Converts Markdown navigation lists (as generated by yamlToMarkdown.js) back into YAML, reconstructing the sidebar structure and restoring comments as YAML comments.

Features:

Parses Markdown headings, paragraphs, and lists to reconstruct the sidebar data structure.
Converts Markdown paragraphs between headings and the first list item into YAML comments.
Scalar properties and tags are faithfully restored.
Prepends YAML comments for the Markdown filename and timestamp.

Usage Example:

const fs = require('fs');
const { convertMarkdownToYaml } = require('./scripts/markdownToYaml');

const markdownContent = fs.readFileSync('sidebars.md', 'utf8');
const yaml = convertMarkdownToYaml(markdownContent, { markdownFilePath: 'sidebars.md' });
fs.writeFileSync('sidebars.generated.yaml', yaml);

🧩 Dependencies

Both scripts require the following libraries (see package.json):

js-yaml
yaml
prettier (with plugins: prettier/plugins/estree, prettier/plugins/yaml, prettier/plugins/markdown)

Install all dependencies with:

npm install

🚀 Usage

Clone the repo:

git clone https://github.com/your-username/sidebar-navigation-model.git

📚 Documentation

Explore:

overview.md: High-level schema purpose and structure
definitions.md: Breakdown of reusable components
integrations-guide.md: How to integrate with static site generators or client apps

📌 Versioning

We follow Semantic Versioning for schema releases. Refer to the CHANGELOG.md for a history of changes.

🤝 Contributing

Contributions are welcome! See our contributing guide to get started.

📬 Questions or Feedback?

Have a question or feedback? Please use one of the following channels:

GitHub Issues: For bug reports and feature requests.
GitHub Discussions: For questions, ideas, and general feedback.

📄 License

Released under the MIT License. Use it freely in commercial and open-source projects.

This site is open source. Improve this page.