As Pieterjan said, Sphinx allows us to have documentation for each release, which is a useful feature to have and we should try and keep it. However, if we are creating a new website then one of the side goals for accessibility should be a consistent theme throughout the website. Does Hugo and Sphinx have overlapping theme templates that could allow us to have both?
On Thu, Feb 10, 2022 at 6:50 AM Pieterjan De Potter <pieterjan.depot...@ugent.be.invalid> wrote: > 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 > > > > >
