build (docs): add a code formatter to the docs/ folder (#4337)

Note: run `npm run format` to format changes in `docs/`.

Author: leafty

.github/workflows/pull-request-test.yml

@@ -42,17 +42,21 @@ jobs:
       run:
         working-directory: docs/
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-node@v4
+      - name: Checkout repository
+        uses: actions/checkout@v5
+      - name: Setup node
+        uses: actions/setup-node@v4
         with:
           node-version: "22"
           cache: npm
           cache-dependency-path: docs/package-lock.json
-      - name: install dependencies
-        run: npm install
-      - name: test docs spelling
+      - name: Install dependencies
+        run: npm clean-install
+      - name: Check docs formatting
+        run: npm run format:check
+      - name: Test docs spelling
         run: npm run spell-check
-      - name: test the docs build
+      - name: Test the docs build
         run: npm run build
 
   check-deploy:

docs/README.md

@@ -36,50 +36,56 @@ This command generates static content into the `build` directory and can be serv
 
 ## Deployment
 
-The documentation is deployed using [Read The Docs](https://about.readthedocs.com/). 
+The documentation is deployed using [Read The Docs](https://about.readthedocs.com/).
 The [renku project](https://app.readthedocs.org/projects/renku/) on Read the Docs
 builds and deploys when changes are made in the repo.
 
 ## Notes
 
-* When adding an image to a page, put it in the same folder as the page and reference it using a relative path (e.g. `./image.png`). By default, the image will fill the whole page's width. If that's what you want, you're done. Otherwise, you can wrap the image in a container with a custom width based on your desired size, e.g.:
-    ```md
-    <p class="image-container-s">
-    ![image 10](./image-10.png)
-    </p>
-    ```
-    The available container sizes are `image-container-s` (55% width), `image-container-m` (70% width), and `image-container-l` (85% width).
-* Image properties that are controllable by CSS can be modified in the documentation CSS file at `docs/src/css/custom.css`. Currently, we use it to add shadows to all images and to define the container sizes for images:
-    ```css
-    img {
-      filter: drop-shadow(0 10px 16px rgba(0, 0, 0, .25))
-              drop-shadow(0 2px 4px rgba(0, 0, 0, .15));
-    }
-
-    .image-container-s, .image-container-m, .image-container-l {
-      margin: auto;
-      text-align: center; /* Center the image horizontally when its width is narrower than the max-width*/
-    }
-
-    .image-container-s {
-      max-width: 55%;
-    }
-
-    .image-container-m {
-      max-width: 70%;
-    }
-
-    .image-container-l {
-      max-width: 85%;
-    }
-    ```
-* When adding a video to a page, put it in the same folder as the page. You then need to import it in the markdown file using its relative path and put the imported name in the `src` attribute of the `video` tag. For example:
-    ```md
-    import video10 from './video-10.mp4';
-
-    <video controls width="100%" src={video10} />
-    ```
-* When linking to other documentation pages, always use relative URL links (e.g. `../sessions/guides/create-environment-with-custom-packages-installed`) instead of absolute links (e.g. `/docs/users/sessions/guides/create-environment-with-custom-packages-installed`) or relative file paths (e.g. `../60-sessions/guides/20-create-environment-with-custom-packages-installed.md`).
-Always use URL links instead of file paths for links. Docusaurus converts file paths into URL links by removing number prefixes and the .md extension. To find the correct URL link, open the corresponding page in your browser, copy the path from the address bar, and adjust it to be relative to the current page.
-
-* If you add an `index.md` file to a directory, never add a prefix to it (e.g. `10-index.md`). Docusaurus treats `index.md` file specially, so it shouldn't have any prefix in its name. Prefixes are only used for other files in the directory to control their order.
+- When adding an image to a page, put it in the same folder as the page and reference it using a relative path (e.g. `./image.png`). By default, the image will fill the whole page's width. If that's what you want, you're done. Otherwise, you can wrap the image in a container with a custom width based on your desired size, e.g.:
+  ```md
+  <p class="image-container-s">
+  ![image 10](./image-10.png)
+  </p>
+  ```
+  The available container sizes are `image-container-s` (55% width), `image-container-m` (70% width), and `image-container-l` (85% width).
+- Image properties that are controllable by CSS can be modified in the documentation CSS file at `docs/src/css/custom.css`. Currently, we use it to add shadows to all images and to define the container sizes for images:
+
+  ```css
+  img {
+    filter: drop-shadow(0 10px 16px rgba(0, 0, 0, 0.25))
+      drop-shadow(0 2px 4px rgba(0, 0, 0, 0.15));
+  }
+
+  .image-container-s,
+  .image-container-m,
+  .image-container-l {
+    margin: auto;
+    text-align: center; /* Center the image horizontally when its width is narrower than the max-width*/
+  }
+
+  .image-container-s {
+    max-width: 55%;
+  }
+
+  .image-container-m {
+    max-width: 70%;
+  }
+
+  .image-container-l {
+    max-width: 85%;
+  }
+  ```
+
+- When adding a video to a page, put it in the same folder as the page. You then need to import it in the markdown file using its relative path and put the imported name in the `src` attribute of the `video` tag. For example:
+
+  ```md
+  import video10 from './video-10.mp4';
+
+  <video controls width="100%" src={video10} />
+  ```
+
+- When linking to other documentation pages, always use relative URL links (e.g. `../sessions/guides/create-environment-with-custom-packages-installed`) instead of absolute links (e.g. `/docs/users/sessions/guides/create-environment-with-custom-packages-installed`) or relative file paths (e.g. `../60-sessions/guides/20-create-environment-with-custom-packages-installed.md`).
+  Always use URL links instead of file paths for links. Docusaurus converts file paths into URL links by removing number prefixes and the .md extension. To find the correct URL link, open the corresponding page in your browser, copy the path from the address bar, and adjust it to be relative to the current page.
+
+- If you add an `index.md` file to a directory, never add a prefix to it (e.g. `10-index.md`). Docusaurus treats `index.md` file specially, so it shouldn't have any prefix in its name. Prefixes are only used for other files in the directory to control their order.

docs/docs/10-users/10-users.md

@@ -9,7 +9,6 @@ Renku is an **open-source platform for researchers and scientists to connect dat
 
 ## How to use Renku docs
 
-
 <p class="text-align: center">
 ![image.png](./rocket_40px.png)
 [**First Steps Tutorial**](/docs/users/getting-started/): Want to try it out? [**Create your account**](/docs/users/getting-started/tutorial-start) and follow our hands-on tutorial!
@@ -21,34 +20,33 @@ Renku is an **open-source platform for researchers and scientists to connect dat
 [**Projects**](/docs/users/projects/projects/) in Renku may contain [**Data**](/docs/users/data/data/), [**Code**](/docs/users/code/code-repository) and [**Sessions**](/docs/users/sessions/environment/) to foster [**Collaboration**](/docs/users/collaboration/). Check each individual building block for understanding the possibilities that Renku offers.
 </p>
 
-  ___
+---
 
 <p class="text-align: center">
 ![image.png](./use-cases_40px.png)
 [**Use Cases**](/docs/users/use-cases/) Learn more about how Renku is used in the broader community.
 </p>
 
-  ___
+---
 
 <p class="text-align: center">
 ![image.png](./use-cases_40px.png)
 [**Knowledge Base**](/docs/users/knowledge-base/fair-open-science/) Curiosity about how it works? [Any doubts](/docs/users/knowledge-base/faq/)? Join our channels to keep in touch with us.
 </p>
 
-  ___
+---
 
 <p class="text-align: center">
 ![image.png](./sunset_40px.png)
 [**Renku Legacy:**](/docs/users/migrate-v1-v2/) Guidelines on how to migrate your code repositories from Legacy Renkulab Gitlab to your own code repository provider, and keep
 </p>
 
-
 ## Use cases
 
-| Researchers    | Educators    | Event organizers  |
-| :-------------: |:-------------:| :-----:|
-| ![image.jpg](https://renkulab.io/assets/researcherIcon-DFFtd-Xp.svg) | ![image.jpg](https://renkulab.io/assets/educatorIcon-8mTN9nT-.svg) | ![image.jpg](https://renkulab.io/assets/organizerIcon-CcAdtX3S.svg) |
-| **Unified Research**  <p>Connect your entire research workflow in one place, and collaborate across specialties without technical barriers.</p> | **Computing Courses made easy** <p>Help your students focus on the material, not getting lost during setup. Ideal for project-based coursework and time-sensitive workshops.</p> | **Seamless Events** <p>Focus on innovation, not setup and infrastructure. Provide a consistent environment for all teams, and get participants coding and collaborating right away.</p> |
+|                                                                  Researchers                                                                   |                                                                                    Educators                                                                                     |                                                                                    Event organizers                                                                                     |
+| :--------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
+|                                      ![image.jpg](https://renkulab.io/assets/researcherIcon-DFFtd-Xp.svg)                                      |                                                        ![image.jpg](https://renkulab.io/assets/educatorIcon-8mTN9nT-.svg)                                                        |                                                           ![image.jpg](https://renkulab.io/assets/organizerIcon-CcAdtX3S.svg)                                                           |
+| **Unified Research** <p>Connect your entire research workflow in one place, and collaborate across specialties without technical barriers.</p> | **Computing Courses made easy** <p>Help your students focus on the material, not getting lost during setup. Ideal for project-based coursework and time-sensitive workshops.</p> | **Seamless Events** <p>Focus on innovation, not setup and infrastructure. Provide a consistent environment for all teams, and get participants coding and collaborating right away.</p> |
 
 ## What's new - Check out our latest blog posts:
 
@@ -59,7 +57,8 @@ Renku is an **open-source platform for researchers and scientists to connect dat
     <p>We've combined Renku's super-simple sessions with the power of supercomputing!</p>
 
     </p>
-  ___
+
+---
 
     <p class="image-container-s">
     [![AiiDA Success Story](https://blog.renkulab.io/assets/images/intro-image-f9ca2c80c6b9ad273b0d8750b112dab7.png)](https://blog.renkulab.io/aiida-success-story/)

docs/docs/10-users/20-getting-started/20-create-project.md

@@ -4,7 +4,7 @@ You will land in your Renku dashboard. From here, you can create a new project:
 
 1. In the **My projects** section of the dashboard, click on **+** to create a new project
 2. For project **Name**, enter **Genova Weather Analysis**
-    - (Leave **Owner, Visibility**, and **Description** unchanged)
+   - (Leave **Owner, Visibility**, and **Description** unchanged)
 3. Click **Create**.
 
 ![image.png](./GS_image_2.png)

docs/docs/10-users/20-getting-started/30-connect-data.md

@@ -16,7 +16,6 @@ Note that the description in Zenodo of this dataset is automatically imported as
 
 :::
 
-
 ## Connect a Storage Space to save your work (optional)
 
 The data connector in the previous step is read only. If you would like to be able to save the work you do in your Renku session, add a data connector for a storage where you'd like to save that work. For example, you might use a Switch Drive or polybox folder, or an S3 bucket.

docs/docs/10-users/20-getting-started/40-connect-code.md

@@ -16,12 +16,12 @@ We need to connect this git repository to the Renku project in order to access i
 
 Here's how to add the code repository to your project:
 
-1. Click on **+** under the Code Repositories section.
-2. Copy and paste the link to **Clone with HTTPS** from your git project.
-In this case, we already provide you with the code here:
+1.  Click on **+** under the Code Repositories section.
+2.  Copy and paste the link to **Clone with HTTPS** from your git project.
+    In this case, we already provide you with the code here:
 
-    ```
-    https://gitlab.com/renku/air-quality-analysis
-    ```
+        ```
+        https://gitlab.com/renku/air-quality-analysis
+        ```
 
 For more information about working with code repositories on Renku, check out the **code** section in the [How To Guides](../code/code-repository).

docs/docs/10-users/20-getting-started/50-launch-session.md

@@ -5,11 +5,10 @@
 To run your code and analyze data on RenkuLab, first decide what kind of session environment you would like by creating a session launcher.
 
 1. In the **Sessions** section of your project page, click on **+**.
-2. In the **Global environment** tab, scroll down and select  **Python Data Science - Jupyter**. This will give you a pre-configured environment with python and data science packages pre-installed. If you need to install other packages, you can install any necessary packages using the terminal. For a detailed guide for how to install packages, see [How to install packages on-the-fly in your session](../sessions/guides/environments/install-packages-on-the-fly-in-your-session). However, the packages you install on-the-fly in the session will not be shared with other people working with your Renku project. To ensure the adequate dependencies are installed in your environment, follow step 4.3 to create a custom environment from code.
+2. In the **Global environment** tab, scroll down and select **Python Data Science - Jupyter**. This will give you a pre-configured environment with python and data science packages pre-installed. If you need to install other packages, you can install any necessary packages using the terminal. For a detailed guide for how to install packages, see [How to install packages on-the-fly in your session](../sessions/guides/environments/install-packages-on-the-fly-in-your-session). However, the packages you install on-the-fly in the session will not be shared with other people working with your Renku project. To ensure the adequate dependencies are installed in your environment, follow step 4.3 to create a custom environment from code.
 3. Click **Next**.
 4. Choose the compute resources for your session based on your project’s needs in the drop-down menu, and select the amount of disk space.
 
-
 ![image.png](./add-session-launcher.png)
 
 :::info
@@ -19,6 +18,7 @@ You can have multiple Session Launchers in your project that run different kinds
 :::info
 Do you need more resources than those available in RenkuLab’s public resource classes? [Contact us!](mailto:hello@renku.io) We can configure a custom resource pool for your team or class.
 :::
+
 ## Launch a Session
 
 Click on the **Launch** button in your new Session Launcher to start a session.

docs/docs/10-users/20-getting-started/60-share.md

@@ -12,12 +12,12 @@ In your project page:
 
 1. Open the **Settings** tab.
 2. Go to **Project Members** and click on **+**
-3. Search for  the people you want to invite by name or username and set their role.
+3. Search for the people you want to invite by name or username and set their role.
 
 ![image.png](./add-member.png)
-    :::info
-    Note that in order to add people to your Renku project, they need to already have a Renku account.
-    :::
+:::info
+Note that in order to add people to your Renku project, they need to already have a Renku account.
+:::
 
 ## Make Your Project Public (optional)
 

docs/docs/10-users/20-getting-started/70-conclusion.md

@@ -1,6 +1,5 @@
 # Next Steps
 
-
 🎉 Congratulations! You have successfully created a Renku project, connected data and code, launched a session, and shared your project with collaborators.
 
 ![image.png](./congratulations.png)