conda.org Implementation

--- tags: Implementation --- # conda.org Implementation The Infrastructure Team is responsible for deciding on what technologies are chosen to support the conda.org website. They will also be responsible for setting up the build and CI infrastructure for the site. Finally (?) the T&I team will be responsible for writing the code to support populating [index/feed](https://hackmd.io/ljHIgPXqQuimhTmQOPeh9g#Feed--Index-pages) and [directory](https://hackmd.io/ljHIgPXqQuimhTmQOPeh9g#Directories) pages. Slack Channel: [#conda-doct-org-implementation](https://conda.slack.com/archives/C03V5P9KSQ7) # Design decisions - Preliminary platform choice: [Docusaurus](https://docusaurus.io/) # Goals These [project-wide goals](https://hackmd.io/MyRHr6w9RViAyNRfifkuUg) drive our technology and infrastructure decisions: * **Make it easy for community members and newcomers to find conda-related information, and to get started in the conda ecosystem** * **Make it easy for community members to contribute content** Example implications of these goals are * Favoring content tools/choices that are easier, rather than harder to use. For example, * Supporting Markdown for content, rather than requiring fluency in HTML and Javascript. * Using platforms that are already familiar to a large part of our contributor base (such as GitHub), enabling platform-savvy contributors to make direct contributions. * Offering news, events, open positions, blogs, etc submissions that allow people to either * submit text and metadata for these items to be hosted in conda.org, or * submit metadata for items hosted elsewhere so we can link to them from conda.org * Supporting intuitive search and navigation interfaces. # Feed / Index pages Implementation [Feeds](https://hackmd.io/ljHIgPXqQuimhTmQOPeh9g#Feed--Index-pages) are things like News, or Blog, or Events, or any other type of common content that we will want people to add content too. Let's explore News as an example. * Have a home/index page for news * Index page lists news items in reverse chronological order. * Index page is programmatically generated from individual news files * These all have metadata at the top. This is what shows up on the index page * Includes date posted, headline, maybe an image? * The actual news item could be in the page in conda.org, or it could be linked to an external site from a metadata entry. # Search **See the [Site Search discussion](https://hackmd.io/HBuhoWgcSgiey1zE_mMnbg).** We at least want a search that explores conda.org. Dave C argues we actually want a lot more than that: we want a search that searches the entire ecosystem (a set of conda-centric sites) and then returns search results in a tabbed ([for example](https://galaxyproject.org/search/?q=conda#gsc.tab=0&gsc.q=conda&gsc.page=1)) interface. Google Custom search can be used for this. Ken Odegard: Many of the SSG include built in search engines, I’m sure they can be extended relatively easily with additional domains. # Platform Choices ## Requirements ### Bare Minimum What is the bare minimum we need this website to support? * GitHub * content has to be in a public repo in GitHub, and it should be in the conda organization on GitHub. The minimum requirement to contribute should be "You need to have a minimal understanding of GitHub." * Markdown * Markdown is widely known and supported. Most content should be in Markdown. * Accessibility! ### Maybe more? What else do we need? * Mobile support: * [Bootstrap](https://getbootstrap.com/)? * Many people know Bootstrap, and it would help us address the big screen / small screen divide. * Ken Odegard: other bootstrapping libraries of note: * https://shoelace.style/ * https://tailwindcss.com/ * Cool icons: * [Font-Awesome](https://fontawesome.com/)? * Widely used and widely useful for making pages more interesting. * interactive tabular data? * [Datatables](https://datatables.net/)? * Useful for tabular data presentation. May not be state of the art though. * Other options? * We are after all embedded in several key visualization efforts * Tagging? * Dave C is a big fan of Tagging. * For example: Does a page benefit educators? Then tag it with the education tag, and then list those items somewhere on our "Educators" page. * What else? ## Website Framework? Static Site Generators are the current technology of choice for generating community web sites. They also enable us to use GitHub Pages, which means we would not have to support and pay for a running server behind the site. That could all be provided by GitHub. Here are some possibilities for frameworks **Jamstack** * Recommended by Dannon Baker at Dave C's previous job. Dannon's opinion carries serious weight with Dave, but Dannon does not have the big picture. * Jannis votes -1 on this out of concerns for long-term maintainability when using a commercial 3rd party framework and service (netlify cms, netlify, react). Jannis's opinion carries serious weight with the world and he does have the whole picture. * From Jannis: As a side note, I’m ecstatic about the UX improvements of these platforms, but our goal IMO is to build a site that runs on a shoestring and does not require a lot of ramp up and running costs. **GitHub Pages** (and see below for specific options) * Jannis favors building on this and completely avoiding hosting our own web server. * If this requires Jekyll, Dave's head will explode clean off his body. * Jannis: Nope, it hasn’t required Jekyll for a while now and GitHub even has just made the announcement to deprecate the old GitHub Pages workflow in favor of [supporting GitHub Actions natively](https://github.blog/changelog/2022-07-27-github-pages-custom-github-actions-workflows-beta/). So no weight gh-pages branch needed anymore! * [This page says we have many choices](https://github.com/collections/static-site-generators) * Including Hugo, Eleventy, vuepress, hexo, Gatsby, hexo, next.js, Pelican * All of those have seen recent development and releases. * From Jannis: The recent development of them isn’t a big concern, but how well they are integrated in the ecosystem that we’re part of. We’d basically have to start at a clean slate in user experience and best practices and would need to come up with our own patterns. IMO that’s not worth the gain. **Gatsby** * Named by Kent Pribbernow as a standout. **Hexo** * Also named by Kent P as a standout. **Sphinx / ReadTheDocs** * This is used by many of Anaconda's open source projects. * But it is a much stronger proposal for code documentation, and we could use it for that. * Jannis: Strong favor for this to reduce overhead of learning another tool, lower barrier of entry, given the massive lack of frontend people/designers in the community. With the [MyST](https://myst-parser.readthedocs.io/en/latest/) project it has become trivial to use Markdown instead of reStructeredText (the default for Sphinx) as markup language and it has been widely adopted by Scientific community projects, e.g. https://numpy.org/doc/stable/ * Jannis: A Sphinx extension called [ablog](https://ablog.readthedocs.io) that helps maintain blogposts has added support for MyST as well: example https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/ablog.html * Jannis: I’ve been impressed by the PyData Sphinx theme and it’s flexibility to design websites using Sphinx that are not beholding to weird syntax, e.g. https://pydata-sphinx-theme.readthedocs.io/en/latest/index.html Combined with a slew of extensions from the same team in the PyData organization (e.g. sphinx-design) I think this is a compelling way to bootstrap a static website. * Ken Odegard: While I agree this would be a lower learning barrier I really don’t think this is suitable for some of the long term aspirations we have for the site. The fact that we need multiple extensions to get Sphinx docs to look non-docs makes it feel like more trouble than a benefit (what happens the day the extensions are no longer maintained). The site really needs to be a page that showcases conda, not something that looks like documentation. Ultimately I think what we want from Sphinx/RTD is the flexibility of writing in MD/RST which is a reasonable requirement. **Docusaurus on Netlify** (added by Jaime) * [Docusaurus](https://docusaurus.io/) has been recommended by Tania, given the strengths of this platform: we need both a site and a blog, which docusaurus has been designed for with a consistent UI/UX style. * Docusaurus relies on React for the frontend, but it’s a static site generator with heavy reliance on Markdown for content. Their [showcase](https://docusaurus.io/showcase) page is really beautiful. * [They deploy on Netlify](https://www.nebari.dev/), thanks to the open-source program they offer. Netlify offers PR previews which are very convenient.