{"id":21766943,"url":"https://github.com/wvbe/docxml","last_synced_at":"2025-04-07T13:04:59.675Z","repository":{"id":50351819,"uuid":"501572931","full_name":"wvbe/docxml","owner":"wvbe","description":"TypeScript (component) library for building and parsing a DOCX file","archived":false,"fork":false,"pushed_at":"2024-10-25T20:31:19.000Z","size":39789,"stargazers_count":32,"open_issues_count":7,"forks_count":7,"subscribers_count":2,"default_branch":"develop","last_synced_at":"2025-03-31T12:04:07.805Z","etag":null,"topics":["deno","docx","ooxml","typescript","word"],"latest_commit_sha":null,"homepage":"https://wvbe.github.io/docxml/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wvbe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2022-06-09T08:42:54.000Z","updated_at":"2025-03-14T21:10:19.000Z","dependencies_parsed_at":"2024-11-18T23:36:57.155Z","dependency_job_id":"6fb0bc17-7ad9-4cd7-a796-b59b41c6904b","html_url":"https://github.com/wvbe/docxml","commit_stats":{"total_commits":166,"total_committers":4,"mean_commits":41.5,"dds":0.01807228915662651,"last_synced_commit":"e5d2fc39087f306f85bd7bf3114ef11b515adce3"},"previous_names":[],"tags_count":89,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wvbe%2Fdocxml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wvbe%2Fdocxml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wvbe%2Fdocxml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wvbe%2Fdocxml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wvbe","download_url":"https://codeload.github.com/wvbe/docxml/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247657276,"owners_count":20974344,"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":["deno","docx","ooxml","typescript","word"],"created_at":"2024-11-26T13:20:59.214Z","updated_at":"2025-04-07T13:04:59.654Z","avatar_url":"https://github.com/wvbe.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DOCX Markup Language\n\nThis is a [NodeJS](https://nodejs.org/)/[Deno](https://deno.land) module for making `.docx` files from scratch or from\nan existing DOCX/DOTX template.\n\nYou could use `docxml` to:\n\n- Create an MS Word file without ever opening MS Word\n- Create a parameterized template file, and render it to DOCX with your data parameters\n- Convert JSON, XML or other data structures to DOCX\n- Parse content from an existing DOCX file\n- Extract style definitions from a DOTX/DOCX file\n\nThis documentation for this lib is available at various locations:\n\n[👉 Documentation site](https://wvbe.github.io/docxml)\u003cbr /\u003e\n[👉 GitHub source](http://github.com/wvbe/docxml)\u003cbr /\u003e\n[👉 Deno mirror](http://deno.land/x/docxml)\u003cbr /\u003e\n[👉 npm mirror](http://npmjs.org/package/docxml)\n\n#### For Deno or for NodeJS\n\n[👉 Main article](./docs/setup/deno-or-node.md)\n\n`docxml` can be used in [NodeJS](https://nodejs.org/) and [Deno](https://deno.land) according to the traditions in those\necosystems. For Node users, simply `npm install docxml` and then `require()` or `import` as you wish. For Deno users,\n`import \"deno.land/x/docxml/mod.ts\"` or use an import map if you wish.\n\n```js\n// NodeJS using CommonJS:\nconst { default: Docxml, Paragraph } = require('docxml');\n\n// NodeJS using ES6 modules, or Deno with an import map\nimport Docxml, { Paragraph } from 'docxml';\n\n// Deno without an import map\nimport Docxml, { Paragraph } from 'https://deno.land/x/docxml/mod.ts';\n```\n\n#### For JSX or for vanilla\n\n[👉 Main article](./docs/setup/jsx-or-not.md)\n\n`docxml` is designed to be used in vanilla JavaScript using class component instances, or using JSX if you're on Deno or\nwant to use NodeJS and a transpiler like Babel:\n\n```ts\nconst para = new Paragraph({ alignment: 'center' }, new Text({}, 'I want a cookie'));\n```\n\n```ts\n/** @jsx Docx.jsx */\nconst para = (\n\t\u003cParagraph alignment=\"center\"\u003e\n\t\t\u003cText\u003eI want a cookie\u003c/Text\u003e\n\t\u003c/Paragraph\u003e\n);\n```\n\n#### For XML or for anything\n\n`docxml` is also designed to be used from scratch/entirely programmatically, or using a more ergonomic API\nto transform from an XML document. Both modes work equally well with vanilla JS or JSX.\n\n```ts\nawait Docx.fromJsx(\n\t\u003cParagraph alignment=\"center\"\u003e\n\t\t\u003cText\u003eI want a cookie\u003c/Text\u003e\n\t\u003c/Paragraph\u003e,\n).toFile('example-1.docx');\n```\n\n```ts\nawait Docx.fromNothing()\n\t.withXmlRule('self::text()', ({ node }) =\u003e \u003cText\u003e{node.nodeValue}\u003c/Text\u003e)\n\t.withXmlRule('self::p', ({ traverse, node }) =\u003e (\n\t\t\u003cParagraph alignment={node.getAttribute('align')}\u003e{traverse()}\u003c/Paragraph\u003e\n\t))\n\t.withXml(`\u003cp align=\"center\"\u003eI want a cookie\u003c/p\u003e`, {})\n\t.toFile('example-2.docx');\n```\n\n#### Features\n\nTo great or small extend, the following features work in the current version of `docxml`. Some items are not ticked off\nyet -- they are not available, but hopefully soon.\n\n[👉 See code examples of some or the more intricate features](https://github.com/wvbe/docxml/wiki/Examples)\n\n**API features:**\n\n- [x] 100% typed\n- [x] Asynchronous components\n- [x] Component composition\n\n**Custom styles:**\n\n- [x] Font size and color\n- [x] Bold, italic, underline styles, strike-through\n- [x] Subscript, superscript, small caps\n- [x] Paragraph spacing and indentation\n- [x] Left/right/center/justified alignment\n- [x] Numbering\n- [ ] Aligning text on tabs\n- [x] Font family\n- [ ] Embed TTF in the DOCX file\n\n**References:**\n\n- [x] Cross references\n- [ ] Table of contents\n\n**Tables:**\n\n- [x] Colspans and rowspans\n- [x] Cell borders\n- [x] [Table borders](http://officeopenxml.com/WPtableBorders.php)\n- [x] [Conditional formatting](http://officeopenxml.com/WPtblLook.php)\n\n**Images:**\n\n- [x] From any `UInt8Array` source\n- [x] Alternative and title text\n- [x] Width and height\n\n**Sections:**\n\n- [x] Width and height\n- [x] Orientation\n- [x] Page headers \u0026 footers\n\n**Comments:**\n\n- [x] Point comment\n- [x] Range comment\n- [ ] Comment reply\n\n**Change tracking:**\n\n- [x] Text additions and deletions\n- [x] Style changes\n- [x] Table row additions and deletions\n\n#### Differences with actual MS Word DOCX\n\nObviously `docxml` is a TypeScript project, which is already very different from how you would normally interact\nwith a DOCX document. More meaningfully however, `docxml` is meant to make writing DOCX _easier_ than going straight\nto OOXML. For example;\n\n- All sizes are of type `Length`, which means it doesn't matter wether you input them as points, centimeters,\n  inches, 1/2, 1/8th or 1/20th points, English Metric Units, and so on.\n- The JSX pragma will try to correct components that would lead to invalid XML structures, by splitting the parents of\n  invalidly placed components recursively until the new position is valid. Moreover, string content in unexpected places\n  is automatically wrapped in `\u003cText\u003e` when using JSX. This makes the configuration of a new DOCX a little more\n  forgiving.\n- Using the `\u003cImage\u003e` or `\u003cComment\u003e` components will automatically create all required relationships etc.\n- Some of the words have changed, generally speaking `docxml` is more verbose than the DOCX verbiage.\n- Generally speaking `docxml` prefers formal (JS) references over references-by-identifier. In those cases the\n  identifiers are randomly generated for you when the `.docx` file is written.\n- Especially in tables and images, a lot of formatting details are automatically applied. In a lot of cases there\n  is no API _yet_ to change them.\n\n#### For contributors\n\nThis project uses unit tests and linting for quality control. To lint, both Deno's own linting as well as ESLint are used.\nPlease run both of the following commands to ensure that a GitHub Action does not fail later.\n\n```sh\n# Once\nnpm install\n\n# Run all unit tests\ndeno task test\n\n# Run all linting\ndeno task lint\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwvbe%2Fdocxml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwvbe%2Fdocxml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwvbe%2Fdocxml/lists"}