maven-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stephan Wissel <step...@wissel.net>
Subject Re: Customizing the maven-site-plugin Markdown renderer?
Date Wed, 08 Apr 2020 18:10:10 GMT
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-flexmark-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-flexmark-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
>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message