{"id":19512506,"url":"https://github.com/vberlier/docutils","last_synced_at":"2025-04-26T04:31:36.341Z","repository":{"id":42215009,"uuid":"174847182","full_name":"vberlier/docutils","owner":"vberlier","description":"Simple javascript parser for docutils xml documents.","archived":false,"fork":false,"pushed_at":"2023-01-07T04:04:25.000Z","size":852,"stargazers_count":3,"open_issues_count":5,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-19T00:01:52.241Z","etag":null,"topics":["docutils","parser","restructuredtext","sphinx","xml"],"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/vberlier.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}},"created_at":"2019-03-10T16:05:35.000Z","updated_at":"2021-08-02T04:53:57.000Z","dependencies_parsed_at":"2023-02-06T11:16:49.251Z","dependency_job_id":null,"html_url":"https://github.com/vberlier/docutils","commit_stats":null,"previous_names":["vberlier/docutils-parser"],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vberlier%2Fdocutils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vberlier%2Fdocutils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vberlier%2Fdocutils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vberlier%2Fdocutils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vberlier","download_url":"https://codeload.github.com/vberlier/docutils/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250931024,"owners_count":21509802,"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":["docutils","parser","restructuredtext","sphinx","xml"],"created_at":"2024-11-10T23:26:26.361Z","updated_at":"2025-04-26T04:31:35.810Z","avatar_url":"https://github.com/vberlier.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# docutils\n\n[![Build Status](https://travis-ci.com/vberlier/docutils.svg?branch=master)](https://travis-ci.com/vberlier/docutils)\n[![npm](https://img.shields.io/npm/v/docutils.svg)](https://www.npmjs.com/package/docutils)\n\n\u003e Simple javascript parser for docutils xml documents.\n\nThis package uses [sax-js](https://github.com/isaacs/sax-js) to parse and turn [docutils xml documents](http://docutils.sourceforge.net/docs/ref/doctree.html) into plain javascript objects. This can be useful for working with documentation generated by tools like [sphinx](http://www.sphinx-doc.org).\n\n```js\nconst docutils = require(\"docutils\");\n\nconst document = docutils.parse(`\n  \u003cdocument source=\".../hello.rst\"\u003e\n    \u003csection ids=\"hello-world\" names=\"hello,\\\\ world!\"\u003e\n      \u003ctitle\u003eHello, world!\u003c/title\u003e\n    \u003c/section\u003e\n  \u003c/document\u003e\n`);\n\nconsole.log(document.children[0].children[0]);\n// Output: { tag: 'title', attributes: {}, children: [ 'Hello, world!' ] }\n```\n\n## Installation\n\nYou can install `docutils` with your `npm` client of choice.\n\n```bash\n$ npm install docutils\n```\n\n## Usage\n\n### docutils.parse(string, plugins = [])\n\nParse the input string and return a hierarchy of plain javascript objects. The function will throw an error if the input string isn't valid xml.\n\nHere's what the function would've returned in the previous example:\n\n```js\n{\n  tag: 'document',\n  attributes: {\n    source: '.../hello.rst'\n  },\n  children: [\n    {\n      tag: 'section',\n      attributes: {\n        ids: 'hello-world',\n        names: 'hello, world!'\n      },\n      children: [\n        {\n          tag: 'title',\n          attributes: {},\n          children: [\n            'Hello, world!'\n          ]\n        }\n      ]\n    }\n  ]\n}\n```\n\nElements are turned into plain javascript objects with a specific structure:\n\n- The `tag` property is the name of the element\n- The `attributes` property is an object mapping each attribute name to its value\n- The `children` property is an array that can contain strings and other elements\n\nKeep in mind that you might need to catch parsing errors where appropriate:\n\n```js\ntry {\n  docutils.parse(\"invalid document\");\n} catch (err) {\n  console.log(err);\n  // Error: Start tag expected, '\u003c' not found\n}\n```\n\n#### Plugins\n\nThe second argument of the `docutils.parse()` function is an optional array of plugins. Plugins are functions that take an instance of `docutils.DocumentParser` as parameter.\n\n```js\nconst titleToUpperCase = (parser) =\u003e {\n  parser.on(\"element:title\", (element) =\u003e {\n    element.children[0] = element.children[0].toUpperCase();\n  });\n};\n\nconst document = docutils.parse(string, [titleToUpperCase]);\n\nconsole.log(document.children[0].children[0]);\n// Output: { tag: 'title', attributes: {}, children: [ 'HELLO, WORLD!' ] }\n```\n\n### docutils.DocumentParser({ plugins = [] } = {})\n\nIt's probably a good idea to always use the `docutils.parse()` function directly, but it's also possible to instantiate the parser manually.\n\n```js\nconst parser = new docutils.DocumentParser();\nconst document = parser.parse(string);\n```\n\nMost of the time, you'll only interact with the parser through plugins. The `docutils.DocumentParser` class inherits from the nodejs [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter) and lets you hook into various stages of the parsing process.\n\n| Event              | Arguments  | Description                                |\n| ------------------ | ---------- | ------------------------------------------ |\n| `document:start`   |            | Emitted before parsing a document          |\n| `document:end`     | `document` | Emitted after parsing a document           |\n| `element`          | `element`  | Emitted after parsing an element           |\n| `element:TAG_NAME` | `element`  | Emitted after parsing a `TAG_NAME` element |\n\n## Contributing\n\nContributions are welcome. This project uses [jest](https://jestjs.io/) for testing.\n\n```bash\n$ npm test\n```\n\nThe code follows the [javascript standard](https://standardjs.com/) style guide.\n\n```bash\n$ npm run lint\n```\n\n---\n\nLicense - [MIT](https://github.com/vberlier/docutils/blob/master/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvberlier%2Fdocutils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvberlier%2Fdocutils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvberlier%2Fdocutils/lists"}