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.
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.
.
├── 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.
- Recursive sidebar modeling
- Component inheritance via
$defs
andallOf
- Regex-validated metadata:
id
(filename-like),slug
, and flexiblepath
- Deeply nested headings and categories
- Ready for version tracking and changelog support
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);
});
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);
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
Clone the repo:
git clone https://github.com/your-username/sidebar-navigation-model.git
Explore:
overview.md
: High-level schema purpose and structuredefinitions.md
: Breakdown of reusable componentsintegrations-guide.md
: How to integrate with static site generators or client apps
We follow Semantic Versioning for schema releases. Refer to the CHANGELOG.md for a history of changes.
Contributions are welcome! See our contributing guide to get started.
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.
Released under the MIT License. Use it freely in commercial and open-source projects.