tritondatacenter / node-jiramark

A node library for parsing JIRA markup

jiramark

jiramark is a library for parsing the JIRA markup language. This library may fail to parse some markup since it doesn't fall back as gracefully with weird input in the same way that JIRA does. If you have any examples of sane markup that you think this library could handle, please open an issue.

Installation

Install node.js, then:

npm install jiramark

API

markupToHTML(input)

This will return a string representing an approximation of the JIRA markup in HTML. If the input cannot be parsed, then an explanatory Error will be thrown.

You'll also want to insert CSS into the page to help format things the way you want. Here's an example to start with:

div.panel {
  border: 2px solid black;
  margin-left: 1em;
  margin-right: 1em;
}
div.code, div.preformatted {
  font-family: Monospace;
}
div.panel, pre {
  background-color: #eeeeee;
}
div.panel div {
  padding: 9px 12px;
}
div.panel div.panelHeader {
  border-bottom: 2px solid black;
}
th, tr {
  border: 1px solid black;
  padding: 3px 4px;
}
th {
  background-color: #eeeeee;
  text-align: center;
}

License

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. For the full license text see LICENSE, or http://mozilla.org/MPL/2.0/.

Copyright (c) 2019, Joyent, Inc.

Bugs

See https://github.com/joyent/node-jiramark/issues.

node-jiramark's Issues

Support "title" option for blocks

{noformat}, {code}, and {panel} support an option "title", which set a header at the top of the block. This was requested in TritonDataCenter/bugview#29, so it would be nice to add support here so that it can be resolved once bugview uses this library.

Release v0.5.0

Version 0.5.0 will include #10, #11, and #12.

Long arguments shouldn't turn into strikethrough

I'm not sure what fixing this looks like yet, but the following currently gets processed incorrectly:

Run {{cmd -C --long}}

This should produce <p>Run <code>cmd -C --long</code>, but it instead turns into <p>Run <code>cmd <del>C </del>-long</code></p>, since the dashes are treated as strikethrough markup.

Only create links for recognized URI schemes

When using the bracket syntax to create a link ([uri] or [text|uri]), the text is only treated as markup when:

• The URI starts with a valid scheme. JIRA recognizes http, https, ftp, mailto, file, and irc. Others, like tel for telephone numbers or news for newsgroups don't seem to be recognized
• A reference starting with // (e.g. //example.com/path/resource.txt)
• A fragment reference starting with # (e.g. #fragment)

When none of these are the case, then the input text is treated as literal characters instead of as a link. See the commit message at the end of OS-7498 for an example of this.

Treat {color} as formatting syntax instead of a block

Despite having block syntax, JIRA actually treats {color} as formatting syntax instead. It doesn't generate a colored block, but rather wraps text with the <font> tag. Since the <font> tag in considered deprecated, I'm going to make it generate the <span> tag instead when I fix this.

Handle more markup edge cases

There are some edge cases that the first release didn't handle:

• Line breaks within a paragraph should be preserved
• A line of only spaces is equivalent to just a newline
• Leading spaces are okay before opening a block
• Formatting can begin immediately after ending formatting, and after punctuation
• Spaces are allowed at the beginning of a monospace block
• Need to handle paragraphs that end just before the beginning of a list/header/bq.
• Need to allow links inside formatting

There's also some additional markup that people frequently use in JIRA that would be useful to implement:

• Multi-line items in lists
• User references
• Linking URLs written directly in the text

Support attachment links and embedded images

JIRA markup has special syntax for creating links to issue attachments, [foo|^filename]. See for example MANTA-4053. There's also the !foo.png! syntax for embedding images (and other filetypes) in an issue. See for example MANTA-3803.

Handle blocks opened inside a line

It's okay to open up blocks inside a line, and the parser should accept it. Some example tickets include:

• DOCKER-357, where {code} is used in a list item, after some text
• TRITON-1076, where {noformat} is used in a list item, after some text
• OS-7520, where {color} is used in a comment

Detect formatting characters intended as literals

Input like The results are ~5 and ~7 currently get formatted as subscript, but shouldn't be. Because what would be the closing format character is followed by an alphanumeric character, it's not actually interpreted as formatting..

Fix minor spacing issues

Non-breaking spaces (U+00A0) should be treated like regular spaces, and leading newlines should be allowed at the start of a document.

Avoid interpreting a cell-closing "|" as a new table

I noticed that the bugview server got stuck parsing OS-7093. Upon closer inspection realized it was because it had markup like this:

| A | - | - |
| B | - | - |

When the parser first encounts the -, it thinks that it needs to parse a list. When it then encounters the |, it thinks that it's parsing a table inside a list element, rather than closing the table.

Support tables

JIRA has markup for tables. The library should have support for it.

Want a faster parser

While testing out this library in bugview, I found that the parser took an extremely long time to finish processing MANTA-3707. After some experimentation, it seems that the issue is largely a consequence of visiting characters one at a time, and generating a new node for each character.

After trying out several other libraries, I decided to build something on top of Ohm to help speed it up. With my changes, representative regular expressions get propagated up the rule definition where possible, so that it can be quickly accepted or rejected when applied. For rules that are accepted, we generate a thunk node that can be split up into the other representative nodes later on when visited. This allows us to avoid building a large number of nodes for the contents of {noformat}/{code} blocks, where we're just going to use the .sourceString property, and not actually visit any of its contents. (The same goes for lines in paragraphs that contain no special characters.)