{"id":22650010,"url":"https://github.com/pauliorandall/p23","last_synced_at":"2026-03-02T05:06:16.578Z","repository":{"id":235010140,"uuid":"789905324","full_name":"PaulioRandall/p23","owner":"PaulioRandall","description":"Simple tool for parsing referenceable comments within Svelte components.","archived":false,"fork":false,"pushed_at":"2024-07-02T09:09:21.000Z","size":295,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"trunk","last_synced_at":"2025-02-09T21:35:41.796Z","etag":null,"topics":["documentation","metadata","plunder","svelte"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PaulioRandall.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2024-04-21T21:35:03.000Z","updated_at":"2024-07-02T09:09:09.000Z","dependencies_parsed_at":"2024-05-16T23:47:44.843Z","dependency_job_id":"277c5c61-b986-4d40-bf96-b8ece5233276","html_url":"https://github.com/PaulioRandall/p23","commit_stats":null,"previous_names":["pauliorandall/p21","pauliorandall/p23"],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaulioRandall%2Fp23","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaulioRandall%2Fp23/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaulioRandall%2Fp23/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaulioRandall%2Fp23/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PaulioRandall","download_url":"https://codeload.github.com/PaulioRandall/p23/tar.gz/refs/heads/trunk","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240395737,"owners_count":19794573,"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","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":["documentation","metadata","plunder","svelte"],"created_at":"2024-12-09T08:30:00.401Z","updated_at":"2026-03-02T05:06:11.545Z","avatar_url":"https://github.com/PaulioRandall.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Made to be Plundered](https://img.shields.io/badge/Made%20to%20be%20Plundered-royalblue)\n[![Latest version](https://img.shields.io/github/v/release/PaulioRandall/p23)](https://github.com/PaulioRandall/p23/releases)\n[![Release date](https://img.shields.io/github/release-date/PaulioRandall/p23)](https://github.com/PaulioRandall/p23/releases)\n\n# P23\n\nSimple tool for parsing referenceable comments within Svelte components.\n\n## Made to be Plundered\n\nFork, pillage, and plunder! Do whatever as long as you adhere to the project's permissive MIT license.\n\n## Examples\n\nGiven the component:\n\n```html\n\u003c!-- BartSimpson.svelte --\u003e\n\n\u003cscript\u003e\n  //p23.ay_caramba A node with the name (or path) 'ay_caramba'.\n\n  /*p23.eat.my.shorts\n    A block node with multiple path segments.\n  */\n\n  /*p23.eat.my.shorts\n    Nodes with the same are presented in order as you'll see.\n  */\n\n  //p23.js.multiline\n  // An unbroken\n  // series of\n  //\n  // single line comments.\n\u003c/script\u003e\n\n\u003cdiv\u003e\n  \u003c!--p23.html.line P23 will parse HTML comments too. --\u003e\n  \u003cslot /\u003e\n\n  \u003c!--p23.html.block\n    That includes\n    multiline block comments. \n  --\u003e\n\u003c/div\u003e\n```\n\nWhen parsed with:\n\n```js\nimport p23 from 'p23'\n\nconst fileDocs = p23()\n```\n\nThen `fileDocs` will be something like:\n\n```js\n[\n  {\n    name: \"BartSimpson.svelte\",\n    relPath: \"./src/lib/BartSimpson.svelte\",\n    absPath: \"/home/esmerelda/github/my-project/src/lib/BartSimpson.svelte\",\n    nodes: {\n      ay_caramba: [\"//p23.ay_caramba A node with the name (path) 'ay_caramba'.\"],\n      eat: {\n        my: {\n          shorts: [`/*p23.eat.my.shorts\n    A block node with multiple path segments.\n  */`, `/*p23.eat.my.shorts\n    Nodes with the same are presented in order as you'll see.\n  */`]\n        }\n      },\n      js: {\n        multiline: [`//p23.js.multiline\n  // An unbroken\n  // series of\n  //\n  // single line comments.`]\n      },\n      html: {\n        line: [`\u003c!--p23.html.line P23 will parse HTML comments too. --\u003e`],\n        block: [`\u003c!--p23.html.block\n    That includes\n    multiline block comments. \n  --\u003e`],\n      }\n    }\n  }\n]\n```\n\n**To parse and clean nodes:**\n\n```js\nimport p23, { cleanNodes } from 'p23'\n\nconst files = p23()\nconst fileDocs = cleanNodes(files)\n```\n\nCleaning removes the P23 delimiter and leading whitespace from lines. Whitespace filtering is opinionated:\n\n- The first line determines the base indent.\n- For each JS and CSS block comment line other than the first:\n  - The base indent is removed.\n  - Either ` * `, tabs, or two sequential spaces are removed if found.\n- For each JS multiline comment line other than the first:\n  - The base indent is removed.\n  - A single space is removed if found.\n- For each HTML comment line other than the first:\n  - The base indent is removed.\n  - A tab or single space is removed if found.\n\n```js\n[\n  {\n    name: \"BartSimpson.svelte\",\n    relPath: \"./src/lib/BartSimpson.svelte\",\n    absPath: \"/home/esmerelda/github/my-project/src/lib/BartSimpson.svelte\",\n    nodes: {\n      ay_caramba: [\"A node with the name (path) 'ay_caramba'.\"],\n      eat: {\n        my: {\n          shorts: [`\nA block node with multiple path segments.\n  `, `\nNodes with the same are presented in order as you'll see.\n  `]\n        }\n      },\n      js: {\n        multiline: [`\nAn unbroken\n\nseries of\n\nsingle line comments.`]\n      },\n      html: {\n        line: [` P23 will parse HTML comments too. `],\n        block: [`\nThat includes\nmultiline block comments. \n  `],\n      }\n    }\n  }\n]\n```\n\n## Usage Notes\n\n1. Doc strings include the comment delimters unless cleaned with `cleanNodes` or by your own means.\n2. Cleaning and managing other whitespace in node values is your responsibility.\n3. Path segments must adhere to: `^[$@a-zA-Z_][$@a-zA-Z0-9_\\-]*$`. This list may be extended in future to include **almost** any string character.\n4. Nodes with the same name are in order of appearance within the file.\n5. Yes, it will parse block comments in CSS nodes too.\n6. \"Don't have a cow, Man!\"\n\n## Options\n\nDefaults noted as field values. \n\nFor information on glob and glob options see [NPM _glob_ package](https://www.npmjs.com/package/glob) ([Github](https://github.com/isaacs/node-glob)). I should hide this library behind the API, but CBA at least for the first version.\n\n```js\nimport p23 from 'p23'\n\np23({\n  // Custom prefix for nodes.\n  // You could use \"@\" to parse \"//@name: value\" for example.\n  prefix: \"p23.\",\n\n  // For SvelteKit packaged libraries you would use\n  // \"dist/*.svelte\" or some variation of it.\n  glob: \"**/*.svelte\",\n  globOptions: {}\n})\n```\n\n## Back Story\n\nI simply wanted to document a component's API within itself and regenerate that documentation in a form I please, particularly within a README. To clarify, I want to document the **interface** (API) to the component by documenting its single implementation. Ths includes details such as name, description, module \u0026 instance properties, slots, set context, and defaults where applicable.\n\nA few documentation tools come close but none completely satisfy my need for simplicity, readability, flexibility, and ability to document all mentioned aspects of the API. Furthermore, existing tools traded-off too much flexibility for conciseness. So I set about creating [**P24**](https://github.com/PaulioRandall/p24). In the process I was able to separate the concern of parsing annotated comments into **P23**.\n\nTo clarify, **P23** is not about documenting components (**P24** does that). It is about specifying parsable comments within Svelte components. The output can then be used by a documentation package or some other innovative tooling. For example, you could build a changelog package where maintainers write changes to a component within the component. The package could render them in a similar manner to how **P24** does with API documentation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpauliorandall%2Fp23","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpauliorandall%2Fp23","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpauliorandall%2Fp23/lists"}