https://github.com/evolvedbinary/lwdita
Tools and libraries for working with LwDITA
https://github.com/evolvedbinary/lwdita
Last synced: 2 months ago
JSON representation
Tools and libraries for working with LwDITA
- Host: GitHub
- URL: https://github.com/evolvedbinary/lwdita
- Owner: evolvedbinary
- License: agpl-3.0
- Created: 2020-04-28T22:03:47.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2025-03-27T13:57:43.000Z (7 months ago)
- Last Synced: 2025-08-18T16:58:40.251Z (3 months ago)
- Language: TypeScript
- Homepage:
- Size: 1.74 MB
- Stars: 1
- Watchers: 4
- Forks: 1
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# LwDITA
[](https://nodejs.org)
[](https://www.npmjs.com/package/@evolvedbinary/prosemirror-ast)
[](https://circleci.com/gh/evolvedbinary/lwdita)
[](https://coveralls.io/github/evolvedbinary/lwdita?branch=main)
This repository contains a number of tools and libraries for working with LwDITA (Lightweight DITA):
1. lwdita-xdita
A parser and serializer for XDITA (which is the XML representation of LwDITA). This can serialize/deserialize XDITA to an lwdita-ast object tree.
2. lwdita-ast
An object representation of the LwDITA conceptual model. This is used by lwdita-xdita.
The `lwdita-ast` AST complies with the LwDITA specs v0.3.0.2, see: [https://github.com/oasis-tcs/dita-lwdita/releases/tag/v0.3.0.2](https://github.com/oasis-tcs/dita-lwdita/releases/tag/v0.3.0.2)
---
## Working with XDITA
You can add lwdita-xml library to your project using `npm` or `yarn`
```bash
npm install --save @evolvedbinary/lwdita-xdita
```
or
```bash
yarn add @evolvedbinary/lwdita-xdita
```
### XDITA Parsing Example
The following example code shows how to parse XDITA to an lwdita-ast object tree.
```javascript
import { xditaToAst, astToJdita } from "@evolvedbinary/lwdita-xdita/converter";
const xdita = `
...
`
const abortOnError = true;
xditaToAst(xdita, abortOnError)
.then(ast => console.log(JSON.stringify(ast.json, null, 2))
.catch(e => console.log('Failed to convert:', e));
```
As `abortOnError` is set to `true` above, `xditaToAst` will fail when it encounters any error (XML syntax errors, validation errors, etc.). If instead you want to ignore any errors and work with whatever data the function could collect, `abortOnError` to `false` instead.
#### Experimental JDita Model
If you would prefer a simpler object model than the lwdita-ast to work with, we have an experimental object model called JDita. To use this, you can pass the output of `xditaToAst` through the experimental converter function `astToJdita`. Note that this API is subject to change! For example:
```javascript
xditaToAst(xdita, abortOnError)
.then(ast => astToJdita(ast))
.then(jdita => console.log(JSON.stringify(jdita.json, null, 2))
.catch(e => console.log('Failed to convert:', e));
```
### XDITA Serialization Example
A full example with an additional option for serializing the AST object back into XML can be found in the file [example.ts](packages/lwdita-xdita/example.ts).
```javascript
import { InMemoryTextSimpleOutputStreamCollector, XditaSerializer } from "@evolvedbinary/lwdita-xdita/xdita-serializer";
const indentXmlOutput = true;
const indentation = '\t';
const indentationSize = 1;
const outputStream = new InMemoryTextSimpleOutputStreamCollector();
const serializer = new XditaSerializer(outputStream, indentXmlOutput, indentation, indentationSize);
const xdita = serializer.serialize(ast);
console.log(xdita);
```
* You can replace `InMemoryTextSimpleOutputStreamCollector` with your own OutputStream implementation by implementing the interface `SimpleOutputStream`.
* The serialized XML will faithfully contain all XML node types.
## Development
### Prerequisites
For development, you will need Node.js and a node package manager to be installed in your environment.
* Minimal Node version: v20.1.0
* [Yarn](https://yarnpkg.com/) version v4.2.2.
* Optional: This project uses Yarn as its build system. Although we don't support it, if you prefer, it should also be possible to use `npm` instead of `yarn`.
### Installation
Clone the lwdita repository:
```shell
git clone https://github.com/evolvedbinary/lwdita.git
```
Change to the lwdita directory:
```shell
cd lwdita
```
Install all packages:
```shell
yarn install
```
### Packages
This project uses [Yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces).
The current packages, aka. "workspaces" are `lwdita-xdita` and `lwdita-ast` and can be found in folder `packages/`.
Package `lwdita-xdita` contains all files and modules for parsing and serializing XDITA documents.
Package `lwdita-ast` contains all files and modules for creating the AST (Abstract Syntax Tree) of the parsed document, provided by package `lwdita-xdita`.
Both packages depend on each other, as indicated by the `dependency` in their respective package.json files, and they share the same global node modules and commands as declared in the `package.json` file in the root of the project.
If in the future different node modules or commands should be defined for the packages, then you are able to address the packages directly with command
```shell
yarn workspace
```
In the global package.json you can e.g. define specific commands for each package like following pattern:
```json
"scripts": {
"start:package-a": "yarn workspace package-a start",
"start:package-b": "yarn workspace package-b start"
}
```
To get more information about contained workspaces, run command
```shell
yarn workspaces info
```
### Build
To build the project, run:
```shell
yarn run build
```
This will create a `./dist` folder in the root of each sub-module, which contains binaries that can be copied to your own project.
### Generate the TSDoc Documentation
You can generate the documentation by running
```shell
yarn run generate-docs
```
This will generate a new folder `docs` containing an HTML file with the entire TSDoc lwdita documentation.
Open this file in a browser to navigate through the documentation.
### Test
This project also has tests which are written using the Mocha framework.
To execute the test suite and view the code coverage, run:
```shell
yarn run test
yarn run coverage
```
### Example
We have an example file to test the conversion: `example.ts`.
This file contains a small example in `XDITA` format.
If you want to test this library and its conversion from `XDITA` to `JDita`, run:
```shell
yarn run example
```
## How it Works
lwdita-xdita takes in documents in LwDITA XDITA (XML) format, and produces an AST (Abstract Syntax Tree).
XDITA is the LwDITA representation that uses XML to structure information. LwDITA is a subset of DITA, with new multimedia element types added to support interoperability with HTML5.
[Source: https://www.dita-ot.org/4.1/topics/lwdita-input](https://www.dita-ot.org/4.1/topics/lwdita-input)
The conversion process starts by building a tree whose root node represents the XDITA Document Node, then appending each XDITA Element Node as a child node node in the tree.
This will generate a full document tree that represents the original XDITA document as a JavaScript object.
Here's how the nodes are created:
Examples of the nodes `` and ``:
## Publishing a Release
To publish a new release of lwdita please follow these instructions:
**NOTE** The project uses [Semantic Versioning](https://semver.org/), and you should make sure to choose the appropriate next version number to supply to `yarn release`.
```shell
cd lwdita
yarn release 1.2.3
```