Add native markdown formatting for maven #1011
Conversation
|
@nedtwigg This is not fully ready to be merged yet, but please have a look 🙂 |
|
This looks great! Just FYI, there is a way to write the glue code without doing a ton of reflection, I just pushed up #1012 as an example. |
korthout
force-pushed
the
flexmark-java
branch
from
4e04186
to
6fa7b9d
Compare
|
@nedtwigg Wow, that was much easier 😆 Please have another look and let me know what the next step could be. |
lib/src/main/java/com/diffplug/spotless/markdown/FlexmarkStep.java
Outdated
Show resolved
Hide resolved
testlib/src/test/java/com/diffplug/spotless/markdown/FlexmarkStepTest.java
Outdated
Show resolved
Hide resolved
Introduces a new step to natively format markdown. Previously markdown was only available to spotless through the use of prettier which requires nodejs. By natively supporting markdown, java users of spotless have one less dependency to worry about. This uses https://github.com/vsch/flexmark-java, a fork of commonmark-java that made it possible to parse many flavors of markdown into an AST and render it in some way. Among those renderers, there is the option to format to markdown. This renderer (or formatter) supports many formatting options. I've selected a few reasonable ones to get started. A test has been added which is inspired by the example from https://github.com/vsch/flexmark-java/wiki/Markdown-Formatter. I've extended it with some interesting things the formatter seems to take care of. During development, I had some difficulties dealing with idempotency of the step. This is because the parser and formatter can be configured to use different flavors individually. Care should be taken to apply the same configurations to both the parser and formatter to keep it idempotent.
Introduces a markdown section to the maven-plugin's configuration
parameters, which allows to specify the flexmark configuration.
Example:
```xml
<markdown>
<flexmark />
</markdown>
```
This works exactly the same as the configuration of the other steps
By default all `.md` extented files are included, but as I understand
it, this can be overwritten using:
```xml
<markdown>
<flexmark>
<includes>...</includes>
</flexmark>
</markdown>
```
This converts the flexmark step to use the compile-only flexmark glue code, which makes using the library specific code much easier by avoiding the java reflection api.
korthout
force-pushed
the
flexmark-java
branch
2 times, most recently
from
0a45d90
to
48f3745
Compare
|
@nedtwigg Thanks for the comments, I've rebased on the default branch and made the requested changes. Please have another look. |
|
Looks great! Just a few small changes (noted above) and we can ship it! |
None of these jars contain anything Eclipse related. They do however contain the formatter and this might be interesting information.
Including '**/*.md' means that all md files in all sub directories are found. In a multi-module maven project, where spotless is run for each module it would mean that markdown files in sub modules are also found by modules at a higher level of the module hierarchie (i.e. sub modules are sub directories of an other module). This means that files would be processed by the formatter multiple times. Which is obviously less performant. Generally, users should be proteced from this, by decent default settings. However, if we would not include '**/*.md' users might be surprised to learn that some of their files are left untouched. Instead, I chose to warn multi-module users specifically about this. Because the impact (and surprise) of not formatting files in nested folder structures is likely greater than the hit in performance due to processing the files multiple times. Also note that the first problem occurs for both regular maven projects as well as multi-module projects and the latter only occurs on multi-module projects.
korthout
force-pushed
the
flexmark-java
branch
from
48f3745
to
e85c7ab
Compare
|
I've made the requested changes and also thought long about the In addition, I've expanded the maven-plugin readme documentation about this formatter. I imagine that the name @nedtwigg I think that this makes it fully ready for merging from my side. Please have another look. |
|
I removed the default includes so that users are required to specify one manually. The performance of This will get merged and released today. |
|
Published in |
|
Thanks for the review @nedtwigg and changes. I agree with your conclusion on the includes. Happy to see it released 🚀 |
This adds support for native formatting of markdown files, and enables it in Spotless for Maven.
Why?
So far, spotless only supported markdown formatting using the general formatting rules and through the use of prettier. However, the general formatting rules can only do so much. In addition, prettier requires npm and nodejs, which can be an unwanted dependency for maven users. By natively supporting markdown formatting, maven users can now avoid the npm/nodejs requirement, while having the benefit of comprehensive markdown formatting.
How?
This native support comes through the use of flexmark-java. A fork of commonmark-java that made it possible to parse many flavors of markdown into an AST and render it in some way. Among those renderers, there is the option to format to markdown. This renderer (or formatter) supports many formatting options. I've selected a few reasonable ones to get started, but they are not configurable yet.
This changeset adds a basic usage of flexmark-java as Markdown formatter. It adds a new
<markdown>tag to the spotless maven plugin configuration, and subsequently adds a new<flexmark>tag a level deeper. Like all formatters it directly supports the default configurations (e.g.includes).Usage
General usage looks like this:
By default it
includesall*.mdand**/*.mdfiles.Lastly, my thanks to everyone here. Spotless is a great tool. I've really been enjoying using it so far 🙌
Todo