{"id":28635498,"url":"https://github.com/ente/protoml-parser","last_synced_at":"2026-03-04T12:01:57.975Z","repository":{"id":294909486,"uuid":"988448151","full_name":"Ente/protoml-parser","owner":"Ente","description":"ProtoML is a lightweight, declarative markup language designed for writing and structuring meeting protocols, notes and task lists in a human-readable and machine-parseable format.","archived":false,"fork":false,"pushed_at":"2025-05-27T03:23:29.000Z","size":82,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-11-27T09:35:12.749Z","etag":null,"topics":["markup-language","meeting","meetings-enhancement","parser","protocols"],"latest_commit_sha":null,"homepage":"https://openducks.org/protoml.php","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ente.png","metadata":{"files":{"readme":"README.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-05-22T15:01:58.000Z","updated_at":"2025-05-27T03:18:52.000Z","dependencies_parsed_at":"2025-05-22T17:33:22.819Z","dependency_job_id":"9d9c6994-9323-4f8f-81e0-b9c10ce96d53","html_url":"https://github.com/Ente/protoml-parser","commit_stats":null,"previous_names":["ente/protoml-parser"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/Ente/protoml-parser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ente%2Fprotoml-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ente%2Fprotoml-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ente%2Fprotoml-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ente%2Fprotoml-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ente","download_url":"https://codeload.github.com/Ente/protoml-parser/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ente%2Fprotoml-parser/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30079565,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T11:57:42.557Z","status":"ssl_error","status_checked_at":"2026-03-04T11:56:10.793Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["markup-language","meeting","meetings-enhancement","parser","protocols"],"created_at":"2025-06-12T17:10:45.885Z","updated_at":"2026-03-04T12:01:57.909Z","avatar_url":"https://github.com/Ente.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ProtoML - A minimal structured protocol language\n\nProtoML is a lightweight, declarative markup language designed for writing and structuring meeting protocols, notes and task lists in a human-readable and machine-parseable format.\n\n## Installing the Parser\n\n- Clone the repository: `git clone https://github.com/ente/protoml-parser.git`\n- Install the app: `npm install -g .`\n- Restart your terminal\n- Run `protoparser test.pml html` to convert a file named `test.pml` to HTML.\n- Run `protoviewer test.pml [theme]` to view the file with the built-in viewer.\n\n## Install via NPM\n\nRequires Node 18\n\n```bash\nnpm install -g protoml-parser\n```\n\n## Key Concepts\n\n- **Purely declarative** - no logic, no runtime, just the code\n- **Flat structure** with modular references\n- **External resources** such as tags or files are importable\n- **Styling \u0026 referencing syntax** included\n- **Fully parsable into structured JSON, HTML or PDF files**\n\n## Syntax Overview\n| Symbol | Meaning |\n| ------ | ------- |\n| `@command` | Starts a data block (e.g. `@participants`) |\n| `@@command` | Used inside `@meeting`, acts as inline macro |\n| `=` | Declare an ID for referencing |\n| `:` | Assigns value to the declared ID |\n| `-` | Declares a plain list entry |\n| `#`, `##` | Markdown-style headers |\n| `//` | Comment, ignored by parser |\n| `-b Text -b-`, `-i Text -i-`, `-a=url Text -a-` | Inline text styling |\n\n## Example\n\nAll available commands are used in this example.\n\n```plaintext\n@tags_import \"tags.pml\"\n@macro myMacro \"myMacro.pml\"\n\n@date:21.05.2025\n@participants // or @ptp\n=pt1=John Doe,jdoe,jdoe@example.com\n=pt2=Jane Doe\n\n@subjects\n=0:Project Status: TimeTrack\n=1:Security: TLS Check\n\n@tasks\n-[ ] Renew SSL certificate @ptp=pt1 =1 @tag=important // Assigns the tasks to participant \"pt1\", assigns it to subject with ID 1 and tags it with the \"important\" tag\n\n@notes\n- PDF export works -b very well -b-\n\n@meeting\n# Meeting Title: @@e=0 // echoes value of ID 0\n## Participants\n@@e=pt1 , @@e=pt2\n## Some topic\n@@macro=myMacro:title=IMPORTANT;text=@@e=1\n.....\n\n```\n\n## External tags file (tags.pml) - not fully supported, yet\n\n```plaintext\n@tags // this command behaves differently when used in the tags.pml\n=0:Important\n=important:Critical, high priority\n```\n\n## External macro file (myMacro.pml)\n\nMacros allow you to do any styling the render is not able to understand, the below's example therefore can only affectively be used with the `html` render.\n\n* `=name:myMacro` defines the name to be used when accessing the macro like `@@macro=myMacro:....`\n* `=template:` defines what the macro does, this can be multiline.\n\n**For `html` renders, keep in mind, that `protoparser` does not remove JS code contained inside a `html` macro.\nThis could lead to possible security risks like XSS**\nThe behavior for this will be changed in release v1.1.0, allowing native JS integration to your scripts.\n\n```plaintext\n@new_macro\n=name:myMacro\n=template:\n\u003cdiv class=\"warn-box\u003e\u003cstrong\u003e{{title}}\u003c/strong\u003e\u003cbr /\u003e{{text}}\u003c/div\u003e\n\n```\n\n## Upcoming features (release v1.1.0)\n\n- `pdf` render support\n- Full implementation of the `@tag`/`@tags_import` command\n- Fixing not being able to assign subjects to tasks\n- Simple SDK for stable support\n- Shipped macros\n- Adding dynamic macros (with JS support)\n\n\n## Parser logic (simplified)\n\n- `@` starts a block\n- `@@` is used inside `@meeting` for inline substitution/macros\n- `=` declares an ID (`=pt1`) that can be referenced later\n- `@tags_import` includes external tag file\n- Markdown-style headers can be used in `@meeting` content\n- Styling uses `-i -i-` for italic, `-b -b-` for bold and `-a=url -a-` for links, similarly to the Tags in HTML\n\n## Output Format (Example: JSON)\n\nThe JSON format represents the actual AST (Abstract Syntax Tree) used by the renders, which may help you when experiencing issues.\n\n```json\n{\n  \"date\": \"2025-05-21\",\n  \"participants\": [\n    {\n      \"name\": \"John Doe\",\n      \"alias\": \"jdoe\",\n      \"email\": \"jdoe@example.com\",\n      \"id\": \"pt1\"\n    },\n    {\n      \"name\": \"Jane Doe\",\n      \"id\": \"pt2\"\n    }\n  ],\n  \"subjects\": {\n    \"0\": \"Project Status: TimeTrack\",\n    \"1\": \"Security: TLS Check\"\n  },\n  \"tasks\": [\n    {\n      \"done\": false,\n      \"text\": \"Renew SSL certificate\",\n      \"assigned_to\": \"pt1\",\n      \"subject\": \"1\",\n      \"tag\": {\n        \"id\": \"important\",\n        \"label\": \"Critical, high priority\"\n      }\n    }\n  ],\n  \"notes\": [\n    \"PDF export works \u003cb\u003every well\u003c/b\u003e\"\n  ]\n}\n```\n\n## protoparser (protoml-parser)\n\n`protoparser` is the command-line tool for parsing `.pml` files (ProtoML) and converting them into structured formats such as JSON, HTML, PDF and more.\n**The parser currently only support HTML rendering.** The other formats are planned for future releases.\n\n### protoviewer (protoml-viewer)\n\n`protoviewer` is a simple Electron app that allows you to view rendered `.pml` files without the need of third-party tools, like a web browser.\nThe viewer only support HTML rendering, since it's nature of being a electron app.\n\nYou can use it this way: `protoviewer [filename] [theme]`\n\n## Basic web parser\n\nThe web parser allows you to directly write and simply parse ProtoML code in your browser. It does not fully support all features of the parser.\nAdditionally, CSS is not supported within the web parser.\n\nTo start using the web parser, simply open the `web/index.html`\nTo rebuild the parser bundle, run `npm run build:web` in the root directory of the project.\nTo run a webserver directly use `npm run dev` which starts a `serve` command on port 3000.\n\n### Basic Usage\n\n```bash\nprotoparser [options] [filename] [format]\n```\n\n#### Example\n\n```bash\nprotoparser -vvv -output=myfile MeetingYesterday.pml html\n```\n\n### Output\n\n```plaintext\n[INFO] Parsing file: MeetingYesterday.pml\n[DEBUG] Format selected: html\n[DEBUG] Filename: MeetingYesterday.html\n[DEBUG] Filename overwrite: myfile.html\n[DEBUG] Participants: @pt1: John Doe,jdoe,jdoe@example.com\n[DEBUG] Participants: @pt2: Jane Doe\n[DEBUG] IMPORTING TAGS\n[DEBUG] Importing tags from: tags.pml\n[DEBUG] Date: 21.05.2025\n...\n[INFO] DONE\n[INFO] Output written to: myfile.html\n```\n\n### Available Options\n\n| Flag | Description |\n| ---- | ----------- |\n| `-v`, `-vv`, `-vvv` | Verbosity levels: info, debug, trace |\n| `-output=FILENAME` | Define custom output file (without extension) |\n| `-strict` | Enable strict parsing (fail on missing refs) |\n| `-theme=name` | Set export theme (used in HTML/PDF) |\n| `-config=PATH` | Use external config for rendering/export |\n| `--help` | Show CLI help |\n| `--listMacros \u003cdir\u003e` | List all macros in the specified path or builtin macros |\n| `--macroHelp \u003cfile_path\u003e` | Show help for a specific macro file |\n| `--listDocs` | List all available documentation files |\n| `--docs \u003cname\u003e` | Show documentation for a specific command or topic |\n\n### Local development\n\n- Clone the repository\n- Make your changes\n- Run `npm run build:exe` to build linux and windows executables or simply run `npm uninstall -g protoparser \u0026\u0026 npm install -g .` to install your local version globally.\n\n### Supported formats\n\n- `json`\n- `html`\n- `pdf`\n\n### Notes\n\n- If no format is given, defaults to HTML\n- If no output is given, the filename (without extension) is used\n- Error and warnings are printed based on verbosity levels.\n\n## What ProtoML is NOT (yet?)\n\n- It it not a programming language\n- It does not include logic, loops or real variables\n- It is not intended to render HTML or provide full Markdown support\n\n## What ProtoML IS\n\n- A semantic markup for protocols, tasks, topics and notes\n- Extremely easy to read and write\n- Expandable via IDs and modular includes\n- Perfectly suited for Electron apps, PDF generators and structured JSON storage\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fente%2Fprotoml-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fente%2Fprotoml-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fente%2Fprotoml-parser/lists"}