Merge pull request #15 from Firgrep/main

Docs update

src/pages/-contributing/_meta.json

@@ -22,5 +22,6 @@
     },
     "why-these-tools": "",
     "github": "",
-    "formatting": ""
+    "formatting": "",
+    "local-development": ""
 }

src/pages/-contributing/code-of-conduct.mdx

@@ -11,7 +11,7 @@ We as members, contributors, and leaders pledge to make participation in our com
 
 We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
 
-We pledge to act in accordance with the tenets and guidelines set out in the [methodology](/-contributing/methodology) to the best of our ability to build _the_ resource for systematic philosophy on the internet, or improve upon it with our collaborators. 
+We pledge to act in accordance with the tenets and guidelines set out in the [methodology](/-contributing/methodology) to the best of our ability to build _the_ resource for systematic philosophy on the internet. 
 
 ## Our Standards
 

src/pages/-contributing/formatting.mdx

@@ -10,21 +10,16 @@ import { Card, Cards } from 'nextra/components'
     <Card
         icon={" 📄 "}
         title="Basics of Markdown"
-        href="/-contributing/markdown/basics"
+        href="/-contributing/formatting/basic-markdown"
     />
     <Card
-        icon={""}
-        title="Placeholder"
-        href="/"
-    />
-    <Card
-        icon={""}
-        title="Placeholder"
-        href="/"
+        icon={" 📄 "}
+        title="Extended Markdown"
+        href="/-contributing/formatting/extended-markdown"
     />
     <Card
-        icon={""}
-        title="Placeholder"
-        href="/"
+        icon={" 📄 "}
+        title="Nextra"
+        href="/-contributing/formatting/nextra"
     />
 </Cards>

src/pages/-contributing/github.mdx

@@ -13,9 +13,9 @@ import { Card, Cards } from 'nextra/components'
         href="/-contributing/github/conceptual-overview"
     />
     <Card
-        icon={""}
-        title="Placeholder"
-        href="/"
+        icon={" 📄 "}
+        title="General Workflow"
+        href="/-contributing/github/general-workflow"
     />
     <Card
         icon={""}

src/pages/-contributing/github/general-workflow.mdx

@@ -0,0 +1,110 @@
+import { Callout } from 'nextra/components'
+
+# General GitHub Workflow
+
+### Basic Setup
+
+Forking a repository on GitHub involves creating your copy of someone else's repository. It's a fundamental feature of GitHub that allows you to contribute to projects, experiment with changes, or use the code as a starting point for your own project.
+
+1. **Creating a Fork:** On GitHub, you'll find a "Fork" button on the top right of a repository page. Clicking this creates a copy of the repository under your GitHub account.
+
+```mermaid
+graph TD;
+    subgraph AA [github.com]
+    id1[(Source Repository)] --> id2[Your Copy on GitHub];
+    end
+```
+
+2. **Your Copy:** The forked repository now exists in your GitHub account, and you can make changes to it without affecting the original repository. You can clone this fork to your local machine and start working on it just like you would with any other repository.
+
+```mermaid
+graph TD;
+    subgraph AA [github.com]
+    id1[Your Copy on GitHub];
+    end
+    id1[Your Copy on GitHub] --> id2[Your Local Copy]
+```
+
+3. **Cloning**: To create a local copy, find the "Clone or download" button on your GitHub repository page. Clicking this button reveals a URL that you can use to clone the repository to your local machine using the `git clone` command. The full command looks like this:
+
+```bash
+git clone <url>
+```
+
+Notice that the repository on your local machine and the repository on GitHub are now linked, but they *do not sync automatically*. To achieve this, you must manually push and pull changes between them using the `git push` and `git pull` commands.
+
+### Making Changes
+
+The basic workflow for making changes to a repository is as follows:
+
+1. **Create a Branch:** When you're working on a project, you're going to want to create a branch for each new feature or bug fix you implement. This keeps your changes organized and allows you to work on multiple features at once without affecting the main codebase. To create a branch, use the `git checkout` command with the `-b` flag:
+
+```bash
+git checkout -b <branch-name>
+```
+
+2. **Make Changes:** Once you've created a branch, you can start making changes to the codebase. You can use the `git status` command to see which files have been modified, and the `git diff` command to see the exact changes you've made. When you're ready to commit your changes, use the `git add` command to add the files you want to commit, and the `git commit` command to commit them:
+
+```bash
+git add <file1> <file2> ... # or `git add .` to add all files
+git commit -m "Commit message"
+```
+
+3. **Push Changes:** Once you've committed your changes, you can push them to your GitHub repository using the `git push` command:
+
+```bash
+git push origin <branch-name>
+```
+
+4. **Create a Pull Request:** Once you've pushed your changes to your GitHub repository, you can create a pull request to merge them into the main codebase. To do this, go to your repository page on GitHub and click the "New pull request" button. This will take you to a page where you can review your changes and create a pull request.
+
+```mermaid
+graph TD;
+    subgraph AA [github.com]
+    id1[Your Copy on GitHub] --> id2{Pull Request}
+    id2{Pull Request} --> id3[(Source Repository)];
+    end
+```
+
+Note that any changes you make to your local repository after creating a pull request will be included in the pull request automatically. This means that you can continue working on your branch while the pull request is being reviewed.
+
+Note also that you any changes you do locally must be pushed to your GitHub repository before they can be included in the pull request.
+
+5. **Review Changes:** Once you've created a pull request, you can review your changes and make sure everything looks good before merging them into the main codebase. You can also use this time to discuss your changes with other contributors and make sure everyone is on the same page.
+
+6. **Merge Changes:** Once you and the collaborators are happy with your changes, you can merge them into the main codebase using the "Merge pull request" button on GitHub (or this will be done by one of the maintainers). This will merge your changes into the main codebase and close the pull request.
+
+Note that you can only merge a pull request if there are no conflicts between your changes and the main codebase. If there are conflicts, you will need to resolve them before you can merge the pull request.
+
+### Staying Up to Date
+
+When you're working on a project, it's important to stay up to date with the latest changes in the main codebase. This ensures that your changes are compatible with the latest version of the codebase, and that you don't accidentally overwrite someone else's work.
+
+To sync your GitHub forked copy with the source repository, you can click the sync button on your GitHub repository page. This will pull changes from the main codebase into your GitHub repository, and allow you to continue working on your branch without affecting the main codebase.
+
+To stay up to date between your GitHub copy and local copy, you can use the `git pull` command to pull changes from the main codebase into your local repository. This will merge any changes that have been made since you last pulled into your local repository, and allow you to continue working on your branch without affecting the main codebase.
+
+```bash
+git pull origin main
+```
+
+Note that if you have uncommitted changes in your local repository, you will need to commit them before you can pull changes from the main codebase.
+
+<Callout type="info" emoji="ℹ️">
+    What if you have worked on some changes in your local codebase but meanwhile there has been an update on the source repository? You can use the <code>git stash</code> command to temporarily store your changes, sync your GitHub copy with the source repository, pull the latest changes from the GitHub copy down to your local repository, and then apply your changes on top of them. Or, alternatively, after syncing your GitHub copy with the source repository, you can commit your current changes and then pull the changes from your remote GitHub copy down to your local repository, which will merge the incoming changes with yours. Note that conflics may arise in both cases, which you will need to resolve manually.
+</Callout>
+
+### Resolving Conflicts
+
+When you merge a pull request, GitHub will automatically try to merge your changes into the main codebase. If there are any conflicts between your changes and the main codebase, GitHub will notify you and allow you to resolve them manually.
+
+To resolve conflicts, you can use the `git merge` command to merge the main codebase into your local repository. This will allow you to resolve any conflicts manually before merging your changes into the main codebase.
+
+```bash
+git merge origin main
+```
+
+### Further information
+
+You can read more about the GitHub flow [here](https://guides.github.com/introduction/flow/).
+

src/pages/-contributing/index.mdx

@@ -186,7 +186,7 @@ Unless you are working with a code editor on local development, you may want to
 
 ### Summary of Article Handling
 
-In this section we have briefly touched on the basics of using GitHub to create and edit files on a codebase. There are many more advanced features to uncover, but these operations should get you going for the majority of tasks. You may next want to consider looking more in-depth at [formatting]() or, if you plan on collaborating extensively with sPhil, consider setting up your [local development](). 
+In this section we have briefly touched on the basics of using GitHub to create and edit files on a codebase. There are many more advanced features to uncover, but these operations should get you going for the majority of tasks. You may next want to consider looking more in-depth at [formatting](/-contributing/formatting) or, if you plan on collaborating extensively with sPhil, consider setting up your [local development](-contributing/local-development). 
 
 ## Contributing Code
 

src/pages/-contributing/local-development.mdx

@@ -0,0 +1,91 @@
+import { Callout } from 'nextra/components'
+
+# Local Development
+
+Settings up local development takes a bit of work, but it's absolutely worth it if you plan on contributing often to sPhil. The following is a guide on how to set up a local development environment on Windows. If you're on Mac, you're on your own. Just kidding, the process should be roughly the same. (Linux users are probably smart enough to figure it out on their own.)
+
+Furthermore, this guide is split into lite and full versions. The lite version is for those who just want to write and edit the content, but don't plan on running the site locally or involve themselves with the programmatic parts. The full version is for those who do want to get fully involved, code and all, and run the site locally. 
+
+### Lite Version
+
+#### Terminals and Installation
+
+First, get acquainted with your terminal. Windows comes with Command Prompt, but we recommend using either [PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.4) or [Git Bash](https://git-scm.com/downloads) instead. PowerShell is best installed from Window's App Store, while Git Bash is best installed from the link above. The simplest way to launch a terminal in Windows is to press `Win` button and type `powershell` or `git bash` into the prompt (note you want `powershell`, not `windows powershell`). This launches a terminal from the user's home directory (usually). No need to do anything yet but know how to start a terminal when we need it. 
+
+Now, you will need to install the following on your local machine:
+
+- [Git](https://git-scm.com/downloads)
+- A text editor (We recommend [VS Code](https://code.visualstudio.com/), but you can use whatever you want)
+- [GitHub Command Line Interface](https://cli.github.com/)
+
+With the tools installed, open up a terminal and navigate to a directory where you want to store the sPhil codebase. For example, if your terminal starts you in your root user directory, you can make a new folder for all your development projects by typing `mkdir dev` and then `cd dev` to navigate into the new folder.
+
+If your terminal starts you in your system directory, you can navigate to your user directory by typing `cd ~` (the long route is to type `cd ../..` and then type `cd Users/<your-username>`). Then, you can make a new folder for all your development projects by typing `mkdir dev` and then `cd dev` to navigate into the new folder.
+
+#### Cloning the Repository
+
+Now, we need to clone the repository. First, retrieve the link from your GitHub copy of sPhil and type `git clone <insert-url-here> sphil` into your terminal. This will create a new folder called `sphil` in your current directory and clone the repository into it. It is important you have exactly one space between all the elements of the command.
+
+Once the repository is cloned, navigate into the `sphil` folder by typing `cd sphil`. You should now be in the root directory of the repository.
+
+#### Editing Content
+
+Inside the `sphil` directory in your terminal, type `code .` to open the repository in VS Code. This will open a new VS Code window with the repository's contents. From here you can look around and open any file to view and edit its contents. At its core, VS Code is really just a text editor, so you can use it to edit any text file, which is what programming source files largely are.
+
+The content of the sPhil is stored in the `pages` folder under `src`. Inside the `pages` folder, you will find a folder for each page of the website.
+
+<Callout type="info" emoji="ℹ️">
+    VS Code will likely prompt you about installing some extensions based on the file-types it detects in the repository. You can install them if you want, but they are not necessary for editing the content. However, we do recommend installing a few. 
+    <ul>
+        <li>- Better Comments</li>
+        <li>- MDX</li>
+        <li>- vscode-icons (if you want swanky icons)</li>
+    </ul>
+</Callout>
+
+#### Committing Changes and Pushing to GitHub
+
+Once you've made some changes to the content, you can commit them to your local repository. First, open up a terminal in VS Code by pressing the `TERMINAL` button at the bottom panel and type `git status`. This will show you all the files you've changed since the last commit. (Note: the panels in VS Code can be adjusted by dragging the divider between them.)
+
+Next, type `git add .` to add all the changed files to the commit. Then, type `git commit -m "<insert-commit-message-here>"` to commit the changes. The commit message should be a short description of the changes you made. For example, if you added a new page, you could type `git commit -m "Added new page on X"`.
+
+Finally, type `git push` to push the changes to your GitHub copy repository. You will be prompted to enter your GitHub username and password. Once you do, the changes will be pushed to your GitHub repository. 
+
+Open your browser and navigate to your GitHub repository. You should see the changes you made in the repository and you can open a PR to the source repository from there.
+
+<Callout type="info" emoji="ℹ️">
+    Use the GitHub CLI to login to your GitHub account and push changes to your repository. This will save you from having to enter your username and password every time you push changes. Use the command <code>gh auth login</code> to login to your GitHub account. You can also use the command <code>gh auth status</code> to check if you're logged in.
+</Callout>
+
+
+### Full Version
+
+The full version extends the lite version by adding the ability to run the site locally. This is useful for testing out changes to the site before pushing them to the source repository. You need to have the lite version set up before you can do the full version.
+
+#### Installation
+
+In addition to all the other things installed previously, you need to install [Node.js](https://nodejs.org/en/download/). We recommend installing the LTS version. Once installed, open up a terminal and type `node -v` to check that it's installed correctly. You should see the version number of the Node.js installation.
+
+Next, navigate to your local `sphil` repository in a terminal and type `npm install` to install all the dependencies. This will take a while, so go grab a coffee or something. Once it's done, you're ready to run the site locally.
+
+If you use VS Code, some extensions you might want to install are:
+- Better Comments
+- MDX
+- ESLint
+- Git Graph
+- Git History
+- Pretty TypeScript Errors
+- Tailwind CSS IntelliSense
+- vscode-icons (if you want swanky icons)
+
+#### Running the Site Locally
+
+To run the site locally, navigate to your local `sphil` repository in a terminal and type `npm run dev` (this will occupy the terminal in which this is launched). This will start a local development server and open a browser window with the site running (or navigate to `https://localhost:3000` in your browser). You can now make changes to the content and see them instantly reflected in the browser!
+
+<Callout type="info" emoji="ℹ️">
+    Normally when you make changes to the content, the site will automatically reload in the browser. However, sometimes it doesn't or it crashes. If either happens, try refreshing the page. The missing `useRef` error is a common one that causes the site to crash, which has to do with how Nextra loads and transpiles `.mdx` files. If you see this error, nothing to worry about, just refresh the page.
+</Callout>
+
+### Troubleshooting
+
+Running into issues? Google is your friend and should be the first stop to debug any issues you run into. Second you can try ChatGPT or an other AI; they're good for basic issues but for more advanced problems they tend to be more an obstacle. Usually, the best source is the documentation website for the specific program or tool in which you're having trouble with. If you can't find a solution, feel free to reach out to the sPhil team for help.