maven-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Hervé BOUTEMY <herve.bout...@free.fr>
Subject Re: Customizing the maven-site-plugin Markdown renderer?
Date Fri, 17 Apr 2020 01:02:11 GMT
sorry, I had a look and wanted to take time to have a minimal Maven site generation to compare
with your direct test: I just sent you a PR

your test is great to show the objective
my addition shows the current effective result = admonition markup is not detected, rendered
as-is
I'm quite suprised that the markup is not detected, because flexmark-ext-amonition is a Doxia
Markdown dependency:
https://maven.apache.org/doxia/doxia/doxia-modules/doxia-module-markdown/dependencies.html

I did not expect that the html would be rendered as wanted, but at least that the markup would
have been detected and rendered in some html form

seems it's time to extend the sample to add a customised doxia-module-markdown :)

Regards,

Hervé

Le jeudi 16 avril 2020, 14:56:05 CEST Stephan Wissel a écrit :
> Did you have a chance to look at this?
> 
> On Thu, Apr 9, 2020 at 2:10 AM Stephan Wissel <stephan@wissel.net> wrote:
> > Hello Hervé,
> > 
> > I created a Flexmark sample that is as close as possible to the way
> > Flexmark is used in Doxia:
> > 
> > https://github.com/Stwissel/maven-site-extension/tree/master/simple-flexma
> > rk-example The result can be seen here:
> > https://projectcastle.io/sample.html
> > (I copied a site-plugin generated page and just removed the body part and
> > replace it with the markdown conversion result)
> > 
> > As it seems, to get Adminition working in the rendering, you need to add a
> > single line (and the import/dependency of course)
> > 
> > https://github.com/Stwissel/maven-site-extension/blob/master/simple-flexma
> > rk-example/src/main/java/com/notessensei/demo/Demo1.java#L78
> > 
> > Would you need more samples?
> > 
> > 
> > Create a nice day!
> > Stephan H. Wissel
> > 
> > Phone: +65 96673269
> > Blog <https://www.wissel.net/blog> Twitter
> > <http://twitter.com/notessensei> LinkedIn
> > <http://sg.linkedin.com/in/notessensei> Xing
> > <https://www.xing.com/profile/StephanH_Wissel>
> > 
> > 
> > On Mon, Apr 6, 2020 at 2:42 PM Hervé BOUTEMY <herve.boutemy@free.fr>
> > 
> > wrote:
> >> don't hesitate to share every single concrete step, even the flexmark
> >> standalone test: this will ease working together, ensuring we understand
> >> each
> >> other
> >> 
> >> even before updating doxia-module-markdown with an updated version, there
> >> is a
> >> test with a Maven site to be done with the normal Doxia, to show the
> >> result
> >> (perhaps there is a partial failure only): this will be interesting to
> >> compare
> >> the result against the flexmark standalone test.
> >> 
> >> then once we'll be at updating doxia-module-markdown, yes, you can
> >> override
> >> the version used by the maven-site-plugin by setting dependencies in
> >> plugin
> >> definition
> >> 
> >> Regards,
> >> 
> >> Hervé
> >> 
> >> Le lundi 6 avril 2020, 07:12:14 CEST Stephan Wissel a écrit :
> >> > Sorry for not being clear. The GitHub part is easy.
> >> > What I'm not sure about is how I can test my modification in the
> >> 
> >> context of
> >> 
> >> > the site plugin.
> >> > Would defining my markdown renderer as dependency of the site plugin
> >> > overwrite the build in renderer or do I have to modify the source of
> >> > the
> >> > site plugin too?
> >> > 
> >> > Create a nice day!
> >> > Stephan H. Wissel
> >> > 
> >> > Phone: +65 96673269
> >> > Blog <https://www.wissel.net/blog> Twitter <
> >> 
> >> http://twitter.com/notessensei>
> >> 
> >> > LinkedIn <http://sg.linkedin.com/in/notessensei> Xing
> >> > <https://www.xing.com/profile/StephanH_Wissel>
> >> > 
> >> > On Mon, Apr 6, 2020 at 6:16 AM Hervé BOUTEMY <herve.boutemy@free.fr>
> >> 
> >> wrote:
> >> > > you can create a GitHub repository, or a collection of repositories
> >> > > whatever is necessary
> >> > > 
> >> > > Regards,
> >> > > 
> >> > > Hervé
> >> > > 
> >> > > Le dimanche 5 avril 2020, 18:38:50 CEST Stephan Wissel a écrit :
> >> > > > I did a flexmark standalone test, happy to try to integrate that.
> >> > > > I presume I would define my local moxia modification (after mvn
> >> 
> >> clean
> >> 
> >> > > > install) as a site plugin dependency?
> >> > > > 
> >> > > > Along those lines:
> >> > > >    <plugin>
> >> > > > 
> >> > > > <groupId>org.apache.maven.plugins</groupId>
> >> > > > <artifactId>maven-site-plugin</artifactId>
> >> > > > <version>${maven.site.plugin.version}</version>
> >> > > > <dependencies>
> >> > > > <dependency>
> >> > > > <groupId>org.apache.maven.plugins</groupId>
> >> > > > <artifactId>doxia-module-markdown</artifactId>
> >> > > > <version>1.9.1-stw</version>
> >> > > > </dependency>
> >> > > > </dependencies>
> >> > > > </plugin>
> >> > > > 
> >> > > > Would that work for providing a demo?
> >> > > > 
> >> > > > Create a nice day!
> >> > > > Stephan H. Wissel
> >> > > > 
> >> > > > Phone: +65 96673269
> >> > > > Blog <https://www.wissel.net/blog> Twitter <
> >> > > 
> >> > > http://twitter.com/notessensei>
> >> > > 
> >> > > > LinkedIn <http://sg.linkedin.com/in/notessensei> Xing
> >> > > > <https://www.xing.com/profile/StephanH_Wissel>
> >> > > > 
> >> > > > On Sun, Apr 5, 2020 at 10:11 PM Hervé BOUTEMY <
> >> 
> >> herve.boutemy@free.fr>
> >> 
> >> > > wrote:
> >> > > > > nice work: dos it mean that you managed to have the rendering
as
> >> > > 
> >> > > expected?
> >> > > 
> >> > > > > Can you create a little demo and share?
> >> > > > > 
> >> > > > > On making the extension configurable and easy to use, it
will be
> >> > > 
> >> > > complex
> >> > > 
> >> > > > > from a
> >> > > > > Maven Site Plugin perspective: its relationship with Doxia
(the
> >> 
> >> core
> >> 
> >> > > > > rendering
> >> > > > > engine), Doxia Markdown Module (the markdown parser for
Doxia),
> >> 
> >> Doxia
> >> 
> >> > > > > Sitetools and Doxia Skins will bring some challenges
> >> > > > > 
> >> > > > > That's why we'll need ot go step by step: sharing a first
result
> >> 
> >> with
> >> 
> >> > > > > a
> >> > > > > lot of
> >> > > > > manual config first, then looking on improvement to replace
> >> > > > > manual
> >> > > 
> >> > > config
> >> > > 
> >> > > > > with
> >> > > > > nice parameters
> >> > > > > 
> >> > > > > I would really love to add such extensions, I'll really
need your
> >> 
> >> help
> >> 
> >> > > > > Regards,
> >> > > > > 
> >> > > > > Hervé
> >> > > > > 
> >> > > > > Le vendredi 3 avril 2020, 21:56:41 CEST Stephan Wissel a
écrit :
> >> > > > > > Hi Hervé,
> >> > > > > > 
> >> > > > > > thank you for your reply, appreciate your swift response.
> >> > > > > > It seems to be a little more complex ;-) , but started
easy
> >> 
> >> (looked
> >> 
> >> > > like
> >> > > 
> >> > > > > 1
> >> > > > > 
> >> > > > > > line and 1 import)
> >> > > > > > 
> >> > > > > > Extensions are loaded like line 145 in the
> >> > > > > > MarkdownParser.class:
> >> > > > > > extensions.add(
> >> > > > > > AdminitionExtension.create() );
> >> > > > > > 
> >> > > > > > I did a quick check on CSS/JS. When I put them in
> >> > > > > > /src/site/resources/css
> >> > > > > > and /src/site/resources/js, they get copied into the
target
> >> 
> >> site.
> >> 
> >> > > > > > Then I added  <head><![CDATA[<script src="./js/site.js"
> >> > > > > > type="text/javascript"></script>]]> </head>
> >> > > > > > to the site.xml - which also worked. So the prerequites
can be
> >> > > 
> >> > > handled
> >> > > 
> >> > > > > > in
> >> > > > > > the site.xml without the need to change any code.
> >> > > > > > 
> >> > > > > > However I wouldn't see just to load that one extra
plugin
> >> 
> >> always,
> >> 
> >> > > more
> >> > > 
> >> > > > > like
> >> > > > > 
> >> > > > > > make it configurable. I see two approaches:
> >> > > > > > - read the name of the plugins from a config setting
and leave
> >> 
> >> it to
> >> 
> >> > > the
> >> > > 
> >> > > > > > user - with all consequences - which one they specify
> >> > > > > > - pick one (for starters) and have a config true/false
flag
> >> 
> >> whether
> >> 
> >> > > to
> >> > > 
> >> > > > > load
> >> > > > > 
> >> > > > > > it (default false)
> >> > > > > > 
> >> > > > > > The first might be the more flexible solution, but
could add a
> >> 
> >> can
> >> 
> >> > > > > > of
> >> > > > > > (support) worms.
> >> > > > > > 
> >> > > > > > What do you think?
> >> > > > > > 
> >> > > > > > Create a nice day!
> >> > > > > > Stephan H. Wissel
> >> > > > > > 
> >> > > > > > Phone: +65 96673269
> >> > > > > > Blog <https://www.wissel.net/blog> Twitter <
> >> > > > > 
> >> > > > > http://twitter.com/notessensei>
> >> > > > > 
> >> > > > > > LinkedIn <http://sg.linkedin.com/in/notessensei>
Xing
> >> > > > > > <https://www.xing.com/profile/StephanH_Wissel>
> >> > > > > > 
> >> > > > > > On Sat, Apr 4, 2020 at 1:55 AM Hervé BOUTEMY <
> >> 
> >> herve.boutemy@free.fr>
> >> 
> >> > > > > wrote:
> >> > > > > > > Hi Stefan,
> >> > > > > > > 
> >> > > > > > > The code for Markdown parsing and extensions activation
is in
> >> > > > > > > Doxia
> >> 
> >> > > > > > > Markdown module:
> >> https://maven.apache.org/doxia/doxia/doxia-modules/doxia-module-markdown/
> >> x
> >> 
> >> 
> >> ref/org/apache/maven/doxia/module/markdown/MarkdownParser.html#L13
> >> 
> >> > > > > > > 3
> >> > > > > > > 
> >> > > > > > > I don't really reviewed how extensions are really
activated,
> >> 
> >> but
> >> 
> >> > > > > > > having
> >> > > > > > > now a quick look at this admonition one, I see
that
> >> 
> >> flexmark-java
> >> 
> >> > > > > explains
> >> > > > > 
> >> > > > > > > some prerequisites that have not been integrated
in Doxia:
> >> https://github.com/vsch/flexmark-java/wiki/Extensions#admonition
> >> 
> >> > > > > > > Then I suppose from the code that:
> >> > > > > > > 1. adding admonition markup will create some html
> >> > > > > > > 2. but the rendering will not be ok because prerequisites
> >> 
> >> have not
> >> 
> >> > > > > > > been
> >> > > > > > > integrated
> >> > > > > > > 3. and I fear that the issue will be more complex
than these
> >> > > > > 
> >> > > > > prerequisites
> >> > > > > 
> >> > > > > > > Then it's a full topic to investigate, create
samples to
> >> > > > > > > test,
> >> > > 
> >> > > look at
> >> > > 
> >> > > > > > > current result, then debug ot see what improvements
are
> >> 
> >> necessary
> >> 
> >> > > > > > > I personnally don't have time to work on this,
but if a group
> >> > > > > > > start
> >> > > > > > > working on this topic, I'd be happy to help
> >> > > > > > > 
> >> > > > > > > Regards,
> >> > > > > > > 
> >> > > > > > > Hervé
> >> > > > > > > 
> >> > > > > > > Le vendredi 3 avril 2020, 16:31:49 CEST Stephan
Wissel a
> >> 
> >> écrit :
> >> > > > > > > > Hi there,
> >> > > > > > > > 
> >> > > > > > > > We are using Markdown in our Maven generated
site
> >> > > > > > > > <
> >> 
> >> http://maven.apache.org/plugins/maven-site-plugin/index.html>.
> >> 
> >> > > > > Works
> >> > > > > 
> >> > > > > > > like
> >> > > > > > > 
> >> > > > > > > > a charm. AFAIK the plugin uses Flexmark
> >> > > > > > > > <https://github.com/vsch/flexmark-java>
under the hood,
> >> 
> >> which
> >> 
> >> > > > > supports
> >> > > > > 
> >> > > > > > > > the Admonition
> >> > > > > > > > extensions
> >> > > > > > > > <
> >> > > 
> >> > > https://squidfunk.github.io/mkdocs-material/extensions/admonition/
> >> > > 
> >> > > > > >.
> >> > > > > >
> >> > > > > > > > We would like to use them too, the infoboxes
are quite
> >> 
> >> helpful
> >> 
> >> > > for
> >> > > 
> >> > > > > > > > documentation. Our site configuration in
the pom.xml looks
> >> 
> >> like
> >> 
> >> > > > > > > > this:
> >> > > > > > > > 
> >> > > > > > > > <plugin>
> >> > > > > > > > 
> >> > > > > > > >     <groupId>org.apache.maven.plugins</groupId>
> >> > > > > > > >     <artifactId>maven-site-plugin</artifactId>
> >> > > > > > > >     <version>3.8.2</version></plugin>
> >> > > > > > > > 
> >> > > > > > > > How could we configure it to recognise the
additional
> >> 
> >> markdown?
> >> 
> >> > > > > > > > Also can be found here:
> >> https://stackoverflow.com/questions/61001709/maven-site-generation-using-
> >> a
> >> 
> >> > > > > > > dv>
> >> > > > > > > 
> >> > > > > > > > anced-markdown
> >> > > > > > > > 
> >> > > > > > > > Create a nice day!
> >> > > > > > > > Stephan H. Wissel
> >> > > > > > > > 
> >> > > > > > > > Phone: +65 96673269
> >> > > > > > > > Blog <https://www.wissel.net/blog>
Twitter <
> >> > > > > > > 
> >> > > > > > > http://twitter.com/notessensei>
> >> > > > > > > 
> >> > > > > > > > LinkedIn <http://sg.linkedin.com/in/notessensei>
Xing
> >> > > > > > > > <https://www.xing.com/profile/StephanH_Wissel>
> >> > > 
> >> > > ---------------------------------------------------------------------
> >> > > 
> >> > > > > > > To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> >> > > > > > > For additional commands, e-mail: users-help@maven.apache.org
> >> 
> >> ---------------------------------------------------------------------
> >> 
> >> > > > > To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> >> > > > > For additional commands, e-mail: users-help@maven.apache.org
> >> > > 
> >> > > ---------------------------------------------------------------------
> >> > > To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> >> > > For additional commands, e-mail: users-help@maven.apache.org
> >> 
> >> ---------------------------------------------------------------------
> >> To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
> >> For additional commands, e-mail: users-help@maven.apache.org





---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org


Mime
View raw message