Re: [DISCUSS] Updating the C* website design

[Rahul Singh]

Seems like even Antora uses another SSG called middleman for their “marketing” 
home page.

https://gitlab.com/antora/antora.org

If the convenience of having both content and docs all in one SSG for code 
maintenance is compatible with the aesthetic/ content / taxonomy strategy need 
for the site visitors, we’ll find out soon enough.




rahul.xavier.si...@gmail.com

http://cassandra.link
The Apache Cassandra Knowledge Base.
On Aug 21, 2020, 8:54 PM -0400, Rahul Singh , wrote:
> Folks,
>
> I applaud the choice of Antora for documentation but I’m not sure it is the 
> best choice for generating an appealing site.
>
> Antora’s self professed strength is in technical documentation. Do we want to 
> stick to a “documentation” / utility look for the front facing site or for a 
> blog?
>
> https://gitlab.com/antora/antora/-/issues/444
>
> I don’t want to rehash any conclusion on choosing Antora for docs or whether 
> asciidoc is the choice for writing documentation.
>
> Could we think about using something like Gatsby or similar for the front 
> facing 5-10 pages + blog ? E. G. Skywalking uses vuepress.
>
> We can use asciidoc as the common format while using Antora for the docs and 
> something else for the rest of the content 
> (https://www.gatsbyjs.com/plugins/gatsby-transformer-asciidoc/)
>
> Something like Gatsby can use both Markdown and Asciidoc and we can migrate 
> from one to the other while still using the same tooling.
>
> Just some thoughts would love feedback!
>
> rahul.xavier.si...@gmail.com
>
> http://cassandra.link
> The Apache Cassandra Knowledge Base.
> On Jul 29, 2020, 1:28 PM -0400, M Brandon Williams , wrote:
> >
> > web

Re: [DISCUSS] Updating the C* website design

[Rahul Singh]

Folks,

I applaud the choice of Antora for documentation but I’m not sure it is the 
best choice for generating an appealing site.

Antora’s self professed strength is in technical documentation. Do we want to 
stick to a “documentation” / utility look for the front facing site or for a 
blog?

https://gitlab.com/antora/antora/-/issues/444

I don’t want to rehash any conclusion on choosing Antora for docs or whether 
asciidoc is the choice for writing documentation.

Could we think about using something like Gatsby or similar for the front 
facing 5-10 pages + blog ? E. G. Skywalking uses vuepress.

We can use asciidoc as the common format while using Antora for the docs and 
something else for the rest of the content 
(https://www.gatsbyjs.com/plugins/gatsby-transformer-asciidoc/)

Something like Gatsby can use both Markdown and Asciidoc and we can migrate 
from one to the other while still using the same tooling.

Just some thoughts would love feedback!

rahul.xavier.si...@gmail.com

http://cassandra.link
The Apache Cassandra Knowledge Base.
On Jul 29, 2020, 1:28 PM -0400, M Brandon Williams , wrote:
>
> web

Re: [DISCUSS] Updating the C* website design

[Mick Semb Wever]

As part of the work, I think all content files should be moved to
> cassandra/doc. This would give a clear separation of concerns;
>  - cassandra/doc contains the material (asciidoc) that is converted to the
> website content.
>  - cassandra-website hosts the live content and contains all the UI
> resources (html templates, css, js, images) that style the content.



Document authors only need to touch one repository to make content edits.



How would this work when you have one version of cassandra-website and
multiple versions of the in-tree docs.

The in-tree docs (cassandra/doc/) is tied to each C* version. Folk want to
look up the documentation specific to the version they are using. While the
cassandra-website docs are for everything not specific to a C* version.

And there are multiple versions of the in-tree docs hosted underneath the
cassandra-website docs, see `asf-staging` and `asf-site` branches. Putting
this in the main repo would make clones bigger. And there's also the issue
of Antora being under MPL and we have to be strict about not distributing
any of its files in any of our releases.

I would have suggested instead, moving as much of the non-version-specific
content to cassandra-website…

regards,
Mick

Re: [DISCUSS] Updating the C* website design

[Anthony Grasso]

Hi Lorina and Mick,

I've raised CASSANDRA-16066
 to capture the
effort required to carry out the work of converting the markdown to
asciidoc. As part of the work, I think all content files should be moved to
cassandra/doc. This would give a clear separation of concerns;
 - cassandra/doc contains the material (asciidoc) that is converted to the
website content.
 - cassandra-website hosts the live content and contains all the UI
resources (html templates, css, js, images) that style the content.

Document authors only need to touch one repository to make content edits.
It also means they only need to run Antora in one location to generate the
content.

The proposal is a fairly common way of publishing content with Antora and
there are a number of examples out there of how to do this. Note, there
would be no alteration to design/content/layout of the website itself. The
only things changing would be the layout of the repositories and the tools
generating the content.

I'm happy to help with the changes if we think this is a good way to go.

Regards,
Anthony

On Thu, 6 Aug 2020 at 05:33, Lorina Poland  wrote:

> The one issue I see with your suggestion about versioned/non-versioned docs
> is that the cassandra/doc repo will have asciidoc files, and currently, all
> the items in the cassandra-website repo are in markdown. There are possible
> solutions (use antora for the website, put the non-versioned docs in their
> own repo which antora can use for building, for example), but that needs
> exploration.
>
> Lorina Poland
>
>
>
>
> On Wed, Aug 5, 2020 at 12:06 PM Michael Semb Wever  wrote:
>
> >
> >
> > > See that here:
> > >
> >
> https://docs.google.com/document/d/1aeNtgyPAsKcNa0GSKvl2ywlFEj30714ry4Sb5turWeE/edit?usp=sharing
> > >
> > > This outline is not complete, just my initial scribblings. Certainly
> > > collaboration would be welcome.
> >
> >
> > This is awesome Lorina. It would also be great to see all non-versioned
> > docs moved out of the cassandra repository and into the cassandra-website
> > repository (where they become easier to update).
> >
> > -
> > To unsubscribe, e-mail: dev-unsubscr...@cassandra.apache.org
> > For additional commands, e-mail: dev-h...@cassandra.apache.org
> >
> >
>