Hi, I have experimented a bit with the capabilities of Paradox and produced a design proposal for the homepage of Apache Pekko (https://pekko.apache.org) available at the following PR: https://github.com/apache/incubator-pekko-site/pull/47
Few notes: - The styling is specific for the homepage. Everything else in the docs remains untouched. - The actual content is mostly unchanged. - The implementation relies on paradox. There has been some discussions on using other technologies for the homepage[1][2]. While paradox makes the job harder (specially in producing html), I think having a dedicated style for the home is what we need for now. Improving the UI aspects of the home from this point it should be easier. - In order to add a dedicated style to the page, I need to override the the `home.st` to include the styling. Let me know if it worth exploring more with other microsite technologies or if you have any feedback on this design. [1] https://github.com/apache/incubator-pekko-site/pull/4 [2] https://lists.apache.org/thread/fthn305vphk7l61gsldm2jyon7q7tz4w On 2023/03/20 18:09:08 Matthew Benedict de Detrich wrote: > > I never suggested changing the currently generated documentation and > said explicitly that this thread is about some additional pages (home > page, download page etc.). > > This is already clear to me (if thats who you were addressing). > > > Writing these additional pages (home page, download page etc.) as > markdown files from which we generate HTML, etc. using sbt-paradox is > a valid solution. There are other ways to generate these additional > pages (home page, download page etc.). There are a number of existing > contributors to Pekko who would be able to use the sbt-paradox > approach. If anyone has a real love for an alternative approach, they > may end up owning that solution - because we may not have many other > contributors who are familiar with that alternative approach. > > I don't have anything necessarily against sbt-paradox, but judging from how > it's designed it doesn't seem the best suited for landing pages in the > sense that it has more complexity than necessary, also do note that the > people that might work on the landing page isn't necessarily going to be > the same set of people that are ultra familiar with paradox/sbt and ithe > like. The other reason why I suggested the alternatives is because they are > specifically designed for micro-sites/landing pages (sbt-microsite in > particular is used for a huge portion of landing pages for OSS Scala > projects, much more than sbt-paradox which generally speaking was used for > mainly for lightbend projects). > > The other main point I made on the github issue is that the majority of the > work will be generating a landing page with branding/design and hence > sbt-paradox is kind of a distraction here. > > > We could have a hybrid approach. We could get basic versions of the > home page and download page created with markdown and sbt-paradox. > Someone else could create a nicer looking alternative set of pages and > we can switch over to those when they are ready. > > Agreed, I also suggested this > > > To unblock this discussion which is one of the blockers for getting a > release done, could I suggest taking a vote on using the > markdown/sbt-paradox approach as an initial solution? To reiterate, I > am not ruling out that an alternative nicer solution could be used > later. > > Sure, go ahead. If we are just going to reuse the current material theme > that is being used for docs its minimal effort and then later on we can > explore other options (also in conjunction with making a nice landing page). > > > On Mon, Mar 20, 2023 at 6:36 PM PJ Fanning <fannin...@apache.org> wrote: > > > I never suggested changing the currently generated documentation and > > said explicitly that this thread is about some additional pages (home > > page, download page etc.). > > > > Writing these additional pages (home page, download page etc.) as > > markdown files from which we generate HTML, etc. using sbt-paradox is > > a valid solution. There are other ways to generate these additional > > pages (home page, download page etc.). There are a number of existing > > contributors to Pekko who would be able to use the sbt-paradox > > approach. If anyone has a real love for an alternative approach, they > > may end up owning that solution - because we may not have many other > > contributors who are familiar with that alternative approach. > > > > We could have a hybrid approach. We could get basic versions of the > > home page and download page created with markdown and sbt-paradox. > > Someone else could create a nicer looking alternative set of pages and > > we can switch over to those when they are ready. > > > > To unblock this discussion which is one of the blockers for getting a > > release done, could I suggest taking a vote on using the > > markdown/sbt-paradox approach as an initial solution? To reiterate, I > > am not ruling out that an alternative nicer solution could be used > > later. > > > > On Mon, 20 Mar 2023 at 16:12, Matthew Benedict de Detrich > > <matthew.dedetr...@aiven.io.invalid> wrote: > > > > > > We are talking about the host site which would be on pekko.apache.org, > > not > > > the documentation, documentation is already handled with sbt-paradox. > > It's > > > meant to be a nice landing page that will point to docs that are > > generated > > > by sbt-paradox. > > > > > > On Mon, Mar 20, 2023 at 2:58 PM Claude Warren, Jr > > > <claude.war...@aiven.io.invalid> wrote: > > > > > > > Is this the website at pekko.apache.org or are you talking about the > > java > > > > doc and equivalent? > > > > > > > > Do we have anybody who has expertise in documentation development? > > > > > > > > On Wed, Mar 1, 2023 at 12:08 PM Matthew Benedict de Detrich > > > > <matthew.dedetr...@aiven.io.invalid> wrote: > > > > > > > > > Previous discussion/s on this > > > > > > > > > > https://github.com/apache/incubator-pekko-site/pull/4 > > > > > https://lists.apache.org/thread/lzfkmq6k6y9t02y4o97jmcgnzxqcp4kh > > > > > > > > > > I think this would be a good time to discuss what software we should > > use > > > > to > > > > > generate our microsite at https://pekko.apache.org/ > > > > > > > > > > Suggestions that have already been made > > > > > > > > > > * Paradox: https://github.com/lightbend/paradox (we use this > > currently > > > > for > > > > > docs and there is a current setup for it, see previously mentioned > > PR) > > > > > * sbt-microsites: https://github.com/47degrees/sbt-microsites (uses > > > > Jekyll > > > > > under the hood but wraps it in sbt which is the same build tool that > > is > > > > > used for all of the other Pekko projects) > > > > > * https://github.com/planet42/Laika: Completely new design for > > > > microsites, > > > > > used somewhat in Scala projects. Also works with sbt > > > > > * https://infra.apache.org/asf-pelican.html Used by Apache projects > > > > > > > > > > I am personally leaning towards either Paradox or sbt-microsites. My > > > > > personal view on this is that while there are other technologies like > > > > > pelican which have historically been used with Apache, to me keeping > > the > > > > > number of tech stacks/build tools in the Pekko ecosystem has higher > > > > > priority and both of these projects use the exact same build tool > > that > > > > > Pekko libraries do. > > > > > > > > > > Ontop of this sbt-paradox is currently being used to generate our > > docs > > > > for > > > > > our various modules, although it does appear to be more catered for > > doc > > > > > generated than microsites (I don't know how significant the > > difference is > > > > > between the two). > > > > > -- > > > > > > > > > > Matthew de Detrich > > > > > > > > > > *Aiven Deutschland GmbH* > > > > > > > > > > Immanuelkirchstraße 26, 10405 Berlin > > > > > > > > > > Amtsgericht Charlottenburg, HRB 209739 B > > > > > > > > > > Geschäftsführer: Oskari Saarenmaa & Hannu Valtonen > > > > > > > > > > *m:* +491603708037 > > > > > > > > > > *w:* aiven.io *e:* matthew.dedetr...@aiven.io > > > > > > > > > > > > > > > > > > -- > > > > > > Matthew de Detrich > > > > > > *Aiven Deutschland GmbH* > > > > > > Immanuelkirchstraße 26, 10405 Berlin > > > > > > Amtsgericht Charlottenburg, HRB 209739 B > > > > > > Geschäftsführer: Oskari Saarenmaa & Hannu Valtonen > > > > > > *m:* +491603708037 > > > > > > *w:* aiven.io *e:* matthew.dedetr...@aiven.io > > > > --------------------------------------------------------------------- > > To unsubscribe, e-mail: dev-unsubscr...@pekko.apache.org > > For additional commands, e-mail: dev-h...@pekko.apache.org > > > > > > -- > > Matthew de Detrich > > *Aiven Deutschland GmbH* > > Immanuelkirchstraße 26, 10405 Berlin > > Amtsgericht Charlottenburg, HRB 209739 B > > Geschäftsführer: Oskari Saarenmaa & Hannu Valtonen > > *m:* +491603708037 > > *w:* aiven.io *e:* matthew.dedetr...@aiven.io >
