allow markdown and html files for documentation of library steps #117
Conversation
the current approach with the txt files has the problem that the content must fit the formatter that is globally configured. When a pipeline library is generic enough to be used on many Jenkins instances the documentation might be broken. As Markdown allows to easily write the docs this should be the new default. The snippet is wrapped in a div so we can apply a different styling. The default Jenkins styling doesn't look so good for markdown files at least (no margin before `<hx>` and big margin afterwards)
| <dependency> | ||
| <groupId>io.jenkins.plugins</groupId> | ||
| <artifactId>markdown-formatter</artifactId> | ||
| <version>95.v17a_965e696ee</version> |
There was a problem hiding this comment.
Not in bom? I would omit this one and stick to the more standard antisamy-markup-formatter.
There was a problem hiding this comment.
The antisamy-markup-formatter can only sanitize html and is not able to convert markdown to html. So without this dependency it is not possible to use markdown files for documentation (and I think we should avoid directly setting a dependency to the commonmark java library when we have a plugin that provides it). Maybe we can add it to the bom
There was a problem hiding this comment.
without this dependency it is not possible to use markdown files for documentation
Right, I was proposing to just drop that feature.
Maybe we can add it to the bom
You could. I have no idea how well supported this plugin is.
There was a problem hiding this comment.
Mark Waite is maintaining the plugin, so should be well supported
There was a problem hiding this comment.
I really like the markdown formatter plugin and plan to continue maintaining it. I have it installed on my local Jenkins instances and use it regularly
There was a problem hiding this comment.
I'm happy to submit the plugin to the BOM. It has less than 1000 installations but it is very helpful and has worked well in all the cases where I've used it.
There was a problem hiding this comment.
Submitted for possible inclusion in the plugin bill of materials:
There was a problem hiding this comment.
The markdown formatter plugin is included in plugin bill of materials 2961.v1f472390972e (April 8, 2024).
| </dependency> | ||
| <dependency> | ||
| <groupId>org.jenkins-ci.plugins</groupId> | ||
| <artifactId>antisamy-markup-formatter</artifactId> |
There was a problem hiding this comment.
Needs to be optional, and then use @OptionalExtension.
Proposed wider use to document Pipeline shared libraries jenkinsci/pipeline-groovy-lib-plugin#117 Has 860 installations with that number increasing steadily. https://plugins.jenkins.io/pegdown-formatter/ should be deprecated. It was last released 12 years ago. It has a known security vulnerability. It has no maintainer. It has a health score of 57/100. Still has over 1000 installations, but many of those installations could use markdown formatter.
|
@mawinter69 I'm a little embarrassed to admit it, but I don't know how to see the documentation for a Pipeline library from inside Jenkins. I've installed an incremental build in my development system and have added markdown formatting to a library that I use, but I don't know how to see that from inside Jenkins. Can you give me guidance? |
|
It's documented here: |
There was a problem hiding this comment.
I've confirmed this works with my Jenkins controller that includes the build of this pull request. I've converted the Pipeline documentation to markdown in my Pipeline shared library . Works great.
I've proposed to include the markdown formatter in the plugin bill of materials and have deprecated the pegdown formatter plugin (last released 12 years ago, known vulnerability, using a deprecated markdown library).
The Jenkins infra team would need to be persuaded to install the markdown formatter plugin on ci.jenkins.io before my documentation updates could be used there.
Proposed wider use to document Pipeline shared libraries jenkinsci/pipeline-groovy-lib-plugin#117 Has 860 installations with that number increasing steadily. https://plugins.jenkins.io/pegdown-formatter/ should be deprecated. It was last released 12 years ago. It has a known security vulnerability. It has no maintainer. It has a health score of 57/100. Still has over 1000 installations, but many of those installations could use markdown formatter.
|
I've started a discussion with the infra team in Gitter and have created a help desk ticket for further review of the markdown formatter plugin and for more discussion. The ci.jenkins.io instance is a large scale instance and the infrastructure team needs to be sure that new additions do not disrupt its primary mission. The related help desk ticket is: |
|
@mawinter69 would you be willing to merge the master branch into this pull request so that I can continue using this in my test environment? |
|
btw the way the markdown formatter plugin is used here is more in the form of a library plugin. Same applies to the owasp html formatter. The usage here is independent from what is configured globally in a Jenkins instance for formatting job/run descriptions. |
It is now possible to use also markdown (extension
.md) and html files (extension.html) to document library steps.The corresponding formatters are used respectively (markdown or owasp) for them and the globally configured formatter is ignored.
.txtfiles are still accepted and will use the globally configured formatter as before.The current approach with the txt files has the problem that the content must fit the formatter that is globally configured. When a pipeline library is generic enough to be used on many Jenkins instances the documentation might be broken.
As Markdown allows to easily write the docs this should be the new default I think (requires to adjust https://www.jenkins.io/doc/book/pipeline/shared-libraries/)
The snippet is wrapped in a div so we can apply a different styling. The default Jenkins styling doesn't look so good for markdown files at least (no margin before
<hx>and big margin afterwards)Testing done
Manual testing
added a unit test (for markdown)
Submitter checklist