https://github.com/ioncakephper/sidebar-navigation-model
A modular and extensible JSON Schema for defining hierarchical sidebar navigation structures in content platforms, documentation tools, and UI frameworks.
https://github.com/ioncakephper/sidebar-navigation-model
configuration data-model documentation-tool front-end json json-sch metadata navigation nested-navigation reusable sidebar web-development
Last synced: 5 months ago
JSON representation
A modular and extensible JSON Schema for defining hierarchical sidebar navigation structures in content platforms, documentation tools, and UI frameworks.
- Host: GitHub
- URL: https://github.com/ioncakephper/sidebar-navigation-model
- Owner: ioncakephper
- License: mit
- Created: 2025-07-15T17:45:36.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-07-17T08:54:42.000Z (7 months ago)
- Last Synced: 2025-07-17T11:54:20.425Z (7 months ago)
- Topics: configuration, data-model, documentation-tool, front-end, json, json-sch, metadata, navigation, nested-navigation, reusable, sidebar, web-development
- Homepage: https://ioncakephper.github.io/sidebar-navigation-model/
- Size: 22.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# 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:**
```js
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:**
```js
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`](https://www.npmjs.com/package/js-yaml)
- [`yaml`](https://www.npmjs.com/package/yaml)
- [`prettier`](https://www.npmjs.com/package/prettier) (with plugins: `prettier/plugins/estree`, `prettier/plugins/yaml`, `prettier/plugins/markdown`)
Install all dependencies with:
```bash
npm install
```
---
## 🚀 Usage
Clone the repo:
```bash
git clone https://github.com/your-username/sidebar-navigation-model.git
```
---
## 📚 Documentation
Explore:
- [`overview.md`](./docs/overview.md): High-level schema purpose and structure
- [`definitions.md`](./docs/definitions.md): Breakdown of reusable components
- [`integrations-guide.md`](./docs/integrations-guide.md): How to integrate with static site generators or client apps
---
## 📌 Versioning
We follow [Semantic Versioning](https://semver.org/) for schema releases. Refer to the [CHANGELOG.md](CHANGELOG.md) for a history of changes.
---
## 🤝 Contributing
Contributions are welcome! See our [contributing guide](CONTRIBUTING.md) to get started.
---
## 📬 Questions or Feedback?
Have a question or feedback? Please use one of the following channels:
- **[GitHub Issues](https://github.com/ioncakephper/sidebar-navigation-model/issues):** For bug reports and feature requests.
- **[GitHub Discussions](https://github.com/ioncakephper/sidebar-navigation-model/discussions):** For questions, ideas, and general feedback.
---
## 📄 License
Released under the [MIT License](LICENSE). Use it freely in commercial and open-source projects.
---