Comprehensive Guide for New Contributors

Welcome to our MkDocs project! This guide will help you set up your environment, make contributions, and deploy changes. Whether you're new to GitHub or MkDocs, follow these step-by-step instructions to get started.

Prerequisites

Before you begin, ensure you have the following tools installed:

1. Visual Studio Code (VSCode): A powerful and free code editor.

2. Download and install VSCode from here.

3. Git: A version control system to manage code changes.

4. Download and install Git from here.

5. Python: A programming language required to run MkDocs.

6. Download and install Python from here.

Setting Up the Project

1. Fork the Repository

2. Go to the project repository on GitHub and click on the "Fork" button in the upper right corner to create a copy of the repository under your GitHub account.

3. Clone Your Fork

4. Open VSCode.

5. Open the terminal in VSCode by selecting View > Terminal or using the shortcut Ctrl+`.

6. In the terminal, clone your forked repository by running:

   bash git clone https://github.com/your-username/your-repository.git cd your-repository

7. Create a Virtual Environment

8. Set up a virtual environment to manage your dependencies. In the terminal, run:

   bash python -m venv env

9. Activate the virtual environment:

   • On Windows:

   bash env\Scripts\activate

   • On macOS and Linux:

   bash source env/bin/activate

10. Install Dependencies

11. Install MkDocs and the Material theme by running:

    bash pip install mkdocs mkdocs-material

12. Run the Project Locally

13. Start the MkDocs development server to see your changes live:

    bash mkdocs serve

14. Open your browser and go to http://127.0.0.1:8000/ to view the site.

Making Contributions

Creating a New Page

1. Create a Markdown File

2. In VSCode, create a new file in the docs directory. For example:

   bash docs/new_page.md

3. Add Content to the Page

4. Open the new file in VSCode and add your content using Markdown syntax.

5. Update the Navigation

6. Open mkdocs.yml in VSCode and add your new page to the navigation:

   yaml nav: - Home: index.md - About: about.md - New Page: new_page.md

Editing Existing Pages

1. Locate the File

2. In VSCode, navigate to the docs directory and find the Markdown file you want to edit.

3. Make Your Changes

4. Open the file in VSCode and make your changes.

Committing and Pushing Changes

1. Stage Your Changes

2. In the terminal, stage your changes:

   bash git add .

3. Commit Your Changes

4. Commit your changes with a descriptive message:

   bash git commit -m "Describe your changes"

5. Push to Your Fork

6. Push your changes to your forked repository:

   bash git push origin main

7. Create a Pull Request

8. Go to the original repository on GitHub.

9. Click on the "Pull Requests" tab and then "New pull request".
10. Select your branch and create a pull request.

Deploying Changes

Our project uses GitHub Actions to automatically deploy changes to GitHub Pages.

GitHub Actions Workflow

1. Ensure Your Workflow File is Correct

2. The .github/workflows/deploy.yml file should look like this:

   ```yaml name: Deploy to GitHub Pages

   on: push: branches: - main