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 > > > > > > > > > >
