I think this is a great idea.
The current website consists of a single HTML page, which indeed makes
it more difficult to maintain, contribute to and link to content.
I'm also in favor of using a static site generator to generate HTML out
of Markdown. Hugo seems to be one of the most (if not the most) popular
ones around, but I personally haven't used it yet.
Are there examples of other Apache sites using Hugo?
The documentation has already been converted to Markdown by Joe Fagan
and Josh Innis. Currently, Sphinx
(https://www.sphinx-doc.org/en/master/) is used to generate HTML pages.
In the current setup, multiple versions of the documentation can be
generated, which is not yet possible with Hugo as far as I could find
(https://github.com/google/docsy/issues/114).
Best regards,
Pieterjan
On 10.02.22 15:02, Nicholas Sorrell wrote:
All,
I wanted to propose that we overhaul the website
(https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fapache%2Fincubator-age-website&data=04%7C01%7CPieterjan.DePotter%40ugent.be%7Cffb7ffea9a1945fe276108d9ec9df500%7Cd7811cdeecef496c8f91a1786241b99c%7C1%7C0%7C637800986184870331%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&sdata=e9J1J1i%2BIcLVZ2W2KsWvwSQTOEHg%2FFQb0J2rnhPNgqI%3D&reserved=0)
to make it easier to contribute to, easier to modify, more extensible, more accessible,
and easier to optimize for searching and performance.
When I created the site, there were a couple of a factors in the design
decisions:
Time - we were racing to get something done and presentable before a conference the team
was presenting at. This meant creating a site with minimal "flare."
Libraries - when we built the site way back then, we weren't sure what 3rd
party libraries we could incorporate. We weren't sure if Apache had rules
limiting the use of them, so we chose to use no libraries. This also impacted
the site (negatively in my opinion).
Since then, we've seen other Apache sites using 3rd party libs and we now have
time to redesign the site. I propose that we redesign the site using Hugo. This
gives us the ability to utilize Markdown, which is much more accessible for
contributors, and also offers more extensibility through themes and plugins. I
think it could also make the process of generating the docs easier but I
haven't fully investigated that.
Another negative about the current website is linking to content. Because of the way that
I've utilized anchors to show/hide content, this keeps the URL slug the same no matter
where you go, which makes it difficult to share, for example, a "Getting
Started" page with someone.
So in summary, here are the potential benefits I see:
+ easier to modify: because the content is written in markdown, it is easier
for people change existing pages without knowledge of HTML/CSS/JS
+ easier to contribute: again, because we will use markdown for content, it is
easier for people to contribute new content
+ more extensible: because Hugo has a large ecosystem, we can tap into the work
of others
+ more accessible: this redesign will also have a focus on accessibility so
all users can engage with the content
+ better SEO: designing with SEO in mind so that users can find out about AGE
is important
+ possibly easier to build docs: right now we're using a Github workflow to
generate these, and we could possibly wrap all of this into a single step of
static site generation with Hugo
+ possible blog: another important aspect of both SEO and community engagement
is a blog, which can show examples and use cases of AGE's new functionality
with each release. The approval process for blog posts should probably part of
a separate conversation.
Looking forward to hearing the community's thoughts.
Thanks,
Nick Sorrell
