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 <li> 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 tests which transform current
> > > markdown to html, the
> > > process seems feasible, at least for simple pages. This process would
> not
> > > be straightforward
> > > JSPWikiMarkup -> HTML -> Markdown, though, some intermediate
> "polishing"
> > > would be
> > > likely to happen (I'm thinking on %%css styles, or identifying links
> > which
> > > are wiki links,
> > > instead of full links).
> > >
> > > This process could also be made available as a maven plugin...
> > >
> > > As for the other way round (Markdown -> JSPWikiMarkup): haven't even
> > > thought of it yet.
> > > In any case, is migrating from one markup to another something likely
> to
> > > happen? Once
> > > you're using one markup and have a bunch of pages, what would trigger
> the
> > > need of migrating
> > > to another markup? Maybe if you're on JSPWikiMarkup you are thinking on
> > > moving to
> > > Markdown b/c that way you can also use the pages as Github pages, or
> > > something like
> > > that (although some markup would be lost). As said before, haven't
> > thought
> > > on this, so any
> > > opinion is more than welcome...
> > >
> > > Yet to be done
> > > ---------------------
> > >
> > > * Plain editor toolbar support
> > >
> > > * Initial set of WikiPages for markdown
> > >
> > > * %%css constructs. A new extension for this should be made, there is
> no
> > > support for this.
> > >
> > > * markup migration tool?
> > >
> > > * plugins implementing HeadingListener (that is, TableOfContents) are
> not
> > > supported: TableOfContents
> > > plugin implements an ad-hoc interface, HeadingListener, which is fired
> by
> > > JSPWikiMarkupParser every
> > > time it finds a header (more precisely, for every heading,
> > > JSPWikiMarkupParser generates a "#" link
> > > with the section reference and then registers a HeadingListener).
> > >
> > > When this plugin is executed then, it knows about the different
> sections,
> > > so it can generate the TOC.
> > > The way flexmarks parses and renders markdown, doesn't allow to
> generate
> > > the TOC this way. Initially,
> > > the Markdown Parser/Renderer generated those #-links, but as soon I
> > > realized TableOfContents wasn't
> > > usable under markdown, I removed the generation of #-links and instead
> of
> > > executing the plugin,
> > > switched it to flexmark's own TOC extension, surrounded with some divs.
> > So
> > > as for now, whereas
> > > TableOfContents generates something like:
> > >
> > > <div class="toc">
> > > <div class="collapsebox">
> > > <h4 id="section-TOC">title</h4>
> > > <ul>/<ol> <!-- either ul or ol -->
> > > <li class="toclevel-1">
> > > <li class="toclevel-2">
> > > <li class="toclevel-3">
> > > </div>
> > > </div>
> > >
> > > the markdown parser/render currently generates something like:
> > > <div class="toc">
> > > <div class="collapsebox">
> > > <h4 id="section-TOC">title</h4>
> > > <!-- Generated by Flexmark's TOC extension -->
> > > <ul>/<ol> <!-- either ul or ol -->
> > > <li> <!--level 1 -->
> > > <ul>/<ol> <!-- either ul or ol -->
> > > <li> <!--level 2 -->
> > > <ul>/<ol> <!-- either ul or ol -->
> > > <li></li> <!-- level 3 -->
> > > </ul>/</ol>
> > > </li>
> > > </ul>/</ol>
> > > </li>
> > > </ul>/</ol>
> > > <!-- End generated by Flexmark's TOC extension -->
> > > </div>
> > > </div>
> > >
> > > So there are two ways of adding support for this:
> > > a) add enough css so that both html render more or less the same.
> > > Parameters parsing should be implemented anyways.
> > > b) add a new Flexmark extension for TOC, probably forking+adapting the
> > > existing TOC extension.
> > >
> > > Hope this clarifies a bit.
> > >
> > > br,
> > > juan pablo
> > >
> > > On Sat, Nov 11, 2017 at 9:36 AM, Dirk Frederickx <
> > > dirk.frederi...@gmail.com>
> > > wrote:
> > >
> > > > Hi Juan,
> > > >
> > > > Adding markup support would indeed be an excellent extension for
> > jspwiki.
> > > >
> > > >
> > > > When changing the parser/render as you proposed, this would mean that
> > > > for one jspwiki instance the backend storage would be changed from
> > > > jspwiki-markup to markdown.
> > > >
> > > > I think this has some important limitations:
> > > > - you can not use both markup styles on the same wiki instance
> > > > so users familiar with jspwiki-markup would be forced to switch
> > > > - we need a solution for migrating a wiki repository between both
> > markups
> > > > to allow smooth transitions
> > > > - we'll need a rewrite the wysiwyg editors, as they are converting
> > > > between html and jspwiki-markup
> > > > - as you indicated we need some adaptions to the plain editor
> > > > but I believe this would mainly be configuration (I can help with
> > > that)
> > > > (configuration to adapt the auto-completions, ...)
> > > >
> > > > ----
> > > >
> > > > Alternatively, we could look for a solution whereby a user can either
> > use
> > > > markdown
> > > > or jspwiki-markup, whenever he/she choses to.
> > > > In this case, the backend would continue to use jspwiki-markup;
> > > > during editing the user can chose another type of input.
> > > >
> > > > The user would then select a "markdown editor" store in its
> > > > UserPreferences.
> > > > (similar as chosing a wysiwyg editor)
> > > > Markdown would be used during editing, and converted to
> jspwiki-markup
> > > > during saving.
> > > > With live-preview the user will see immediately the rendered page.
> > > >
> > > > This approach is similar how the wysiwyg editors work, translating
> > > between
> > > > HTML
> > > > and jspwiki-markup when saving the page.
> > > >
> > > >
> > > > A topic to be addressed is the fact that markdown has a few more
> > features
> > > > than jspwiki-markup.
> > > > For example, with markdown you can go to 6 levels with headers,
> > jspwiki
> > > > has only 3 levels.
> > > > I guess most of these cases would be solvable through the use of
> > specific
> > > > %%css-class constructs.
> > > > To be validated.
> > > >
> > > > ----
> > > >
> > > > Finally, we could also opt for a solution to mix different markup
> > styles
> > > in
> > > > one page.
> > > > You can write a page in jspwiki-markup, but if you want to
> copy/paste
> > > some
> > > > markdown, it can be put inside a PLUGIN or a %%dynamic-style.
> > > >
> > > > The syntax of a PLUGIN (server side markup conversion) may be a bit
> too
> > > > complex
> > > > for most users.
> > > >
> > > > [{MarkdownPlugin
> > > >
> > > > ####This Is a Header####
> > > > }]
> > > >
> > > > Taking the markdown conversion to the browser-level (with javascript)
> > > would
> > > > be feasible as well.
> > > > (eg showdown http://www.showdownjs.com/ )
> > > > %%markdown
> > > >
> > > > ####This Is a Header####
> > > > /%
> > > >
> > > >
> > > > ----
> > > >
> > > > I believe the 2nd option would be preferred.
> > > > However, a faster path to support markdown would be with a plugin
> or a
> > > > dynamic style.
> > > >
> > > >
> > > > br,
> > > > dirk
> > > >
> > > >
> > > >
> > > >
> > > > On Thu, Nov 9, 2017 at 10:00 PM, Juan Pablo Santos Rodríguez <
> > > > juanpablo.san...@gmail.com> wrote:
> > > >
> > > > > Hi!
> > > > >
> > > > > (last e-mail today, promise)
> > > > >
> > > > > At work we've built a POC regarding a tool to generate some static
> > > sites.
> > > > > We're automating JBake site's generation from some assets,
> templates
> > > and
> > > > > markdown content (b/c JBake understands markdown). For content
> > authors
> > > we
> > > > > were looking for a good web-based contents-editor, with versioning
> > > > > capabilities, visually appealing, integrated with our ldap...
> > Something
> > > > > like JSPWiki O:-) but supporting markdown.
> > > > >
> > > > > Given that current master allows switching parsers/renderers, I've
> > been
> > > > > going at work with some customizations we needed to use JSPWiki for
> > > this
> > > > > POC, whenever I've could look at the POC. Most of them are specific
> > to
> > > > our
> > > > > infrastructure (workflows, page storage), but the Markdown support
> is
> > > > > pretty agnostic to us so I asked if I could move it to JSPWiki,
> and I
> > > got
> > > > > my ok :-)
> > > > >
> > > > > In order to simplify things regarding code transfer I'll be putting
> > it
> > > > on a
> > > > > personal github repo (my company is already ok with that), AL
> > > licensed. I
> > > > > have to extract it from our current code-base, so it maybe some
> days
> > > > until
> > > > > I put it on a github repo for review prior to bringing in to
> master,
> > > but
> > > > > this is a heads up.
> > > > >
> > > > > Regarding the maturity of the development
> > > > > * it is POC level, meaning is working and stable, but not feature
> > > > complete.
> > > > > It's enough to demonstrate that JSPWiki can parse/render Markdown,
> > but
> > > > > there are some rough edges
> > > > > ** JSPWikiMarkupParser does a lot of things (f.ex. generates a hash
> > > with
> > > > a
> > > > > link for all headings) that I might overlooked so there might be
> > > > > differences
> > > > > ** No toolbar support on editors (especially on plain editor).
> > Current
> > > > > toolbars aren't thought with multiple parsers on mind, and as the
> POC
> > > > > end-users are more than capable of writing markdown with their bare
> > > hands
> > > > > :-) I've preferred to focus on working the parser and the renderer
> > than
> > > > on
> > > > > this. In order to be feature complete, this should be done, and I
> > > haven't
> > > > > thought on a way of doing it yet, so any idea would be more than
> > > welcome
> > > > > O:-) (probably extending the parsers with a new method to expose
> the
> > > > markup
> > > > > associated which each toolbar button, and present it through a new
> > JSP
> > > or
> > > > > who knows how)
> > > > > * The parsing / rendering is handled with Flexmark (markdown
> parser,
> > AL
> > > > > licensed) and some extensions. It requires Java 7 (we are on Java
> 6).
> > > > Time
> > > > > to think on 2.11 O:-)?
> > > > >
> > > > >
> > > > > br,
> > > > > juan pablo
> > > > >
> > > >
> > >
> >
>
