[
https://issues.apache.org/jira/browse/CASSANDRA-16115?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17217055#comment-17217055
]
Melissa Logan commented on CASSANDRA-16115:
-------------------------------------------
As the team dug into using Antora for the main website (in addition to docs),
it became clear that it would be far simpler to use a static site generator
(SSG) to vastly reduce complexity. Captured thoughts about the recommendation
below and would appreciate feedback. Flagging in particular for [~mck],
[~polandll], [~Anthony Grasso].
Recommendation
Since one of the benefits of a static site generator (SSG) is that content
folks can manage content with markdown instead of HTML, we looked at *markdown
-> HTML* parsers and found some popular Github repos.
The attached files use one called “Marked”. In order to run the attached files,
you need a local server running on your computer (since the index.html file
needs to fetch the test.md file). For folks who don’t have a local server or
aren’t familiar with running one, you can also view the link below.
The link itself conveys very simply what the attached files do: namely, all
content would be added to the “test.md” file, while all the HTML/JS would be
done in the .html file for layout, interactions, etc. This allows for a
separation of concerns so developers can modify layout/interaction in the .html
files, while content folks can do their thing in the .md file, just like how
Antora/Jekyll work (but without the large overhead/complexity those SSR
platforms bring).
One illustration of how it could work is that the homepage would have a
corresponding .md file for each section. The homepage-hero.md file, for
example, would have all content that appears at the top of the page. The “What
is Apache Cassandra” section with the nine icons would be another markdown file
where content could be modified.
The idea of having separate files is for to better separate what markdown needs
to be parsed for what section.
Done this way, we eliminate the setup, overhead, complexity, and build
processes that SSGs require. We instead would simply have .html files the
developers work with, and .md files the content folks work with.
If needed, we can stand up a simple remote server (like
[cassandra.traverstodd.com|http://cassandra.traverstodd.com/]) where we’d push
these two attached files, so that it can be seen in action.
[Demo link
here|https://marked.js.org/demo/?text=Marked%20-%20Markdown%20Parser%0A%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%3D%0A%0A%5BMarked%5D%20lets%20you%20convert%20%5BMarkdown%5D%20into%20HTML.%20%20Markdown%20is%20a%20simple%20text%20format%20whose%20goal%20is%20to%20be%20very%20easy%20to%20read%20and%20write%2C%20even%20when%20not%20converted%20to%20HTML.%20%20This%20demo%20page%20will%20let%20you%20type%20anything%20you%20like%20and%20see%20how%20it%20gets%20converted.%20%20Live.%20%20No%20more%20waiting%20around.%0A%0AHow%20To%20Use%20The%20Demo%0A-------------------%0A%0A1.%20Type%20in%20stuff%20on%20the%20left.%0A2.%20See%20the%20live%20updates%20on%20the%20right.%0A%0AThat%27s%20it.%20%20Pretty%20simple.%20%20There%27s%20also%20a%20drop-down%20option%20in%20the%20upper%20right%20to%20switch%20between%20various%20views%3A%0A%0A-%20**Preview%3A**%20%20A%20live%20display%20of%20the%20generated%20HTML%20as%20it%20would%20render%20in%20a%20browser.%0A-%20**HTML%20Source%3A**%20%20The%20generated%20HTML%20before%20your%20browser%20makes%20it%20pretty.%0A-%20**Lexer%20Data%3A**%20%20What%20%5Bmarked%5D%20uses%20internally%2C%20in%20case%20you%20like%20gory%20stuff%20like%20this.%0A-%20**Quick%20Reference%3A**%20%20A%20brief%20run-down%20of%20how%20to%20format%20things%20using%20markdown.%0A%0AWhy%20Markdown%3F%0A-------------%0A%0AIt%27s%20easy.%20%20It%27s%20not%20overly%20bloated%2C%20unlike%20HTML.%20%20Also%2C%20as%20the%20creator%20of%20%5Bmarkdown%5D%20says%2C%0A%0A%3E%20The%20overriding%20design%20goal%20for%20Markdown%27s%0A%3E%20formatting%20syntax%20is%20to%20make%20it%20as%20readable%0A%3E%20as%20possible.%20The%20idea%20is%20that%20a%0A%3E%20Markdown-formatted%20document%20should%20be%0A%3E%20publishable%20as-is%2C%20as%20plain%20text%2C%20without%0A%3E%20looking%20like%20it%27s%20been%20marked%20up%20with%20tags%0A%3E%20or%20formatting%20instructions.%0A%0AReady%20to%20start%20writing%3F%20%20Either%20start%20changing%20stuff%20on%20the%20left%20or%0A%5Bclear%20everything%5D(%2Fdemo%2F%3Ftext%3D)%20with%20a%20simple%20click.%0A%0A%5BMarked%5D%3A%20https%3A%2F%2Fgithub.com%2Fmarkedjs%2Fmarked%2F%0A%5BMarkdown%5D%3A%20http%3A%2F%2Fdaringfireball.net%2Fprojects%2Fmarkdown%2F%0A&options=&version=master].
> 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/dev@cassandra.apache.org/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: commits-unsubscr...@cassandra.apache.org
For additional commands, e-mail: commits-h...@cassandra.apache.org
