Redesigning conda-forge.org

[jaimergp]

Hello conda-forge!

We now have a new website prototype available at https://cf-infra-docs.netlify.app/. This mostly showcases the work @asmitbm did during his GSoC internship last summer, but you can also see how some documentation would look like there, or the blog.

This prototype is based on the Docusaurus framework, which uses a React, Node and Markdown.

In parallel, @afshin has been working on a new status page in this PR. A preview is also available.

I've also done some work studying potential migration strategies for our documentation. I don't want to lose the valuable git history by converting all the RST over to MD, so instead I suggest the following strategy:

1. Keep Sphinx around for now, but have it render to Markdown instead of HTML (via sphinx-markdown-builder).
2. Have Docusaurus take those Markdown documents and render the HTML with them.
3. Whenever needed, slowly migrate RST content to native MD in Docusaurus. This might never happen though, if we feel that Sphinx's linking abilities are too important. We can also end up in a hybrid situation, with some narrative documentation being rendered natively in Docusaurus, and some more reference-y docs done in Sphinx.

I have a demo of how this strategy works in Quansight-Labs/cf-infra-docs#14. Plus the corresponding preview.

---

Migration steps

This is my proposed timeline:

• 1. Implement Docusaurus in this repository, starting with the frontpage only. Ensure there are no broken links - conda-forge.org redesign: Homepage #2050
• 2. Migrate the blog (the preview site already has it), while keeping git credits around.
• 3. Migrate feedstock-outputs
  • Frontend: Reimplement /feedstock-outputs in Docusaurus #2064
  • Backend should produce JSON: add json output feedstock-outputs#58
• 4. Migrate the Sphinx documentation as discussed above.
  • Migrate announcements to a new blog-like instance - Migrate announcements page to news/ #2057
  • Migrate most of the Orga content to a new community docs-like instance: Move (most of) /docs/orga/ under /community #2093
  • Expose the rest of the documentation as is (in the future, we'll do more work to reorganise some bits). Render Sphinx /docs in docusaurus #2077
• 5. Migrate the status page:
  • Status Dashboard #2090
  • Remove site and workflows, update README status#172
  • Dark mode: Status Dashboard #2090 (comment) & Status Dashboard #2090 (comment)
  • UX in migration details: Status Dashboard #2090 (comment)
• 6. Add more visibility to the Miniforge website, possibly matching the new website style.
• Other items:
  • Search with Algolia Render Sphinx /docs in docusaurus #2077
  • Statistics with Goatcounter Render Sphinx /docs in docusaurus #2077

Thoughts, @conda-forge/core?

[asmitbm]

Happy to get feedback from the community :D

[jaimergp]

Some more updates:

• Asmit successfully finished its GSoC internship in September 🥳
• The frontpage looks like this.
• I've updated the issue description with our next steps.

[jakirkham]

Thanks Jaime! 🙏

What level of feedback are you looking for at this stage?

[jaimergp]

Thanks @jakirkham. Not much. Basically if anyone feels strongly about it and prefers we do it in a different way. I'll take silence as a go-ahead but it'd be better to have explicit support :D

[jakirkham]

Sorry let me clarify.

Is this meant as a high-level rough sketch of what you would like to do? If so, then comments would be about colors, layout, etc

Or is this meant to go as-is? If so, comments would focus on missing links, typos, etc.

Does that make more sense? Which of those are you going for? Or something else entirely?

[jaimergp]

Ah ok, thanks for clarifying.

The design is mostly settled now. We didn't get feedback back then (see hidden comments) so we had to assume folks were ok with our choices. We might fine tune some elements (i.e. the different states of the links), though, so if you have feedback in that direction, of course it's welcome. The currently proposed frontpage follows the conda-forge.org frontpage almost 1:1 in content, although it has been redesigned.

That said, I'd like to focus on the transition to a new framework now without losing information in the way (no broken links, all functionality in place, etc). Once we are using the new framework we can easily submit PRs to adjust things.

Let me know if you need more details, happy to provide them. It looks like we could start with a PR for point (1), right?

[beckermr]

The colors are not to my liking. Can we work on them?

[beckermr]

I think we chatted about the colors a few weeks ago?

[beckermr]

suggestions from @wolfv on colors

• https://coolors.co/edf0da-f0dfad-8f2d56-ff6542-218380
• https://coolors.co/1be7ff-6eeb83-e4ff1a-ff6542-e8aa14

[jaimergp]

Hello @conda-forge/core, @isabela-pf has shared three palettes I'm presenting below. Still preliminary and might need a few touches here and there, but these are ready for comments.

In Isabela's words:

I tried to keep to warmer colors to continue the "forge" feeling while avoiding conda green or the red, orange, and yellows that tend to give contrast issues. The blues have a little more hot-flame yellow in them, and the magenta is a little more ember-like.

See them in action:

• Teal live preview (Try a teal theme Quansight-Labs/cf-infra-docs#16)
• Cyan live preview (Implement cyan theme Quansight-Labs/cf-infra-docs#17)
• Magenta live preview (Add a magenta theme Quansight-Labs/cf-infra-docs#18)

Try the dark/light theme switcher in the top bar to try both modes!

If you ask me for my preferences, I really like the magenta, then cyan, and finally teal, but I would be happy with all of them. Please let us know if you have a preference!

[hmaarrfk]

All 3 are beautiful in my mind ;)

[h-vetinari]

I agree that they all look great! Personally, I think the magenta one is the most aggressive, contrast-wise, so my order of preference is:

1. teal
2. cyan
3. magenta

[jaimergp]

Cool! Yes, that matches what I'm seeing in an informal survey in the Quansight Slack:

• Teal: 11
• Cyan: 5
• Magenta: 4

[jakirkham]

Would be ok with Teal or Cyan. Magenta is too close to the red we wanted to move away from. Also is there an optical illusion at play or does Cyan have a gradient across it?

---

For completeness, am writing down notes from the previous core meeting when we reviewed the new webpage together:

• Side bar menu - This is nice! Could it also float? So following the user down the page as they scroll.
• Links - 1st or 2nd layer in docs seem to have broken links (based on a handful I tried). Might be worth running linkcheck or similar to just validate all links are working.
• Status page
  • Current progress bars show done and everything else
    • This loses some gradation that the current progress bars have (done, in-pr, awaiting-pr, not-solvable, awaiting-parents, bot-error)
    • Ideally would keep at least (done, in-pr, everything else)
    • Maybe in-pr could be gray (instead of black or white) or something to call out it is in-between done and awaiting
  • Anchors appear to be missing. In the current status page one can anchor to the Arch migration, Long-term migrations, or some specific migration. This appears to not be available in the current status page. It would be nice to include anchors so we can point people to more specific migrations or other details.

[jaimergp]

Also is there an optical illusion at play or does Cyan have a gradient across it?

All of them have a gradient in the frontpage :D

For completeness, am writing down notes from the previous core meeting when we reviewed the new webpage together

Noted!

[jaimergp]

I've merged the teal theme with some adjustments. I'll create issues for the pending tasks.

Side bar menu - This is nice! Could it also float? So following the user down the page as they scroll.

I think it does already. It's more noticeable in long docu pages, like this one. In short pages where the footer is already showing up, then it resumes the scrolling.

[jaimergp]

New homepage is live!

[jaimergp]

feedstock-outputs has lost its theming 😬 Still works, but it has reverted to factory bootstrap and the top bar is now partially hidden by the header. I can work on a new iteration that matches the new homepage, or simply change the link to https://conda-metadata-app.streamlit.app/. Thoughts?

[beckermr]

I think all we need to do is to move the CSS or w/e to the right path?

[beckermr]

paths are in this file: https://github.com/conda-forge/feedstock-outputs/blob/gh-pages/index.html

We can change them there too.

[asmitbm]

I can help design that page? My idea earlier was to design a card with name and its version as seen on conda metadata site. Thoughts?

[beckermr]

Sure! The search integration was done by hand so we'd need to ensure that translates.

[jaimergp]

The primary usage of this page is to locate which feedstocks are generating a given package. So as an user I'd like to:

• Search by package name and obtain the feedstock name(s) producing it. The relationship must be clear in the UI. I should be able to quickly understand that "package A" is produced by "feedstock A". However, when I search for "package B" I will see that it can be generated by both "feedstock B1" and "feedstock B2".
• Autocomplete on the search bar would be awesome. Alternatively, the "filter as I type" behaviour is also good.

Note we have like 20k feedstocks so take into account the amount of HTML that needs to be rendered per item. It can get heavy. To that end, I think a simple table would be enough.

While I love the info-rich cards, I don't think we can fetch the remote metadata in a performant way to display things like number of downloads or things like that, so let's stick to the metadata that it's provided in feedstock-outputs for now (package name, feedstock name).

[jaimergp]

Status update:

• After migrating the homepage, we have now migrated the blog too. This supersedes the previous system deployed from conda-forge/blog (now archived). Contributing a blog post is as simple as sending a PR in this repo with a new markdown file under blog/.

My next item will be the announcements. Right now, this is a single RST page under the user/ docs. Some extra machinery has been added to generate the RSS feed. My naive migration plan would be to:

1. Split the single announcements page into one post per announcement.
2. Create a new "blog-like" instance under news/. This will automatically generate a RSS feed. ¹
3. Redirect /docs/user/announcements.html to /news/. Same for the RSS feed.

However, I'm also tempted to merge the announcements into the current blog itself, and simply label each post type differently. Announcements would have a news tag, and the blog posts could be labeled as blog or post. Not sure if simpler or more intricate, but it would remove the need to differentiate between announcements and blog posts. It's not like we have a lot of throughput anyway (specially in the last year).

---

This is how it currently looks like in my local prototype:

A single announcement:

All announcements:

The archive page:

Thoughts?

Footnotes

1. Note: the current Docusaurus blog plugin doesn't allow for much sidebar customization, so we won't be able to have the dates in the sidebar links, but this is being worked on. ↩

[jaimergp]

More updates:

• Announcements merged to /news
• Feedstock-outputs merged to /packages

Coming next: community section.

[jaimergp]

Latest updates:

• /docs is rendered with Docusaurus now (Sphinx behind the scenes)
• /search configured with algolia
• Non-invasive statistics configured with GoatCounter
• Netlify previews in each PR

[jaimergp]

Latest updates:

• All Sphinx content moved to Docusaurus
• conda-metadata-app links added to /packages
• New status dashboard PR available at Status Dashboard #2090 - feedback welcome!

[jaimergp]

Latest updates:

• New /status dashboard now live!

[jakirkham]

Nice work! 👏

Submitted a couple PRs tweaking little things in the status page. Overall find it very clean and nice to read/explore! 🤩

[jakirkham]

In terms of the blog/announcement point above, would suggest we keep them separate. They serve different purposes and expect it is easier for user to consume what they want if we split them out

As to blogpost activity, think we can pick this up. There are a number of things over the last year (or even past few months), which would benefit from a blogpost (website improvements, CI improvements, .conda packages, CUDA 12, etc.). We probably just need to get in the habit of cranking through these