{"id":31982359,"url":"https://github.com/assayyaad/haikal-markdown","last_synced_at":"2025-10-25T06:02:54.324Z","repository":{"id":313519975,"uuid":"1051540967","full_name":"Assayyaad/Haikal-Markdown","owner":"Assayyaad","description":"أدوات هيكلية صارمة لملفات Markdown","archived":false,"fork":false,"pushed_at":"2025-09-22T09:21:19.000Z","size":66,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-22T11:29:00.291Z","etag":null,"topics":["formatter","makdown","parser","strict","validator"],"latest_commit_sha":null,"homepage":"https://haikal.assayyaad.pro/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Assayyaad.png","metadata":{"files":{"readme":"README.en.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-06T07:53:20.000Z","updated_at":"2025-09-22T09:22:00.000Z","dependencies_parsed_at":"2025-09-06T17:30:43.079Z","dependency_job_id":"2fe42169-eb9f-4a2c-8b85-daaa69a7ce0f","html_url":"https://github.com/Assayyaad/Haikal-Markdown","commit_stats":null,"previous_names":["assayyaad/haikal-markdown"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Assayyaad/Haikal-Markdown","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Assayyaad%2FHaikal-Markdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Assayyaad%2FHaikal-Markdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Assayyaad%2FHaikal-Markdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Assayyaad%2FHaikal-Markdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Assayyaad","download_url":"https://codeload.github.com/Assayyaad/Haikal-Markdown/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Assayyaad%2FHaikal-Markdown/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279035019,"owners_count":26089604,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-15T02:00:07.814Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["formatter","makdown","parser","strict","validator"],"created_at":"2025-10-15T02:22:56.225Z","updated_at":"2025-10-15T02:22:58.706Z","avatar_url":"https://github.com/Assayyaad.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Haikal Markdown\n\n\u003cdiv style=\"text-align: center;\"\u003e\n\n[![github](https://img.shields.io/badge/Assayyaad/Haikal--Markdown-000000?logo=github\u0026logoColor=white)](https://www.github.com/Assayyaad/Haikal-Markdown)\n[![npm](https://img.shields.io/badge/haikal--markdown-CB3837?logo=npm\u0026logoColor=white)](https://www.npmjs.com/package/haikal-markdown)\n\n![version](https://img.shields.io/npm/v/haikal-markdown.svg?label=latest\u0026logo=npm)\n![monthly downloads](https://img.shields.io/npm/dm/haikal-markdown.svg?logo=npm)\n\n[![test](https://github.com/Assayyaad/Haikal-Markdown/actions/workflows/test.yml/badge.svg)](https://github.com/Assayyaad/Haikal-Markdown/actions/workflows/test.yml)\n[![documentations](https://github.com/Assayyaad/Haikal-Markdown/actions/workflows/docs.yml/badge.svg)](https://github.com/Assayyaad/Haikal-Markdown/actions/workflows/docs.yml)\n[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?logo=semantic-release)](https://github.com/semantic-release/semantic-release)\n\n[العربية](./README.md)\n\n\u003c/div\u003e\n\nA strict markdown format specification and parser for converting markdown content into structured, manipulable code representations.\n\n**Note**: The syntax and format choices in this package are based on the standards explained in the [Markdown Guide](https://www.markdownguide.org). When multiple syntax options exist for the same markdown element, this package enforces one specific syntax to ensure consistency. The formatter will automatically convert any alternative valid markdown syntax to the chosen syntax enforced by this package.\n\n- [Haikal Markdown](#haikal-markdown)\n  - [Overview](#overview)\n  - [Purpose](#purpose)\n  - [Structure](#structure)\n    - [Document Hierarchy](#document-hierarchy)\n    - [Top-Level: Sections](#top-level-sections)\n    - [Mid-Level: Paragraphs](#mid-level-paragraphs)\n      - [Text Paragraphs](#text-paragraphs)\n      - [Header Paragraphs](#header-paragraphs)\n      - [List Paragraphs](#list-paragraphs)\n      - [Media Paragraphs](#media-paragraphs)\n      - [Footnotes Paragraphs](#footnotes-paragraphs)\n      - [Quote Paragraphs](#quote-paragraphs)\n      - [Code Paragraphs](#code-paragraphs)\n      - [Table Paragraphs](#table-paragraphs)\n    - [Text Formatting](#text-formatting)\n  - [Future Plans](#future-plans)\n    - [Platform-Specific Formatting](#platform-specific-formatting)\n    - [Obsidian Plugin Support](#obsidian-plugin-support)\n  - [Features](#features)\n  - [Installation](#installation)\n  - [Usage](#usage)\n  - [Rules Summary](#rules-summary)\n  - [Contributing](#contributing)\n  - [License](#license)\n\n## Overview\n\nHaikal Markdown defines a rigid markdown structure that enables reliable parsing to code and back without data loss or formatting issues. The specification enforces consistent formatting rules that eliminate ambiguity in markdown interpretation.\n\n## Purpose\n\n- **Bidirectional Conversion**: Parse markdown to structured code representations and convert back to markdown\n- **Consistent Structure**: Enforce strict formatting rules for predictable parsing\n- **Easy Manipulation**: Enable programmatic manipulation of markdown content through structured data\n- **Format Enforcement**: Automatically format any markdown content to comply with Haikal rules, converting alternative valid markdown syntax to the chosen standardized syntax\n\n## Structure\n\n### Document Hierarchy\n\n```\nParsed Markdown File\n├── path: string\n└── sections: Section[]\n    └── Section (Paragraph[])\n        └── Paragraph (union type)\n            ├── TextParagraph\n            ├── HeaderParagraph (levels 1-6)\n            ├── ListParagraph (bullet/number/task)\n            ├── MediaParagraph (image/gif/video/audio)\n            ├── FootnoteParagraph\n            ├── QuoteParagraph (nested paragraphs)\n            ├── CodeParagraph (syntax highlighted)\n            └── TableParagraph (rows/cells)\n```\n\n### Top-Level: Sections\n\nDocuments are divided into sections separated by three dashes (`---`). Each section contains an array of paragraphs.\n\n### Mid-Level: Paragraphs\n\nWithin each section, content is organized into paragraphs separated by exactly two newlines (`\\n\\n`). Each paragraph has a specific type and structure:\n\n#### Text Paragraphs\n\n```javascript\n{\n  type: 'text',\n  content: { text: 'Raw text content' }\n}\n```\n\n#### Header Paragraphs\n\n```javascript\n{\n  type: 'header',\n  level: 1,  // 1-6\n  content: { text: 'Header Text' }\n}\n```\n\n#### List Paragraphs\n\n```javascript\n{\n  type: 'list',\n  listType: 'bullet',  // 'bullet' | 'number' | 'task'\n  contents: [\n    { text: 'First item' },\n    { text: 'Second item' }\n  ]\n}\n```\n\n#### Media Paragraphs\n\n```javascript\n{\n  type: 'media',\n  path: '/path/to/image.jpg',\n  alt: 'Alt text',  // optional\n  url: 'https://link-url.com',  // optional\n  mediaType: 'image',  // optional: 'image' | 'gif' | 'video' | 'audio'\n  extension: 'jpg'  // optional\n}\n```\n\n#### Footnotes Paragraphs\n\n```javascript\n{\n  type: 'footnote',\n  list: [\n    { number: 1, text: 'First reference' },\n    { number: 2, text: 'Second reference' }\n  ]\n}\n```\n\n#### Quote Paragraphs\n\n```javascript\n{\n  type: 'quote',\n  paragraphs: [\n    { type: 'text', content: { text: 'Quoted text' } }\n  ]\n}\n```\n\n#### Code Paragraphs\n\n```javascript\n{\n  type: 'code',\n  text: 'console.log(\"Bismi Allah\");',\n  language: 'javascript'  // optional: supported languages include 'c', 'cpp', 'csharp', 'java', 'javascript', 'python', 'ruby', 'go', 'rust'\n}\n```\n\n#### Table Paragraphs\n\n```javascript\n{\n  type: 'table',\n  rows: [\n    [\n      { text: 'Header 1' },\n      { text: 'Header 2' }\n    ],\n    [\n      { text: 'Cell 1' },\n      { text: 'Cell 2' }\n    ]\n  ]\n}\n```\n\n### Text Formatting\n\nAll text content supports inline formatting with precise positioning:\n\n- **bold** (`\u003cstrong\u003e`)\n- *italic* (`\u003cem\u003e`)\n- ~~strikethrough~~ (`\u003cdel\u003e`/`\u003cs\u003e`)\n- ==highlight== (`\u003cmark\u003e`)\n- `code` (`\u003ccode\u003e`)\n- ~subscript~ (`\u003csub\u003e`)\n- ^superscript^ (`\u003csup\u003e`)\n\nFormats are stored as ranges with start/end indices within the text.\n\n## Future Plans\n\n### Platform-Specific Formatting\n\nSupport for multiple [platform](https://www.markdownguide.org/tools) flavors by providing formatting that converts unsupported markdown syntax to plain text for specific platforms:\n\n- **Obsidian** - Full markdown support with frontmatter\n- **Discord** - Limited markdown with platform-specific formatting\n- **GitLab** - GitLab-flavored markdown support\n- **GitHub** - GitHub-flavored markdown support\n- **WhatsApp** - Basic text formatting only\n\n### Obsidian Plugin Support\n\n- **JS Engine** - Support for JavaScript execution within Obsidian notes\n- Additional plugin integrations as needed\n\n## Features\n\n- **Parser**: Converts Haikal-compliant markdown into structured data\n- **Generator**: Converts structured data back to markdown\n- **Formatter**: Enforces Haikal rules on any markdown content\n- **Validator**: Checks compliance with Haikal specifications\n\n## Installation\n\n```bash\nnpm install haikal-markdown\n```\n\n## Usage\n\n```javascript\nimport { parseMarkdown, serializeMarkdown } from 'haikal-markdown'\n\n// Parse markdown to structure\nconst sections = parseMarkdown(markdownContent)\n\n// Generate markdown from structure\nconst markdown = serializeMarkdown(sections)\n```\n\nFor specific functionalities:\n\n```javascript\n// Import parsing functions\nimport { parseParagraph, parseSection } from 'haikal-markdown/parse'\n\n// Import content manipulation functions\nimport {\n  findHeaders,\n  insertParagraphAt,\n  removeSectionAt\n} from 'haikal-markdown/content'\n\n// Import types\nimport type { ParsedMarkdownFile, Section } from 'haikal-markdown/types'\n```\n\n## Rules Summary\n\n1. Sections separated by exactly `---`\n2. Paragraphs separated by exactly `\\n\\n`\n3. Each paragraph must be a single, recognized type\n4. No mixed content within paragraphs\n5. Consistent indentation and spacing\n6. Headers use ATX format only\n7. Lists use consistent markers\n8. Code blocks must be fenced\n\n## Contributing\n\nContributions welcome! Please ensure all markdown follows Haikal specifications.\n\n## License\n\nThis is free and unencumbered software released into the public domain.\n\nFor more information, please refer to [LICENSE](./LICENSE) or \u003chttps://gitlab.com/-/snippets/4888680\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fassayyaad%2Fhaikal-markdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fassayyaad%2Fhaikal-markdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fassayyaad%2Fhaikal-markdown/lists"}