Update workflow

Author: brunopgalvao

.CONTRIBUTING.md

@@ -3,6 +3,7 @@
 > **📋 Essential**: All contributions must follow the [PaperMoon Style Guide](https://github.com/papermoonio/documentation-style-guide).
 
 ## Contents
+
 - [Quick Start](#quick-start)
 - [Fix or Improve Existing Content](#fix-or-improve-existing-content)
 - [Add a New Page](#add-a-new-page)
@@ -16,24 +17,30 @@
 ## Quick Start
 
 1. **Fork and Create Branch**
+
    ```bash
    git clone https://github.com/your-username/polkadot-docs.git
    cd polkadot-docs
    git checkout -b your-feature-branch
    ```
 
 2. **Make Your Changes**
+
    - Follow the [PaperMoon Style Guide](https://github.com/papermoonio/documentation-style-guide)
    - Test your changes locally (see [Running Polkadot Docs Locally](../README.md#run-polkadot-docs-locally))
 
 3. **Update AI Documentation**
-   After making content changes, regenerate the AI-ready documentation files:
+
+   After making content changes, regenerate the AI-ready documentation files. 
+   
+   Set up your Python environment following the [Set Up Python Environment](./README.md#set-up-python-environment) section of the README, then run:
    ```bash
    python3 scripts/generate_llms.py
    ```
    **Note**: Run this script on every PR once all changes are committed.
 
 4. **Create Pull Request**
+
    - Push your branch and create a pull request
    - Use the PR template to indicate your review preference
 
@@ -56,6 +63,7 @@ To add a page to an existing section:
 1. **Create your markdown file** following [naming conventions](https://github.com/papermoonio/documentation-style-guide/blob/main/style-guide.md#naming-conventions)
 
 2. **Include required frontmatter**:
+
    ```markdown
    ---
    title: Page Title (max 60 chars for SEO)
@@ -76,6 +84,7 @@ To add a page to an existing section:
    - [Google's description recommendations](https://developers.google.com/search/docs/advanced/appearance/snippet?hl=en)
 
 3. **Update navigation** - Add your page to the `.nav.yml` file in the same directory:
+
    ```yaml
    - 'Your Page Display Name': 'your-file-name.md'
    ```
@@ -85,6 +94,7 @@ To add a page to an existing section:
 To create an entirely new section of documentation:
 
 1. **Create directory structure**:
+
    ```
    your-new-section/
    ├── .nav.yml
@@ -93,6 +103,7 @@ To create an entirely new section of documentation:
    ```
 
 2. **Create `.nav.yml`**:
+
    ```yaml
    title: Section Display Name
    nav: 
@@ -125,13 +136,15 @@ tutorials/
 ```
 
 ### Set Up Directory Structure
+
 ```
 tutorials/[section]/[subsection]/[tutorial-name].md
 images/tutorials/[section]/[subsection]/[tutorial-name]/
 .snippets/code/tutorials/[section]/[subsection]/[tutorial-name]/
 ```
 
 ### Use the Tutorial Template
+
 ```markdown
 ---
 title: Tutorial Title (max 60 chars)
@@ -159,6 +172,7 @@ Related tutorials
 ```
 
 ### Tutorial Requirements
+
 - All code examples must be tested and functional
 - Always specify dependency versions (e.g., `npm install [email protected]`)
 - Use action-oriented section titles
@@ -171,11 +185,13 @@ Related tutorials
 **Where to store**: `images/<path-matching-doc-structure>/`
 
 **Requirements**:
+
 - Format: `.webp`
 - Desktop screenshots: 1512px width, variable height
 - Browser extension screenshots: 400x600px
 
 **How to use**:
+
 ```markdown
 ![Alt text description](/docs/images/<subdirectory>/<image-file-name>.webp)
 ```

README.md

@@ -6,7 +6,7 @@ The documentation source files are written in [Markdown](https://daringfireball.
 
 ## Run Polkadot Docs Locally
 
-You may want to spin up a local version of the documentation site to preview your changes. This guide will cover the steps needed to serve a local version.
+Follow these steps to run the documentation site locally and preview your changes.
 
 ### Clone Repositories
 
@@ -40,34 +40,57 @@ To set up the structure, follow these steps:
     git clone https://github.com/polkadot-developers/polkadot-docs.git
     ```
 
-### Install Dependencies and Serve Site
+### Set Up Python Environment
 
-1. Now that the repositories are cloned and properly nested, use the [pip](https://pypi.org/project/pip/) package installer to install [mkdocs](https://www.mkdocs.org/) and other required dependencies by running the command:
+Navigate to the `polkadot-mkdocs` directory and create a Python virtual environment:
 
-    ```bash
-    pip install -r requirements.txt
-    ```
+```bash
+cd polkadot-mkdocs
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+pip install -r requirements.txt
+```
 
-    This command will install all dependencies listed in the `requirements.txt` file.
+### Install Dependencies and Serve Site
 
-2. Switch to the `polkadot-docs` directory and use [npm](https://docs.npmjs.com/about-npm) to install dependencies:
+1. Install Node.js dependencies:
 
     ```bash
-    cd polkadot-docs && npm install
+    cd polkadot-docs && npm install && cd ..
     ```
 
-3. Navigate back to the `polkadot-mkdocs` folder, then build the site:
+2. Serve the site:
 
     ```bash
     mkdocs serve
     ```
 
 After a successful build, the site should be available at http://127.0.0.1:8000.
 
+### Deactivating the Virtual Environment
+
+When you're done working on the documentation, you can deactivate the virtual environment by running:
+
+```bash
+deactivate
+```
+
+### Next Time You Work on the Docs
+
+When you return to work on the documentation:
+
+1. Navigate to the `polkadot-mkdocs` directory
+2. Activate the virtual environment:
+   - macOS/Linux: `source venv/bin/activate`
+   - Windows: `venv\Scripts\activate`
+3. Run `mkdocs serve` to start the development server
+
 ## Contributing
 
 See [.CONTRIBUTING.md](./CONTRIBUTING.md) for how to contribute to this repository.
 
+We're excited to have you contribute to the **Polkadot Docs** and help improve our ecosystem! 🚀 Every contribution, whether it's fixing a typo, improving documentation, or adding new content, helps make Polkadot more accessible to developers worldwide. Thank you for being part of our community! 🙏✨
+
 ## Disclaimer
 
 ### Licensing Disclaimer