Iced's website requirments

[AlistairKeiller]

rendered

Iced website outline

Summary

The goal of this RFC is to make a decision on which technology is best for Iced's website based on the goals and requirements for the website. This RFC details every requirement for the Iced website so that once we agree on the requirements, we can decide on the best technology for the website.

Requirements

• The website should support i18n
• The website should support a11y
• The website should support dark mode
  • The dark mode should default to the user's system preference and be overridable by the user
• The website should be navigable
  • Every action a user could reasonably take, e.g., going from the landing page to the contributor's page or from one guide to another, should be easily and clearly accessible within one click
• The guide should be searchable
  • The search should automatically index the guide
  • The search bar should suggest results interactively as the user types
  • The search bar should be accessible from any page
• The website should have a landing page
  • The landing page should explain what Iced is to someone who has never heard of it
  • The landing page should explain the reasons someone should use Iced
• The website should have a guide
  • The guide should be readable for someone with little experience with Rust and no experience with Iced
  • The guide should walk through the creation of some Iced examples
  • The guide should go through Iced's architecture and core concepts
  • The guide should be written in Markdown
    • The Markdown's code blocks should be rendered with syntax highlighting and a copy button
    • Headings should be rendered with a clickable item next to them that links to their corresponding anchor
    • The headings in a given page of Markdown should be displayed in an "On this page" sidebar
      • The headings in the "On this page" section should be clickable to jump to the corresponding section
      • The headings in the "On this page sections" should be highlighted to indicate the current section
• The website should have a showcase page
  • The showcase page should display all the projects using Iced
  • The showcase page should display Iced's examples
  • Each example should be shown with an image or gif, and a link to the project's source code
• The website should have a contributors page
  • The contributors page should display the GitHub profiles of all the people who have contributed to Iced in the order of GitHub's contribution ranking
• The website should have a roadmap page
• The website should have a 404 page
• The website should be free to host
• The website should be accessible to anyone from the domain iced.rs

Goals

These are like requirements, but they do not have a clear yes or no answer.

• The website should be responsive
  • The website should be mobile friendly
  • The website should be high DPI friendly
• The website should be performant
• The website should be easy to maintain
  • The website should minimize the codebase
    • The website should not rewrite and maintain a tool if another developer is already maintaining a tool that does the same thing
• The website should have accessible development
  • The website's development environment should be easy to install and run
  • The website should be written with tools that an average developer could quickly use, either by being familiar, easy to learn, or a mix of both
• The website should have a good DX
  • Changes to the code should interactively update in the browser
  • Features should be fast to write
• The website should have good SEO
• The website should look good ( subjective )
• The website should look consistent across pages ( subjective )
  • There should be a consistent color scheme across the website
  • As many components as possible should be reused across pages, like a navigation bar and search bar

Nice to have

These are here to decide between tools if all else is equal.

• The website's software stack should be open-source
• The website's software stack should be built with Rust

[yzn-h]

for hosting I recommend cloudflare pages

[yzn-h]

bevy's website is a good example to learn from.

[AlistairKeiller]

for hosting I recommend cloudflare pages

I do really like cloudflare pages. Due to a bug in their build image, Zola >0.14.0 does not work, which is frustrating, but I have used them to host this demo anyway for now with Zola = 0.14.0. This should be fixed soon ( cloudflare/pages-build-image#1 ).

bevy's website is a good example to learn from.

I agree there is a lot to like about bevy's website, and it can be a great source of information.

Ok, if there are no other comments about the requirements, then we can look at which options we want to compare based on the requirements. I think the two best options are Zola and VitePress. I have made a similar website in both Zola ( https://github.com/AlistairKeiller/iced-zola https://42f7eec7.iced-zola.pages.dev/ ) and Vitepress ( https://github.com/AlistairKeiller/iced-vitepress https://0d47a19f.iced-vitepress.pages.dev/ ) so we can compare them. Just a note, the guide is implemented in the Vitepress version but not in the Zola version because that is a lot of work and does not seem necessary for the comparison.

Does anyone have suggestions for contenders? Does everyone agree there are the best foot forward for Zola and VitePress?

[yzn-h]

Zola is faster it ships a smaller site

tests:
1- webpagetest (default settings)

Zola

Vitepress

2 - gtmetrix (3G Slow (750/500 Kbps, 250ms))

[AlistairKeiller]

That is very an interesting find. I thought Zola would perform marginally better, but I did not expect it to win this much because I thought VitePress was fairly optimized for a documentation generator. So ya, Zola clearly wins in performance, and obviously wins in the amount of Rust used in the codebase. Although I think this is still a worthwhile comparison to make because I think VitePress wins in DX and accessible development.

[yzn-h]

The difference is big because the test was done on weak devices and slow Internet
Any new device will not find these differences

[AlistairKeiller]

The other thing to note about the performance is that VitePress has a custom router that only loads the difference of pages on a page navigation, which makes page navigation feel more responsive. This may be possible in Zola with something like flamethrower, but it is extra work and dependencies which is why probably why I have not seen it done before.

[emann]

Regarding the showcase page, IMO its should really be split up into 3 sections:

• Examples - The example projects included in the iced repo - these are fairly basic "Here's some cool things you can do!" projects, likely also where the future tutorial projects will go
• Showcases - Exemplary projects made by the community, maybe sorted by number of stars on git?
  • These should be manually added/approved to make sure we have an image for them, and should be "exemplary" in the sense that they showcase the true extents of what iced can do, not just "I made a calculator" etc. Would also keep the list from getting too long. Maybe we don't want to do this so people don't feel bad if their project isn't good enough to make the list 😆
  • Since Iced is still a ways away from hitting 1.0, it would be nice if project showcases were grouped by the version of iced that they used. A lot can change between versions (and maybe some people are stuck on a specific version for various reasons) so it'd be nice to be able to just look at ones using the version you are using. Could be a manual process, but would be fairly easy to make a script to scrape the cargo.toml for what version they're using (I'd be willing to help out in this regard!)
• Community projects - Links to the iced github topic, the showcase thread in the repo and the showcase channel in the discord.

Also, it'd be extra effort but it'd be awesome if we had tags for certain "things" you can do with iced that you could search on - these could be scraped from github topics, but we may want more specific things e.g.

• Image Rendering
• Which rendering backend they use
• API interaction
• Hardware interaction
• Visualization
• Stage-based (app follows a strict flow through multiple pages)
• Menu based
  Probably a pipe dream, but would be super helpful for new users to be able to explore past the examples/tutorials provided in the repo and checkout how other people are doing specific things they want to do

[AlistairKeiller]

I agree with your organization of the website, and I would like to add adding the guide/documentation to the website like bevy's website. I don't really understand the second idea.

As for the technical side of making the site, I still have not made a full-blown comparison chart, but one of my biggest gripes with Zola is that be best way to manager CSS is SCSS or a static CSS file like Bulma, which is just can not be as powerful as an atomic CSS engine like Tailwind. This is why in my example website, as well as in many other Zola themes, they integrate Tailwind for Atomic CSS ( technically mine uses a clone because it is slightly easier to integrate ).

It seems like there is some support in discourse for my feature suggestion of adding a rust clone of Tailwind like railwind (getzola/zola#2060). That would address one of my largest gripes with Zola, and I think would make it a much more compelling platform to work with.