docs: update README.md

Author: ioncakephper

README.md

@@ -24,24 +24,23 @@ Whether you’re building a static site generator, documentation renderer, or a
 .
 ├── README.md
 ├── CHANGELOG.md
-├── CODE_OF_CONDUCT.md
-├── CONTRIBUTING.md
-├── LICENSE
+├── package.json
+├── docs/
+│   ├── definitions.md
+│   ├── integrations-guide.md
+│   └── overview.md
 ├── schema/
 │   ├── v1.0.0/
 │   │   ├── sidebar.schema.json
 │   │   └── samples/
-│   │       ├── meta-valid-sample.yaml
-│   │       └── valid-sample.yaml
+│   │       └── example.yaml
 │   └── latest/
 │       ├── sidebar.schema.json
 │       └── samples/
-│           ├── meta-valid-sample.yaml
-│           └── valid-sample.yaml
-├── docs/
-│   ├── definitions.md
-│   ├── integration-guide.md
-│   └── overview.md
+│           └── 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.
@@ -58,6 +57,75 @@ Whether you’re building a static site generator, documentation renderer, or a
 
 ---
 
+## 🛠️ 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:
@@ -74,7 +142,7 @@ Explore:
 
 - [`overview.md`](./docs/overview.md): High-level schema purpose and structure
 - [`definitions.md`](./docs/definitions.md): Breakdown of reusable components
-- [`integration-guide.md`](./docs/integration-guide.md): How to integrate with static site generators or client apps
+- [`integrations-guide.md`](./docs/integrations-guide.md): How to integrate with static site generators or client apps
 
 ---
 
@@ -103,4 +171,4 @@ Have a question or feedback? Please use one of the following channels:
 
 Released under the [MIT License](LICENSE). Use it freely in commercial and open-source projects.
 
----
+---