Re: Markdown support
Hi Juan,
Wow ! It seems there are much more aspects to it then simple
parsing/rendering :-)
Concerning the TOC plugin, the current generated HTML always looked funny
to me. (i.e. a flat list of items, versus a regular nested UL/LI
tree)
We'd probably should improve the current TOC plugin to render a regular
UL/LI tree.
The rest is indeed pure css formatting.
I tried to quickly build a %%markdown behaviour based on an open-source
javascript MARKDOWN rendering engine (marked.js), which fully runs in the
browser.
( see https://jspwiki-wiki.apache.org/Wiki.jsp?page=Markdown%20Behavior )
Usage:
%%markdown
{{{
##here comes your markdown!##
}}}
/%
Note: see https://issues.apache.org/jira/browse/JSPWIKI-1040 to simplify
this to
%%%markdown
##here comes your markdown!##
/%
This approach allows for mixing JSPWiki markup and MARKDOWN on the same
page, while keeping the MARKDOWN syntax fully conform to the specification.
So there is no need to extend the MARKDOWN syntax with additional JSPWiki
specific markup, like [{plugins}] or %%css-style.
It does support GFM, but apparently only partially. ( more testing
required -- this obviously depends on the chosen JS library )
I added support for prettified code blocks, and section #hash-links.
The plain editor (with preview) works OK.
Current limitations:
- Links require full URL format : support for simple wiki-pages names
would be cool
- Table Of Contents support : re-rendering of a TOC should be done on the
browser (could be useful for JSPWiki anyway, eg looking at the lack of
TOC support for InsertPages etc...)
- Plain-Editor: Auto-suggestion and TAB-completion could be extended with
MARKDOWN specific configuration.
- ...
BTW:
I tried to install the jspwiki-markdown from github , but got errors with
the mvn clean install.
Mainly due to missing symbols...
=> " add the jspwiki-markdown as a dependency to jspwiki-war " : I need
your help here...
Best regards,
dirk
On Sun, Nov 12, 2017 at 9:41 PM, Juan Pablo Santos Rodríguez <
juanpablo.san...@gmail.com> wrote:
> Hi Dirk,
>
> lot of stuff to cover (meaning: long mail following), will try to address
> all the points:
>
> Initial design
> --
>
> yes, the solution, as it is made consists on a MarkdownParser /
> MarkdownRendered,
> which acts as an alternative to current Parser/Renderer. There's no support
> for mixed
> markup, but I suppose that could be added too, via another Parser/Renderer,
> which
> could act as a Facade, selecting an underlying markup processing depending
> on user
> preferences (or whatever). But that raises more questions, though: once the
> page is
> stored on a given markup, what happens when a user with a different markup
> stored in
> his/her preferences? The type of markup should be also stored as a WikiPage
> attribute...
>
> This was done as POC for evaluating using JSPWiki as a Markdown
> content-publising
> tool. For that flexmark is used, which does 99% of the markup parsing, so
> moving this
> to the client side would imply a totally different take on this. I'm still
> extracting markdown
> support from other custom code, so I expect that by Tuesday/Wednesday I'll
> have it
> uploaded to a github repo.
>
> As it is now, once you commit to a markup style, you're set with that. At
> least as a
> starting point, it's possible to add mixed markup support later on.
>
> The Parser/Renderer is based on Flexmark + a custom JSPWiki extension.
> Currently
> it supports:
> * Normal Markdown
> * Wiki links (internal, external, interwiki, edit, etc.)
> * Variables
> * Almost all plugins (more on this below)
> * Inline images
> * Footnotes
> * ACLs
> * Metadata
> * WYSIWYG edition
>
> The generated HTML markup specific to JSPWiki is almost, if not equal, to
> the current
> JSPWiki markup Parser/Renderer.
>
> The editors
>
>
> I've been skimming through the editors. So far, it seems to me that the js
> files operate
> on generated html (no jspwiki markup handling), so that shouldn't be a
> problem, and the
> JSPs doesn't seem to perform any transformation.
>
> As this was done as a POC, I've been focusing mostly on the
> parsing/rendering that on
> anything else, so it's pretty possible that I've missed something on the
> editors side, but
> without digging on them too much, they seemed to play along well.
>
> Oh, and of course, adaptations to the plain editor *need* to be done. I'm
> thinking that the
> different parsers should make available their configuration up to the
> editors, so the plain
> editor is able to generate the appropiate markup for each parser.
>
> Migration
> -
>
> there's nothing yet, as the POC I was working on assumed no previous
> content, so I haven't
> thought a lot about this... As always, something can/could/should be done:
> there is a
> flexmark extension (haven't investigated that it, though) which performs an
> html to markdown
> conversion. Given that there are unit tes
Re: Markdown support
Hi Dirk,
I got the same reaction when began to work on the markdown extension, I was
expecting it would
take a lot less code. I'll take a look to the markdown behaviour this week
to see how it looks like.
Couple of questions in the meantime O:-)
- would it be possible to set markdown as the only markup? so you don't
have to wrap with
%%(%)markdown (I'm thinking on a do-nothing-parser-and-renderer, so it all
gets done in the browser)
- plugins, variables, acls et all would be still rendered? (the
do-nothing-parser-and-renderer would
better be a do-almost-nothing-parser-and-renderer..)
Regarding the jspwiki-markdown, I've pushed a small fix, so it uses ASF's
snapshot repo, in order
to download latest JSPWiki snaphot, it needs at least 2.10.3-git-42 to be
able to compile. Doing an
mvn clean install on latest master should also make the compilation
problems disappear.
Finally, about " add the jspwiki-markdown as a dependency to jspwiki-war ",
that would mean
something like
https://github.com/juanpablo-santos/jspwiki-markdown/blob/master/jspwiki-markdown-war/pom.xml#L36-L49
But for that you have to have access to latest snapshot, either by
compiling latest master,
or by pulling latest commit and trying again O:-) Either way, thanks for
looking into it!
br,
juan pablo
On Sun, Nov 19, 2017 at 11:15 AM, Dirk Frederickx wrote:
> Hi Juan,
>
> Wow ! It seems there are much more aspects to it then simple
> parsing/rendering :-)
>
> Concerning the TOC plugin, the current generated HTML always looked funny
> to me. (i.e. a flat list of items, versus a regular nested UL/LI
> tree)
> We'd probably should improve the current TOC plugin to render a regular
> UL/LI tree.
> The rest is indeed pure css formatting.
>
>
>
>
> I tried to quickly build a %%markdown behaviour based on an open-source
> javascript MARKDOWN rendering engine (marked.js), which fully runs in the
> browser.
> ( see https://jspwiki-wiki.apache.org/Wiki.jsp?page=Markdown%20Behavior )
>
> Usage:
> %%markdown
> {{{
> ##here comes your markdown!##
> }}}
> /%
>
> Note: see https://issues.apache.org/jira/browse/JSPWIKI-1040 to simplify
> this to
> %%%markdown
> ##here comes your markdown!##
> /%
>
>
> This approach allows for mixing JSPWiki markup and MARKDOWN on the same
> page, while keeping the MARKDOWN syntax fully conform to the specification.
>
> So there is no need to extend the MARKDOWN syntax with additional JSPWiki
> specific markup, like [{plugins}] or %%css-style.
>
> It does support GFM, but apparently only partially. ( more testing
> required -- this obviously depends on the chosen JS library )
> I added support for prettified code blocks, and section #hash-links.
> The plain editor (with preview) works OK.
>
> Current limitations:
> - Links require full URL format : support for simple wiki-pages names
> would be cool
> - Table Of Contents support : re-rendering of a TOC should be done on the
> browser (could be useful for JSPWiki anyway, eg looking at the lack of
> TOC support for InsertPages etc...)
> - Plain-Editor: Auto-suggestion and TAB-completion could be extended with
> MARKDOWN specific configuration.
> - ...
>
>
>
>
>
> BTW:
> I tried to install the jspwiki-markdown from github , but got errors with
> the mvn clean install.
> Mainly due to missing symbols...
> => " add the jspwiki-markdown as a dependency to jspwiki-war " : I need
> your help here...
>
>
> Best regards,
>
> dirk
>
>
>
>
>
> On Sun, Nov 12, 2017 at 9:41 PM, Juan Pablo Santos Rodríguez <
> juanpablo.san...@gmail.com> wrote:
>
> > Hi Dirk,
> >
> > lot of stuff to cover (meaning: long mail following), will try to address
> > all the points:
> >
> > Initial design
> > --
> >
> > yes, the solution, as it is made consists on a MarkdownParser /
> > MarkdownRendered,
> > which acts as an alternative to current Parser/Renderer. There's no
> support
> > for mixed
> > markup, but I suppose that could be added too, via another
> Parser/Renderer,
> > which
> > could act as a Facade, selecting an underlying markup processing
> depending
> > on user
> > preferences (or whatever). But that raises more questions, though: once
> the
> > page is
> > stored on a given markup, what happens when a user with a different
> markup
> > stored in
> > his/her preferences? The type of markup should be also stored as a
> WikiPage
> > attribute...
> >
> > This was done as POC for evaluating using JSPWiki as a Markdown
> > content-publising
> > tool. For that flexmark is used, which does 99% of the markup parsing, so
> > moving this
> > to the client side would imply a totally different take on this. I'm
> still
> > extracting markdown
> > support from other custom code, so I expect that by Tuesday/Wednesday
> I'll
> > have it
> > uploaded to a github repo.
> >
> > As it is now, once you commit to a markup style, you're set with that. At
> > least as a
> > starting point, it's possible to add mixed markup support later on.
> >
> > The Parse
Re: Markdown support
Hi Juan,
- would it be possible to set markdown as the only markup? so you don't
have to wrap with
%%(%)markdown (I'm thinking on a do-nothing-parser-and-renderer, so it all
gets done in the browser)
>> I've been thinking about that also.
>> One option could be to define a new UserPreference or jspwiki-property
to add
specific class or behaviour (such as "markdown" or "prettify")
to the top of the wiki-page so that it become default to all pages.
>> (This is similar to the [{SET page-styles="..."}] variable, but you
still need to add this to each page.)
>> But then you do not have any way to turn it of on a per page basis. ...
>> Anyway, the wrapper %%%markdown ... /% is very limited, and gives you
the option to still use JSPWiki
markup (like plugins, %%styles, ...) mixed with the markdown.
- plugins, variables, acls et all would be still rendered? (the
do-nothing-parser-and-renderer would
better be a do-almost-nothing-parser-and-renderer..)
>> Yep, as long as you keep them outside the %%markdown ... /% wrapper.
>> ACL typically would appear at the start of a page, just before the
markdown.
br,
dirk
On Sun, Nov 19, 2017 at 11:12 PM, Juan Pablo Santos Rodríguez <
juanpablo.san...@gmail.com> wrote:
> Hi Dirk,
>
> I got the same reaction when began to work on the markdown extension, I was
> expecting it would
> take a lot less code. I'll take a look to the markdown behaviour this week
> to see how it looks like.
> Couple of questions in the meantime O:-)
> - would it be possible to set markdown as the only markup? so you don't
> have to wrap with
> %%(%)markdown (I'm thinking on a do-nothing-parser-and-renderer, so it all
> gets done in the browser)
> - plugins, variables, acls et all would be still rendered? (the
> do-nothing-parser-and-renderer would
> better be a do-almost-nothing-parser-and-renderer..)
>
> Regarding the jspwiki-markdown, I've pushed a small fix, so it uses ASF's
> snapshot repo, in order
> to download latest JSPWiki snaphot, it needs at least 2.10.3-git-42 to be
> able to compile. Doing an
> mvn clean install on latest master should also make the compilation
> problems disappear.
>
> Finally, about " add the jspwiki-markdown as a dependency to jspwiki-war ",
> that would mean
> something like
> https://github.com/juanpablo-santos/jspwiki-markdown/blob/
> master/jspwiki-markdown-war/pom.xml#L36-L49
> But for that you have to have access to latest snapshot, either by
> compiling latest master,
> or by pulling latest commit and trying again O:-) Either way, thanks for
> looking into it!
>
>
> br,
> juan pablo
>
>
>
> On Sun, Nov 19, 2017 at 11:15 AM, Dirk Frederickx <
> dirk.frederi...@gmail.com
> > wrote:
>
> > Hi Juan,
> >
> > Wow ! It seems there are much more aspects to it then simple
> > parsing/rendering :-)
> >
> > Concerning the TOC plugin, the current generated HTML always looked
> funny
> > to me. (i.e. a flat list of items, versus a regular nested UL/LI
> > tree)
> > We'd probably should improve the current TOC plugin to render a regular
> > UL/LI tree.
> > The rest is indeed pure css formatting.
> >
> >
> >
> >
> > I tried to quickly build a %%markdown behaviour based on an open-source
> > javascript MARKDOWN rendering engine (marked.js), which fully runs in
> the
> > browser.
> > ( see https://jspwiki-wiki.apache.org/Wiki.jsp?page=Markdown%20Behavior
> )
> >
> > Usage:
> > %%markdown
> > {{{
> > ##here comes your markdown!##
> > }}}
> > /%
> >
> > Note: see https://issues.apache.org/jira/browse/JSPWIKI-1040 to
> simplify
> > this to
> > %%%markdown
> > ##here comes your markdown!##
> > /%
> >
> >
> > This approach allows for mixing JSPWiki markup and MARKDOWN on the same
> > page, while keeping the MARKDOWN syntax fully conform to the
> specification.
> >
> > So there is no need to extend the MARKDOWN syntax with additional
> JSPWiki
> > specific markup, like [{plugins}] or %%css-style.
> >
> > It does support GFM, but apparently only partially. ( more testing
> > required -- this obviously depends on the chosen JS library )
> > I added support for prettified code blocks, and section #hash-links.
> > The plain editor (with preview) works OK.
> >
> > Current limitations:
> > - Links require full URL format : support for simple wiki-pages names
> > would be cool
> > - Table Of Contents support : re-rendering of a TOC should be done on the
> > browser (could be useful for JSPWiki anyway, eg looking at the lack of
> > TOC support for InsertPages etc...)
> > - Plain-Editor: Auto-suggestion and TAB-completion could be extended
> with
> > MARKDOWN specific configuration.
> > - ...
> >
> >
> >
> >
> >
> > BTW:
> > I tried to install the jspwiki-markdown from github , but got errors with
> > the mvn clean install.
> > Mainly due to missing symbols...
> > => " add the jspwiki-markdown as a dependency to jspwiki-war " : I need
> > your help here...
> >
> >
> > Best regards,
> >
> > dirk
> >
> >
> >
> >
> >
> > On Sun, Nov 12, 201
