[
https://issues.apache.org/jira/browse/METRON-662?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15829577#comment-15829577
]
Matt Foley commented on METRON-662:
-----------------------------------
Hi all,
I’ve put together a prototype doc book, along the lines we discussed, and it
looks pretty worthwhile.
Many thanks to Mike M. who whipped the pom.xml file into shape, and helped me
find the right site.xml file to imitate.
If you’re interested, please do a single-branch clone as follows:
bq. git clone --single-branch -b METRON-660
https://github.com/mattf-horton/incubator-metron.git \[clonename\]
(or whatever git command pleases you :-)
In this branch, there’s a new top-level subdirectory named site-book/. This is
not necessarily how we want to integrate stuff, it was just convenient to do it
separate from the existing site/ directory for now. To build the book, do
these three commands:
{code}
cd site-book/
bin/generate-md.sh #This gathers all the *.md files into
site-book/src/site/markdown/**, and generates the menu tree into
site-book/src/site/site.xml
mvn clean site:site #This builds the book with the maven site plugin
and doxia-markdown plugin
{code}
If both those steps are successful, you can then go to a browser and open
bq. file:///Users/yourname/yourpath/clonename/site-book/target/site/index.html
and see the book, with the nav menu on the LHS.
It’s important to note that a very usable (not perfect) nav hierarchy has been
auto-generated; this is not hardwired nor hand-edited.
I do plan to add some overrides that allow individual items in the menu to be
tweaked.
While it already looks fairly nice, and clearly illustrates the value of
building a book, there are two glaring issues.
* Doxia-markdown doesn’t process the triple back-tick (```) the same way as
Github Markdown. It seems to color-code it as <code>, but doesn’t preserve
line breaks, which is really bad.
* Similarly, it only processes bullet lists in isolation, and it doesn’t
correctly combine bullet lists subordinate to a numbered list.
The upshot is that
* both code and bullet lists often lose their linebreaks, and get mushed into
run-on paragraphs, usually combined with the preceding paragraph, and
* bullet lists interrupt numbered lists and make them start over at #1.
Perhaps 80-90% of these issues can be fixed by editing the markdown files to
put blank lines around the list formats. I started doing this, but I didn’t
want to obscure the proto by editing tons of .md files. As of this proto, only
the half dozen actually broken files (that caused maven site build errors) have
been fixed.
The other 10-20% will just require simplification of the markdown used, unless
we can get an updated version of the plugins.
Anyway, please take a look and share your thoughts.
Thanks,
--Matt
> feasibility POC for doxia-markdown plugin
> -----------------------------------------
>
> Key: METRON-662
> URL: https://issues.apache.org/jira/browse/METRON-662
> Project: Metron
> Issue Type: Sub-task
> Reporter: Matt Foley
>
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
