[
https://issues.apache.org/jira/browse/OOZIE-2734?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16563727#comment-16563727
]
Andras Salamon commented on OOZIE-2734:
---------------------------------------
A few comments about my patch:
* I've updated quite a few maven plugins used during the site creation, so we
also address OOZIE-3164
* A customised version of the twiki pugin was used for HTML creation (because
of special colors and table of contents), there is no need for a customised
plugin for markdown
* To avoid using a customised plugin I've changed a few header formatting
levels. For instance twiki was using a header3 sometimes with a special flag to
avoid the header to appear in the table of contents. I use a simple bold
formatting instead.
* HTML generation from Markdown is quite strict compared to the HTML
generation from Twiki. If the input file is not syntactically correct sometimes
it just gives an error message instead of creating a semi-correct HTML file.
> Switch docs from twiki to markdown
> ----------------------------------
>
> Key: OOZIE-2734
> URL: https://issues.apache.org/jira/browse/OOZIE-2734
> Project: Oozie
> Issue Type: Improvement
> Components: docs
> Affects Versions: trunk
> Reporter: Robert Kanter
> Assignee: Andras Salamon
> Priority: Major
> Attachments: OOZIE-2734-1.patch, OOZIE-2734-2.patch,
> twiki2md_20180730.zip
>
>
> This won't be a fun JIRA, but it would be great if we could switch to
> something easier to work with and better supported like markdown, and get rid
> of the super old twiki we're using for docs.
> I found two tools that I haven't tried out that claim to be able to convert
> this for us:
> # http://pandoc.org/
> # https://github.com/jcodagnone/twiki2markdown
> The former supports a lot of different formats, and according to [this blog
> post|http://goer.org/Journal/2013/02/converting_twiki_foswiki_to_markdown_restructuredtext.html]
> it's better to convert from the rendered html instead of the twiki. But who
> knows which is better, or if the second tool is better than either.
> I think once we switch to a better format, it will be easier to keep the docs
> in better shape, as they could really use some reorganizing. Though we can
> keep that for a separate task.
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
