https://github.com/alipsa/gmd
Groovy Markdown processor
https://github.com/alipsa/gmd
Last synced: over 1 year ago
JSON representation
Groovy Markdown processor
- Host: GitHub
- URL: https://github.com/alipsa/gmd
- Owner: Alipsa
- License: mit
- Created: 2022-07-24T13:55:01.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2025-02-23T20:32:31.000Z (over 1 year ago)
- Last Synced: 2025-02-23T21:26:57.911Z (over 1 year ago)
- Language: JavaScript
- Size: 16.5 MB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://maven-badges.herokuapp.com/maven-central/se.alipsa.groovy/gmd)
[](https://javadoc.io/doc/se.alipsa.groovy/gmd)
# gmd - Groovy Markdown
Groovy markdown is basically markdown with some groovy code for dynamic rendering.
It is based on the GmdTemplateEngine and the [Commonmark
Markdown package](https://commonmark.org/).
A gmd file (or text) is markdown with groovy code in codeblocks starting with \```{groovy} and ending with \```
(similar to rmd and mdr files) and \`= \` for direct value output.
Here is an example:
```markdown
# The thing
Here it is
```{groovy}
import java.time.LocalDate
import java.time.format.TextStyle
import java.util.Locale
def now = LocalDate.parse("2022-07-23")
def dayName(theDate) {
return theDate.getDayOfWeek().getDisplayName(TextStyle.FULL, Locale.getDefault())
}
out.println "## Today (" + dayName(now) + ") is " + now + "."
```
How about that?
```
This will generate the following markdown
````markdown
# The thing
Here it is
```groovy
import java.time.LocalDate
import java.time.format.TextStyle
import java.util.Locale
def now = LocalDate.parse("2022-07-23")
def dayName(theDate) {
return theDate.getDayOfWeek().getDisplayName(TextStyle.FULL, Locale.getDefault())
}
out.println "## Today (" + dayName(now) + ") is " + now + "."
```
## Today (Saturday) is 2022-07-23.
How about that?
````
If you don't want to echo the code in the Markdown document you can set the
echo property to false e.g. \```{groovy echo=false}
Inline variables (similar to the <%= expression %> syntax in scriptlets) can be done using \`= expression \`
here is an example:
````markdown
```{groovy echo=false}
aVal = 123 + 234
```
123 + 234 = `= aVal `
````
Which will result in
```markdown
123 + 234 = 357
```
This kind of Markdown text can then be transformed to html and pdf using the Gmd class e.g:
```groovy
def gmd = new se.alipsa.groovy.gmd.Gmd()
// html is a string of html markup
def html = gmd.gmdToHtml(text)
// create a pdf file from the html
def pdfFile = File.createTempFile("weather", ".pdf")
gmd.htmlToPdf(html, pdfFile)
```
If you want to pass parameters to be used in the gmd text/file you can do that like this:
```groovy
def text = 'Hello `=name`!'
def gmd = new se.alipsa.groovy.gmd.Gmd()
def md = gmd.gmdToMd(text, [name: "Per"])
// Or directly to html
def html = gmd.gmdToHtml(text, [name: "Per"])
// the html can then be used to create a pdf
gmd.htmlToPdf(html, [name: "Per"], new File("pdfFile.pdf"))
```
For "Special" characters e.g. match symbol, you could use the html escape codes. E.g.
to write `X = ∑(√2π + ∛3)`, you could do `X = ∑(√2π + ∛3)` and scope the
expression with parenthesis as appropriate. Otherwise, it will show up as `X = ?(?2? + ?3)` when you turn it into html or pdf.
See [HTML Math Symbols](https://www.toptal.com/designers/htmlarrows/math/) for an extensive list.
An alternative is to generate a whole html doc encoded in UTF-8 that includes unicode fonts.
The gmdToHtmlDoc() and mdToHtmlDoc() does just that. Those methods also includes highlightJs and Bootstrap in the html.
HighlightJS requires the execution of the highligtJs init script for the code sections to be properly formatted.
In order for this to happen, the html code need to be rendered in a browser with javascript support.
Gmd supports processing the javascript by running it in the JavaFx WebView as follows
Example usage:
```groovy
def text = """
# Test
```{groovy echo=false}
def a = 3
for (i in 1..a) {
out.println('Hello ' + i)
}
```
- first
- second
```groovy
def q = 213
println('q is ' + q)
```
X = ∑(√2π + ∛3) = `=Math.sqrt(2* Math.PI) + Math.cbrt(3)`
"""
def gmd = new Gmd()
def html = gmd.gmdToHtmlDoc(text)
// create a pdf file from the html
def pdfFile = File.createTempFile("test", ".pdf")
gmd.processHtmlAndSaveAsPdf(html, pdfFile)
```
Alternatives to using JavaFx WebView might be [Web-K](https://github.com/Earnix/Web-K) or [J2V8](https://github.com/eclipsesource/J2V8)
, but I have not tested any of those.
To use it from within a JavaFx application see the [GmdTestGui](https://github.com/Alipsa/gmd/tree/main/GmdTestGui/src/main/groovy/se/alipsa/gmdtest/GmdTestGui.groovy)
for an approach that I found to provide the best performance and usability.
The library, which requires Java 21 or later, is available from maven central:
Gradle:
```groovy
implementation "se.alipsa.groovy:gmd:2.1.0"
```
Maven:
```xml
se.alipsa.groovy
gmd
2.1.0
```
## Using Gmd from the command line
The release artifacts on github contains a fat jar (e.g. gmd-bundled-2.1.0.jar)
that enables you to use Gmd from the command line.
```
java -jar gmd-bundled-2.1.0.jar toHtml test.gmd test.html
```
or for a pdf:
```
java -jar gmd-bundled-2.1.0.jar toPdf test.gmd test.pdf
```
Note: If you don't want the styled (highlight) PDF version you can use toPdfRaw instead.