Merge pull request #2147 from jaimergp/website-announcement

.github/workflows/deploy.yml

@@ -53,6 +53,7 @@ jobs:
             --base "$(pwd)/build"
             --accept 100..399,401,403,429
             --exclude 'https://polys.me/?$'
+            --exclude 'https://conda-metadata-app.streamlit.app/?$'
             --exclude 'https://kb43fqob7u-dsn.algolia.net/'
             --exclude '.*/404.html/'
             --exclude '.*,.*'

docs/user/contributing.md

@@ -15,20 +15,47 @@ We encourage you to contribute to conda-forge. You can do so in several ways:
 - [Contribute new packages](../maintainer/adding_pkgs.md).
 - Help update and [maintain packages](../maintainer/updating_pkgs.md).
 - Suggest or implement improvements for our [infrastructure](../maintainer/infrastructure.md).
-- Help [improve the documentation](#improve-docs).
+- Help [improve the website and documentation](#improve-the-website).
 
 <a id="improve-docs"></a>
 
-<a id="improve-the-documentation"></a>
+## Improve the website
 
-## Improve the documentation
+The conda-forge website is version-controlled in the
+[conda-forge.github.io repository](https://github.com/conda-forge/conda-forge.github.io) on GitHub.
+It is built with [Docusaurus](https://docusaurus.io).
 
-The conda-forge documentation is version-controlled in the
-[conda-forge.github.io repository](https://github.com/conda-forge/conda-forge.github.io) on GitHub. The source
-text is stored in [the `docs/` subdirectory](https://github.com/conda-forge/conda-forge.github.io/tree/main/docs of this repository and
-is formatted using [Docusaurus' Markdown](https://docusaurus.io/docs/markdown-features).
+### Website repository structure
 
-<a id="editing-the-documentation-directly-through-github"></a>
+:::info MD, MDX and JSX
+While most of the content is written with
+[Docusaurus' Markdown](https://docusaurus.io/docs/markdown-features) (`*.md` files),
+some specific pages and sections include dynamic blocks (`*.mdx` files) or are straight JSX files
+(`*.jsx` files). This allows you to mix Markdown and JavaScript/React in the same document,
+depending on the file extension. In MDX mode, the parser is much stricter though.
+Read more about in the ["MDX and React" docs from Docusaurus](https://docusaurus.io/docs/markdown-features/react).
+:::
+
+#### Docs & Community
+
+- These two sections use [`plugin-content-docs`](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs).
+- The **Docs** section corresponds to the `/docs` directory. Most of the pages use regular Markdown
+  (`*.md`), but some are dynamic pages with some JavaScript (`*.mdx`).
+- The **Community** section comes from the `/community` directory.
+
+#### News & blog
+
+- These two sections use [`plugin-content-blog`](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog).
+- The **News** section comes from the `/news` directory.
+  It is considered a changelog of important changes in our infrastructure and packages.
+- The **Blog** section corresponds to the `/blog` directory.
+  It usually discusses important updates from the extended ecosystem.
+
+#### Standalone pages and sections
+
+- These rely on [`plugin-content-pages`](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-pages).
+- They can be simple Markdown pages or more elaborate React applications.
+- Find them under `/src/pages`. MDX and JSX pages will usually call components defined in `/src/components`.
 
 ### Editing the documentation directly through Github
 
@@ -38,8 +65,6 @@ will take you directly to a web-based editor for this very webpage. In
 general, the file corresponding to each page in the GitHub browser has a
 little pencil icon in its top-right corner that lets you open it up for editing.
 
-<a id="editing-the-documentation-locally"></a>
-
 ### Editing the documentation locally
 
 We are glad to know that you would like to contribute to the conda-forge documentation.
@@ -48,29 +73,37 @@ If you are new to the conda-forge community, follow the steps below to make your
 1. [Fork](https://help.github.com/articles/fork-a-repo/) the
    [conda-forge.github.io repository](https://github.com/conda-forge/conda-forge.github.io).
 2. Clone this fork onto your local machine:
-   - `git clone https://github.com/<your-username>/conda-forge.github.io.git`
-   - `cd conda-forge.github.io`
+   ```
+   git clone https://github.com/<your-username>/conda-forge.github.io.git
+   cd conda-forge.github.io
+   ```
 3. Create a new branch deriving from `main` to do your work:
-   - `git checkout -b <new-branch-name>`
+   ```
+   git checkout -b <new-branch-name>
+   ```
 4. Run the following commands:
-   - `conda env create -f ./.ci_scripts/environment.yml`
-   - `conda activate conda-forge-docs`
+   ```
+   conda env create -f ./.ci_scripts/environment.yml
+   ```
+   conda activate conda-forge-docs
 5. While writing your new documentation, you can use the live preview mode with:
    - `npm install` to make sure `node_modules` is up-to-date
-   - `npm run start` to start the live preview. Every time you save a file, the changes will be reflected instantaneously!
-6. Once ready, you can also check how the production build would look like with the command:
-   - `.ci_scripts/update_docs`
-     You can check the changes locally by opening the html files in `build/` or running:
-   - `python -m http.server --directory build/`
+   - `npm run start` to start the live preview. Every time you save a file, the changes will be reflected instantaneously.
+6. Once ready, you can also check how the production build would look like with the commands:
+   ```
+   .ci_scripts/update_docs
+   python -m http.server --directory build/
+   ```
 7. Add and commit your changes:
-   - `git add .`
-   - `git commit -m "your commit message"`
+   ```
+   git add .
+   git commit -m "your commit message"
+   ```
 8. Submit a [pull request](https://help.github.com/articles/about-pull-requests/) to the main repository proposing your changes.
+   The CI pipelines will include a PR preview on Netlify.
 
 Happy contributing!
 
-<a id="writing-guidelines"></a>
-
 ### Writing guidelines
 
 Some basic writing guidelines should be kept in mind before you start contributing:

news/2024-04-09-new-website.md

@@ -0,0 +1,48 @@
+# The new conda-forge.org
+
+As you might have noticed, for the last few months we have been changing different parts of the conda-forge.org website. Read more to learn more about what we changed, how it works and how to contribute.
+
+<!-- truncate -->
+
+## Old vs new
+
+The [old conda-forge.org](https://github.com/conda-forge/conda-forge.github.io/tree/1d3214c295a46a249434de4fcf48c6b8d747a07f) documentation was written with [Sphinx](https://www.sphinx-doc.org). Some extra extensions were responsible for the other parts of the website; e.g. the [blog](https://github.com/conda-forge/blog), the [RSS feed](https://github.com/conda-forge/conda-forge.github.io/tree/1d3214c295a46a249434de4fcf48c6b8d747a07f/newsfeed), the [frontpage](https://github.com/conda-forge/conda-forge.github.io/blob/1d3214c295a46a249434de4fcf48c6b8d747a07f/index.html.tmpl), [feedstock outputs](https://github.com/conda-forge/conda-forge.github.io/blob/1d3214c295a46a249434de4fcf48c6b8d747a07f/feedstock_outputs.html.tmpl), or the [status page](https://github.com/conda-forge/status/tree/bde62db0bc9de460f533d60ca6218604c3e42fa5/site).
+
+The new website has been rewritten using the [Docusaurus](https://docusaurus.io/) project. This allows us to have a single framework for all the sections of the site. There are some big differences if we compare the new site with the old one:
+
+- Sphinx was written in Python. Docusaurus uses the Node.js stack.
+- Most of our docs were written in RST. Docusaurus handles Markdown and MDX (Markdown + JSX).
+- Instead of generating static HTML from Jinja templates, we now prefer fetching the JSON payloads and render the relevant pages at build time (i.e. when we run `npm run build`) or at load time (when the user visits the website). This allows to have all the website rendering logic in the same repository with a unified theme, search engine and statistics.
+
+## What we have changed
+
+- The theme for the whole site is responsive, accessible, mobile friendly and supports dark/light modes. A style guide is available too.
+- The Status dashboard fetches data dynamically and provides detailed views for each migration.
+- The Packages section lists latest updates in addition to mapping packages to feedstocks.
+- A new Download page displays links to the latest Miniforge installers.
+- The documentation has been split in two top-level categories: Docs and Community.
+- Algolia generously serves the backend for the search bar.
+- Netlify will render previews on each opened PR for a smoother contribution process.
+- The blog posts and the announcements feed are served natively by Docusaurus.
+- We converted all the Sphinx-native ReStructuredText documents to Docusaurus-friendly Markdown.
+- The conda-forge.yml docs are autogenerated from the conda-smithy schemas.
+- ... and a bunch of smaller changes in the documentation. Refer to the [meta-issue](https://github.com/conda-forge/conda-forge.github.io/issues/1971) for more information!
+
+## New features you can use
+
+- Learn how to use and maintain packages from conda-forge in the [main documentation section](/docs).
+- Read about how our community is set up in the [Community section](/community)
+- The most recent changes to our infrastructure will be announced in [News](/news). You can also subscribe to the [RSS feed](pathname:///news/rss.xml) and browse the [archive](/news/archive/).
+- Important information about the ecosystem is discussed in the [Blog](/blog). You can also subscribe to the [RSS feed](pathname:///blog/rss.xml) and browse the [archive](/blog/archive/). The posts are sometimes categorized with [tags](/blog/tags/) too.
+- Use the search bar to locate any document in the website! It should be smart enough to remember the content you need more often. Use the <kbd>Cmd/Ctrl</kbd>+<kbd>K</kbd> shortcut for faster access.
+- The [Status dashboard](/status) will inform you about the latest incidents and ongoing migrations. Each migration has now a permalink you can explore and share!
+- The [Packages](/packages) section will help you find all the packages in conda-forge. If you don't type anything in the search bar, it will list the last 100 uploads to the Anaconda.org channel. The metadata link in each row will take you to the [`conda-metadata-app` dashboard](https://conda-metadata-app.streamlit.app/).
+- Use the [Download page](/download) to get the latest Miniforge installers.
+
+## How to help and contribute
+
+We have changed a lot of things, so there's a chance we missed something somewhere. If you have suggestions or errors to report, please let us know in the [website issue tracker](https://github.com/conda-forge/conda-forge.github.io/issues). Feel free to check the [documentation contribution guidelines](/docs/user/contributing/#improve-the-website) too.
+
+## Acknowledgements
+
+This revamp was a months-long effort (read ). The core team would like to take a moment to thank to all the contributors that made it possible (in alphabetical order): Afshin Darian, Asmit Malakannawar, Gabriela Vives, Isabela Presedo-Floyd, Klaus Zimmermann, Tania Allard.