[
https://issues.apache.org/jira/browse/CASSANDRA-16115?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17221037#comment-17221037
]
Anthony Grasso commented on CASSANDRA-16115:
--------------------------------------------
Hi Melissa,
Unless I've missed something, the proposal sounds very similar to what we are
doing with Antora. As part of CASSANDRA-16066, I have started developing a
prototype which does the static content generation using Antora. Currently, it
does the following transformations:
* *Cassandra Code -> AsciiDoc* (generate AsciiDoc files using code in Cassandra
repository)
* *AsciiDoc -> HTML* (AsciiDoc files sourced from Cassandra and Cassandra
Website repositories)
In the above case AsciiDoc files are generated from the Cassandra repository.
To generate the HTML for the website Antora uses the AsciiDoc files from both
the Cassandra and the Cassandra Website repositories. The AsciiDoc files are in
a plain-text format similar to markdown.
The HTML content generated by Antora is styled using predefined HTML and
JavaScript templates. This allows for the separation of concerns highlighted in
your above proposal. To explicitly define the separation, the prototype I am
developing for the Cassandra Website repository uses the following two top
level directories:
* */cassandra-website/site-content*
* */cassandra-website/site-ui*
*site-content* directory has the AssciDoc files containing the content to be
published on the site. Any changes to wording on the website would be made to
the files in here. The content would be unrelated to a particular Cassandra
release version. All content related to a Cassandra release version e.g.
manuals, technical docs, etc would be generated from the Cassandra repository.
In this case, any changes to the technical documentation for a particular
Cassandra version would made in the Cassandra repository.
*site-ui* directory has the HTML templates and JavaScript that defines the
presentation of the content. Any website styling or behaviour changes would be
made to the files in here.
Antora's real power is being able to generate content for multiple versions of
a document. In our case we have a version of the Cassandra documentation for
each release. Hence, Antora will allow us to generate the documents for each of
these versions. Given we need Antora to create the versioned documentation, we
may as well use it for the non-versioned content as well. The reason is reduce
the the number of tools we need to perform the HTML generation. As illustrated
above we can easily split the content from the styling for the non-versioned
documentation.
Let me know if what I've written makes sense or if I've missed something
crucial in your proposal. Let's catch up off-ticket when you have time to go
through the details and if it can be made simpler?
> New Cassandra website design, content and layout to work with Antora
> --------------------------------------------------------------------
>
> Key: CASSANDRA-16115
> URL: https://issues.apache.org/jira/browse/CASSANDRA-16115
> Project: Cassandra
> Issue Type: Task
> Components: Documentation/Website
> Reporter: Melissa Logan
> Assignee: Melissa Logan
> Priority: Normal
> Fix For: 4.0.x
>
> Attachments: Screen Shot 2020-09-03 at 09.48.53.png
>
>
> This task is related to CASSANDRA-16066 (Update and rework the
> cassandra-website material to work with Antora). The goal is to update the
> front-end of the C* website (design, IA and content) to work with Antora to
> help modernize the website as discussed on the [mailing
> list|https://www.mail-archive.com/[email protected]/msg15537.html].
> *Design Concepts:* A minimum of two homepage design concepts will be created
> and shared for input, which will help standardize a brand palette for C* and
> a design language for the site. This may include custom iconography and
> graphics. The chosen design language will be used to develop the remaining
> templates.
> *Template Design*: It's estimated that 7 template designs will be needed
> including the creation of several new pages:
> * Homepage template
> * Toplevel template - e.g. Community.
> * General template - Mostly textual with some images, e.g. Intro, Quickstart
> * “Library” template - A library of assets (links, downloads, logos etc)
> that are sortable by metadata, e.g Resources, or Kafka's Powered By page).
> * Blog landing template
> * Blog single template
> * Docs template
> *Website Content:* Along with new design will be a need for new or updated
> content to fit the new page layouts. The intention is to use as much as
> possible from existing content, and augment with new content where needed.
> *Template Development:* This includes the frontend development, such as any
> HTML markup to achieve designs. HTML would be crafted so as to preserve any
> backend/API calls, such that content is pulled in as designed. The majority
> of the frontend work would come in the form of crafting CSS to bring the
> designs to life, plus any minor Javascript to add subtle delights to key
> pages.
> *Style Guide*: Once all is complete, a Style Guide be added to GitHub for
> contributors.
> The [cassandra-website|https://github.com/apache/cassandra-website]
> repository would need to be modified. Specific changes to be determined.
>
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
