You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@yetus.apache.org by Allen Wittenauer <aw...@apache.org> on 2019/04/19 16:17:10 UTC
[DISCUSS] Website Generation
While working on YETUS-856, I determined that our version of Middleman doesn’t actually seem to fully honor the markdown spec. Now, YETUS-307 (upgrade to Middleman v4) has been hanging around for a while. So I thought sure, let’s see what it does… well… I figured out the source of the generation problems: v4 has changed how it handles file extensions.
In v3:
foo.md -> foo/index.html
In v4:
foo.md -> foo
foo.md.html -> foo.html
So it looks like in order to upgrade, we pretty much need to rework the entire website. If that’s the case, then it may be worth our while to look at alternatives.
Since we’re already in maven territory, it may be worthwhile to just make the jump to maven site (and https://github.com/devacfr/reflow-maven-skin — a fork of the original reflow-maven-skin — looks promising with a few mods). But there are a lot of other generators out there.
Thoughts?
Re: [DISCUSS] Website Generation
Posted by Sean Busbey <bu...@apache.org>.
If I can edit in markdown then I'm happy with whatever.
I already maintain a middleman install just for yetus. I don't mind
whatever replaces it if I get to uninstall middleman.
On Mon, Apr 22, 2019, 09:50 Allen Wittenauer <aw...@apache.org> wrote:
>
>
> > On Apr 21, 2019, at 6:57 PM, Sean Busbey <bu...@apache.org> wrote:
> >
> > I really like editing and authoring in markdown. Is there a maven site
> > plugin to allow that or are we back to some xml stuff?
>
> Settings and themes are XML and content can be in anything that
> doxia supports including markdown. I helped convert Hadoop’s mvn site
> driven documentation to markdown a few years ago. (They still use that
> horrible fluido skin though.)
>
> I have two big reservations around switching to mvn site:
>
> * There is a good chance we’ll want to use a custom maven
> skin, which could end up in us maintaining it as part of the Yetus source
> tree. This isn’t necessarily a bad thing, but I’m not sure we want to be in
> that business.
>
> * doxia tends to be a bit flaky and crash in surprising
> ways. The Hadoop documentation didn't have a lot of complexity and yet it
> still broke it in surprising ways. But that was also before doxia moved
> from pegdown to flexmark .
>
> There are lots of other choices for static site generators. The
> big con I can see for using one of those is that we’ll still be maintaining
> code to push the javadoc, etc, into it.
Re: [DISCUSS] Website Generation
Posted by Stack <st...@duboce.net>.
The static site generators are nice but there is always some ramp-up, a
barrier to contribution whereas the mvn site generation is integral. I just
tried the reflow skin cited above on another project and while 'raw', it
has good doc and addresses the main problem w/ mvn sites, their datedness.
S
On Mon, Apr 22, 2019 at 7:50 AM Allen Wittenauer <aw...@apache.org> wrote:
>
>
> > On Apr 21, 2019, at 6:57 PM, Sean Busbey <bu...@apache.org> wrote:
> >
> > I really like editing and authoring in markdown. Is there a maven site
> > plugin to allow that or are we back to some xml stuff?
>
> Settings and themes are XML and content can be in anything that
> doxia supports including markdown. I helped convert Hadoop’s mvn site
> driven documentation to markdown a few years ago. (They still use that
> horrible fluido skin though.)
>
> I have two big reservations around switching to mvn site:
>
> * There is a good chance we’ll want to use a custom maven
> skin, which could end up in us maintaining it as part of the Yetus source
> tree. This isn’t necessarily a bad thing, but I’m not sure we want to be in
> that business.
>
> * doxia tends to be a bit flaky and crash in surprising
> ways. The Hadoop documentation didn't have a lot of complexity and yet it
> still broke it in surprising ways. But that was also before doxia moved
> from pegdown to flexmark .
>
> There are lots of other choices for static site generators. The
> big con I can see for using one of those is that we’ll still be maintaining
> code to push the javadoc, etc, into it.
Re: [DISCUSS] Website Generation
Posted by Anu Engineer <ae...@hortonworks.com>.
No arguments to any points that you made; That is why I was brought up that topic very gently. I respect your view, the technical rationale and comments.
It is just that right now, we have 3 websites including Ozone (Plug: https://hadoop.apache.org/ozone/ )
If it ended up being Hugo, it would be easier for someone like me to contribute to Yetus websites too.
I hope at least some of the Hadoop committers has invested time and energy on Hugo already, and we could leverage that too.
Thanks
Anu
On 4/22/19, 11:48 AM, "Allen Wittenauer" <aw...@apache.org> wrote:
> On Apr 22, 2019, at 10:41 AM, Anu Engineer <ae...@hortonworks.com> wrote:
>
> * For those not aware, Allen once told me not to use Hugo – hence that remark (
The ‘why' was apparently lost. :( Getting slightly off-topic:
Pre-Hugo:
ant + site source repo
mvn site + source repo
Post-Hugo:
hugo + site source repo
mvn site + source repo
It could have been:
mvn site + source repo
Hadoop already had a static site generator that was part of it’s core and without major work wasn’t going to go away. There was little value in just swapping out ant (which most of the committers have a small grasp of) for hugo (which maybe 3 people understood) just to get updated graphics and layout when there could have been a major process improvement with updated graphics and layout and without a bunch of people having to learn new stuff.
Re: [DISCUSS] Website Generation
Posted by Allen Wittenauer <aw...@apache.org>.
> On Apr 22, 2019, at 10:41 AM, Anu Engineer <ae...@hortonworks.com> wrote:
>
> * For those not aware, Allen once told me not to use Hugo – hence that remark (
The ‘why' was apparently lost. :( Getting slightly off-topic:
Pre-Hugo:
ant + site source repo
mvn site + source repo
Post-Hugo:
hugo + site source repo
mvn site + source repo
It could have been:
mvn site + source repo
Hadoop already had a static site generator that was part of it’s core and without major work wasn’t going to go away. There was little value in just swapping out ant (which most of the committers have a small grasp of) for hugo (which maybe 3 people understood) just to get updated graphics and layout when there could have been a major process improvement with updated graphics and layout and without a bunch of people having to learn new stuff.
Re: [DISCUSS] Website Generation
Posted by Anu Engineer <ae...@hortonworks.com>.
Allen,
With the risk that you might jump on me* (, May I bring up Hugo as a possible candidate?
Apache Hadoop and Apache Ozone and Apache Submarine websites are generated via Hugo today; it uses simple Markdown to generate the website.
--Anu
* For those not aware, Allen once told me not to use Hugo – hence that remark (
On 4/22/19, 7:50 AM, "Allen Wittenauer" <aw...@apache.org> wrote:
> On Apr 21, 2019, at 6:57 PM, Sean Busbey <bu...@apache.org> wrote:
>
> I really like editing and authoring in markdown. Is there a maven site
> plugin to allow that or are we back to some xml stuff?
Settings and themes are XML and content can be in anything that doxia supports including markdown. I helped convert Hadoop’s mvn site driven documentation to markdown a few years ago. (They still use that horrible fluido skin though.)
I have two big reservations around switching to mvn site:
* There is a good chance we’ll want to use a custom maven skin, which could end up in us maintaining it as part of the Yetus source tree. This isn’t necessarily a bad thing, but I’m not sure we want to be in that business.
* doxia tends to be a bit flaky and crash in surprising ways. The Hadoop documentation didn't have a lot of complexity and yet it still broke it in surprising ways. But that was also before doxia moved from pegdown to flexmark .
There are lots of other choices for static site generators. The big con I can see for using one of those is that we’ll still be maintaining code to push the javadoc, etc, into it.
Re: [DISCUSS] Website Generation
Posted by Allen Wittenauer <aw...@apache.org>.
> On Apr 21, 2019, at 6:57 PM, Sean Busbey <bu...@apache.org> wrote:
>
> I really like editing and authoring in markdown. Is there a maven site
> plugin to allow that or are we back to some xml stuff?
Settings and themes are XML and content can be in anything that doxia supports including markdown. I helped convert Hadoop’s mvn site driven documentation to markdown a few years ago. (They still use that horrible fluido skin though.)
I have two big reservations around switching to mvn site:
* There is a good chance we’ll want to use a custom maven skin, which could end up in us maintaining it as part of the Yetus source tree. This isn’t necessarily a bad thing, but I’m not sure we want to be in that business.
* doxia tends to be a bit flaky and crash in surprising ways. The Hadoop documentation didn't have a lot of complexity and yet it still broke it in surprising ways. But that was also before doxia moved from pegdown to flexmark .
There are lots of other choices for static site generators. The big con I can see for using one of those is that we’ll still be maintaining code to push the javadoc, etc, into it.
Re: [DISCUSS] Website Generation
Posted by Sean Busbey <bu...@apache.org>.
I really like editing and authoring in markdown. Is there a maven site
plugin to allow that or are we back to some xml stuff?
On Fri, Apr 19, 2019, 11:17 Allen Wittenauer <aw...@apache.org> wrote:
>
> While working on YETUS-856, I determined that our version of
> Middleman doesn’t actually seem to fully honor the markdown spec. Now,
> YETUS-307 (upgrade to Middleman v4) has been hanging around for a while.
> So I thought sure, let’s see what it does… well… I figured out the source
> of the generation problems: v4 has changed how it handles file extensions.
>
> In v3:
>
> foo.md -> foo/index.html
>
> In v4:
>
> foo.md -> foo
> foo.md.html -> foo.html
>
>
> So it looks like in order to upgrade, we pretty much need to
> rework the entire website. If that’s the case, then it may be worth our
> while to look at alternatives.
>
> Since we’re already in maven territory, it may be worthwhile to
> just make the jump to maven site (and
> https://github.com/devacfr/reflow-maven-skin — a fork of the original
> reflow-maven-skin — looks promising with a few mods). But there are a lot
> of other generators out there.
>
> Thoughts?