search

ansible-community / community-topics

[Moved to Ansible Forum] Discussions for Ansible Community Meetings
https://docs.ansible.com/ansible/devel/community/steering/community_steering_committee.html#community-topics-triage
GNU General Public License v3.0
35 stars 9 forks source link

[associated vote ended on 2023-03-30] Static site generator for the Ansible community web presence #210

Closed oraNod closed 1 year ago

oraNod commented 1 year ago

Summary

The Ansible community is requested to provide input on requirements and options for a static site generator that will create a new Ansible community site and Ansible community documentation navigation should the Ansible community be in favour of those efforts.

Additional Information

Here is the initial list of requirements and things that would be nice to have. We can evaluate SSG options against this list:

Requirements:

Nice to have:

oraNod commented 1 year ago

Options for static site generators:

leogallego commented 1 year ago

@oraNod is the "web ui for content generation" included in the "cms" concept? I would like to add that to the nice-to-have if possible!

mariolenz commented 1 year ago

I don't know anything about static site generators... but doesn't antsibull-docs already use sphinx? If it fulfills the requirements (and maybe even the nice-to-haves) maybe that would be a reason to use it for the new Ansible community site?

Just an idea. As I've said, this isn't really my area of expertise.

gotmax23 commented 1 year ago

Hugo is written in Go instead of Python, but it's also a good choice and has a strong community surrounding it.

gotmax23 commented 1 year ago

I don't think mkdocs or Sphinx are good choices for a landing page. They're meant for documentation, and we already have a docsite.

mscherer commented 1 year ago

As it was asked on the chat, I kinda feel I can give some opinions here (and I try to keep myself out of tooling discussion, because obviously, everybody but me is always wrong :p ) .

My team at RH had to deal with SSG in the past 7 years, and I also evaluated them myself for personal projects, so my perspective is more from deployment side than designer side.

I think extensibility can be a trap. I know there is always tradeoff on features vs maintenability, and having plugins/modules/whatever is a way to solve that tension. However, my experience with Middleman (or Wordpress for that matter) is that plugins tend to get unmaintained, and cause troubles down the line. SSG also tend to get newer release, some changing their internal, resulting in breakage in plugins. Given SSG with plugins also tend to be written in dynamic languages, there is usually no clear interface or proper API, and there isn't a good curated marketplace like we have with linux distro.

So I would suggest, if there is a need for plugins, to treat them as proper software projects (eg, separate repo, CI, etc), and be evaluated as such (and the same caution to creating your own). In a ideal world, you want to avoid code as much as possible.

Another lesson I learned is that it can be nice to have a CI and tests for a website. For example, I use zola for my personal projects, and I stumbled upon a few issues upon update that were silently breaking the site and my templates (I tracked down to a refactoring in zola, and I was able to quickly correct, but I didn't detect at first ).

I tend to be partial toward static binary for SSG because 1) they are fast 2) they are easier to install/deploy/maintain, both desirable properties to ease contributions (and ease sysadmin life, which, as a sysadmin, is a high priority).

However, that tend to come with 1) no extensibility (again, a plus on my book)
2) no jinja (at best, a jinja-like system), so I suspect it might be a big "no" due to that.

When I say fast, that's around 10 seconds from commit being pushed to page on the web, for stage + prod, vs 4 to 5 minutes of a site of the same complexity based on middleman (due to the dynamic nature meaning we have to install plugins at each run ).

And static binary also help a lot for the versioning requirements, since you can just keep the old binary to build the old branch.

One approach that I tried to push for Fedora is that for some websites, it is also ok to treat them as disposable. Each time we had a new community manager for a project in my team, they changed the whole website, usually changing the stack (going from dynamic to static, or static to dynamic, from plain html to hugo to middleman to nico, etc). So there was no need to plan for long term support, since in 3 to 4 years time, everything would be throw away anyway.

Now, that's not the case for documentation, but for a isolated website (like a event one), treating the website as a temporary one where one can experiment with a different stack can be useful to get experience. I wrote about that idea on Fedora discourse, if you want to see the discussion (and others points made by others). The Fedora folks who work on that would surely be happy to discuss their experience.

So maybe not unifying docs + community + others can be used to get more experience with various SSGs stacks and avoid long term headaches of having too much requirements on 1 single stack.

oraNod commented 1 year ago

I don't know anything about static site generators... but doesn't antsibull-docs already use sphinx? If it fulfills the requirements (and maybe even the nice-to-haves) maybe that would be a reason to use it for the new Ansible community site?

Just an idea. As I've said, this isn't really my area of expertise.

@mariolenz Yes I think Sphinx is a pretty solid choice because it has a lot of mindshare/adoption already. I'm not 100% on how well it does general sites, even though I'm pretty sure it has that capability.

oraNod commented 1 year ago

Hugo is written in Go instead of Python, but it's also a good choice and has a strong community surrounding it.

@gotmax23 I can add Hugo to the list. I don't think it will have the "mindshare" with the community though. For instance I didn't include Jekyll as an SSG option because Ruby just wouldn't be a popular choice.

oraNod commented 1 year ago

@mscherer Thank you so much for those valuable insights. I feel like there are a lot of things we can learn from the Fedora community here and you've raised a lot of points already that I'm not sure we've fully considered. Let me ask folks on the Ansible community team here but I think we should definitely meet with some of the Fedora folks about the experiences so we can bring those things over to this effort.

ssbarnea commented 1 year ago

@gotmax23 Take a look at Material landing page from https://squidfunk.github.io/mkdocs-material/ which does not really look as a "documentation landing" page. AFAIK, mkdocs-material can be used to also create custom landing pages.

felixfontein commented 1 year ago

I personally like Nikola a lot (https://github.com/getnikola/nikola/), I've been using it for a long time now (almost as long as Ansible) and it worked well for my personal homepages and blogs.

Simliar to ansible-core it has a small core that is extensible, and comes with plugins for everything - most things you need are already bundled, and then there's also https://themes.getnikola.com/ for more themes and https://plugins.getnikola.com/ for more plugins.

Nikola has been very stable in the several past years, so no big breaking changes are to be expected most of the time even if we write our own plugins.

(Disclaimer: I've contributed a lot to Nikola, and I think I still have commit rights.)

Edit: some more points added to the initial post:

maxamillion commented 1 year ago

+1 @felixfontein - I ironically had suggested Pelican purely because it seems to have the largest community around it, but I personally use Nikola for my site (that admittedly doesn't change often) and I've been a very happy user for many years.

oraNod commented 1 year ago

Removing Hyde from the list of potential SSGs after discussion with @leogallego who proposed it. Hyde is not actively maintained so we shouldn't really consider it a viable option.

oraNod commented 1 year ago

@maxamillion I've been looking at the Pelican option and have come up with this assessment against that checklist. I think you suggested Pelican so wanted to get your thoughts.

Pelican

Pelican is a great tool but maybe not as widely used as other options and doesn't really have a great selection of themes.

Requirements:

Nice to have:

oraNod commented 1 year ago

@felixfontein I've removed analytics and discourse integration from the list of nice to haves. Those probably are things that should come later.

oraNod commented 1 year ago

@gotmax23 Here is an assessment on Hugo. Would you mind taking a look and seeing if there are any points you disagree with?

Hugo

Hugo is kind of the Ferrari of static site generators. It lets you build modern, SEO-friendly, and secure websites quickly and offers a lot of great features (like mermaidJS support). Hugo can build really great websites, like Manjaro Linux https://manjaro.org/ and LetsEncrypt https://letsencrypt.org/

On the other hand Hugo is written in Go and relies heavily on JavaScript. For the Ansible community site Hugo feels a bit like "outsider" technology that might present a barrier for engagement. Because the underlying tech stack is not the typical first choice for the Ansible community, Hugo would actually be a more complex option even though it offers a lot of flexibility and powerful tooling. That complexity could make it harder to change to a different static site generator after the community website starts to mature or for longer-term maintainability.

Requirements:

Nice to have:

oraNod commented 1 year ago

Sphinx

Sphinx is widely known for building documentation from RST source. It is not traditionally thought of as a static site generator although it can be used to create websites. One of the benefits of Sphinx as an SSG is being able to use intersphinx for linking across sites but this actually slows build time and can be resource intensive.

This most compelling point for Sphinx is that it is a very familiar tool for the Ansible community. At the same time there is some overhead to adapt Sphinx as a static site generator and it is probably a better choice to use MD with MyST than RST. There is a solid tutorial on that here: https://www.jetbrains.com/pycharm/guide/tutorials/sphinx_sites/

Requirements:

Nice to have:

oraNod commented 1 year ago

MkDocs

MkDocs seems like a mixed bag. MkDocs itself is simple and straightforward, although it does not seem to be under as much active dev as other options.

The real option under consideration here is the material theme for MkDocs. Even the Ansible community theme for MkDocs is based on the material theme. In this regard MkDocs feels like a constrained choice that might limit the ability to adapt and build different layouts. This is especially true considering the fact that, like Sphinx, MkDocs is intended more for documentation projects than full websites.

Requirements:

Easy to add custom styling: https://www.mkdocs.org/user-guide/customizing-your-theme/#using-the-docs_dir - For the material theme: https://squidfunk.github.io/mkdocs-material/customization/#additional-stylesheets

The Ansible community theme is built on the material theme and provides a good starting point but has a high overhead for customization, especially considering more complex formats and templates beyond a documentation project.

https://github.com/mkdocs/mkdocs - It looks like there are no commits since November. However the material theme has more active contributors than MkDocs itself: https://github.com/squidfunk/mkdocs-material

The Ansible community theme has one contributor at the moment (yay, Sorin!): https://github.com/ansible/mkdocs-ansible

Nice to have:

oraNod commented 1 year ago

Lektor

Lektor offers the ability to model content and explicitly define the structure of the website. In this way it is convenient for separating content from layout.

Lektor makes it easy to get a site up and running quickly but the general lack of themes and basic default styles necessitates more UX work than other static site generators.

Requirements:

Nice to have:

cybette commented 1 year ago

I don't have a strong preference on any of the above, partly because I don't have experience with them. I have used Middleman, Jekyll, and Hyde (in addition to Wordpress and Hubspot which are not SSGs) and dislike all of them :sweat_smile:

I might try out a couple of them over the weekend to get a feel, but I trust all you experts here to select one that's most suitable for the community's needs.

webknjaz commented 1 year ago

My personal preference is Lektor because I worked with it and it's heavily customizable. It was initially written by the creator of Jinja and Flask. It's a bit like a CMS really that generates content that can be served statically.

@oraNod

I'm not sure what you mean by these but IMO for this type of task, we don't really need to rely on third-party themes and would need to make our own.

  • [ ] Easily add custom css when required but low requirement for theme customization, built-in cross-browser compatibility and responsive design

There's plugins integrating stuff like webpack and scss — I imagine they take care of this. Although, I'd go for a CSS framework like Tailwind that effectively makes this requirement irrelevant.

  • [ ] Button to edit pages directly

Not sure what you mean by this. In local dev mode, there's an edit button that takes you to the admin view. I think it works regardless of the theme...

Looks like there's also a plugin for static search at https://github.com/rlaverde/lektor-static-search.

oraNod commented 1 year ago

@webknjaz Thanks! I agree Lektor is a great choice and I really like several aspects of it, especially the models. However I've started to wonder if it's the right tool for getting the Ansible community site off the ground. If it turns out that is not the case I think we should keep evaluating Lektor with a view to switching over if that serves any particular longer-term needs better.

I'm not sure what you mean by these but IMO for this type of task, we don't really need to rely on third-party themes and would need to make our own.

I agree to an extent but the community team has taken some lessons about ux from the prototype docsite. It's important that the initial effort have good ux from the very start. Until we get a bit more help with ux there is a need to be cautious and avoid too many design flaws.

samccann commented 1 year ago

@felixfontein - the bit about 'mindshare with the broader Ansible community' to me means - pick an SSG that multiple people in community would feel comfortable with and willing to assist in creating and maintaining the new website. This from the start is meant to be a community website for and by the Ansible community.

samccann commented 1 year ago

Coming at this as a novice and reading the discussion, seems Nikola and Lecktor both have that critical mindshare with community members and the important features we're looking for.

samccann commented 1 year ago

I ran an accessibility check on the lecktor and Nikola websites, just for fun. They both have similar number of identified issues and score overall... and both a better scores than Ansible.com today so.. taking that as win :-)

--and yep, realize our own website will have to take steps to be accessible, but thought it was an interesting datapoint anyway.

gotmax23 commented 1 year ago

A vote was started in https://github.com/ansible-community/community-topics/discussions/216 about whether to move forward with Nikola as the static site generator for the first iteration.

GregSutcliffe commented 1 year ago

Coming in late to this one, but I have no bombshells to drop :)

A couple of general comments first

As to the actual choice, reading through the comments, it seems like any of these could do the job, and we're down to personal preference. On that basis I could vote for Hugo (since I use that for my site) but I don't want to cause bikeshedding, so I'll jump on the Nikola train so that we can get started actually building this thing. It gets plus-points because (as an ex-physicist myself) Tesla is a personal hero anyway :)

samccann commented 1 year ago

Thanks everyone! Closing this now as the nikola scaffolding is in place with https://github.com/ansible-community/community-website/pull/28