docs: Small updates to the formatting of the README. (#335)

Signed-off-by: Ryan Parman <[email protected]>

.gitignore

@@ -20,3 +20,13 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+
+# Linting and related tooling that we don't want to push onto everybody
+# https://editorconfig.org
+.editorconfig
+# Git hooks
+.githooks
+# https://github.com/antham/gommit
+.gommit.toml
+# https://github.com/DavidAnson/markdownlint
+.markdownlint.*

.husky/.gitignore

@@ -0,0 +1 @@
+_

.vscode/extensions.json

@@ -0,0 +1,13 @@
+{
+  "recommendations": [
+    "bierner.markdown-preview-github-styles",
+    "bradlc.vscode-tailwindcss",
+    "davidanson.vscode-markdownlint",
+    "fcrespo82.markdown-table-formatter",
+    "howardzuo.vscode-npm-dependency",
+    "karanba.npm-helper",
+    "mistermunchkin.simple-markdown-snippets",
+    "mskelton.npm-outdated",
+    "unifiedjs.vscode-mdx"
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,15 @@
+{
+  // ===========================================================================
+  // For VS Code users, this will disable AI extensions for every VS Code user
+  // who works on this project. We should probably add the appropriate settings
+  // for all other AI tools as well.
+  //
+  // Unlike JetBrains IDEs, this directory and its files are *meant* to be
+  // committed to repositories so that recommended settings and extensions can
+  // be shared project-wide.
+  //
+  // This is a JSONC file. <https://code.visualstudio.com/Docs/languages/json>
+  // ===========================================================================
+  "github.copilot.toggleCopilot": "off",
+  "tabnine.codeLensEnabled": false
+}

README.md

@@ -1,60 +1,78 @@
-<img src="./.github/logo-dark.svg#gh-dark-mode-only" alt="OpenTofu" width="250px" />
-<img src="./.github/logo-light.svg#gh-light-mode-only" alt="OpenTofu" width="250px" />
+<picture>
+  <source srcset="./.github/logo-dark.svg" media="(prefers-color-scheme: dark)" width="250px">
+  <source srcset="./.github/logo-light.svg" media="(prefers-color-scheme: light), (prefers-color-scheme: no-preference)" width="250px">
+  <img src="./.github/logo-light.svg" width="250px" alt="OpenTofu">
+</picture>
 
 ## Stack
 
-- Docusaurus
-- React
-- TypeScript
-- Tailwind CSS
+- [Docusaurus]
+- [React]
+- [TypeScript]
+- [Tailwind CSS]
 
-## Working with this repository
+## Cloning the repository
 
-### Cloning the repository
-
-This repository uses git submodules to pull in the [main OpenTofu repository](https://github.com/opentofu/opentofu).
-You can clone it using the following two steps:
-
-1. Clone the repository:
+This repository uses Git submodules to pull in the [main OpenTofu repository](https://github.com/opentofu/opentofu).
 
 ```bash
-git clone [email protected]:opentofu/opentofu.org.git
+git clone --recurse-submodules [email protected]:opentofu/opentofu.org.git
 ```
 
-2. Fetch the documentation:
+<details>
+<summary>Oops! I forgot to recurse submodules…</summary><br>
 
 ```bash
 cd opentofu.org
 git submodule init
 git submodule update
 ```
 
-### Running the dev server locally
+</details>
+
+## Development
+
+You can either develop locally, or by using a local Docker container.
 
-You can run the dev server if you have a local NodeJS/npm environment installed:
+### Option A: Running the dev server locally
+
+You can run the dev server if you have a local Node.js/npm environment installed:
 
 1. Install dependencies:
 
-```bash
-npm i
-```
+   ```bash
+   npm install
+   ```
 
-2. Start the development server:
+1. Start the development server:
 
-```bash
-npm run start
-```
+   ```bash
+   npm run start
+   ```
 
-You can now access the site locally at http://localhost:3000/
+1. You can now access the site locally at <http://localhost:3000>.
 
-### Running the dev server in a container
+### Option A: Running the dev server in a container
 
-You can also run the dev server in a container with the following command:
+You can run the dev server in a Docker container with the following command:
 
 ```bash
 docker compose up --build
 ```
 
+## Troubleshooting
+
+### The docs folder does not exist for version "vX.Y"
+
+> Error: The docs folder does not exist for version "vX.Y". A docs folder is expected to be found at versioned_docs/version-vX.Y.
+
+Make sure you installed the Git submodules. See above for instructions.
+
 ## Contributing
 
 When you contribute code to OpenTofu, do not forget to sign off your commits as [described here](https://github.com/opentofu/opentofu/blob/main/CONTRIBUTING.md#signing-off-your-commits).
+
+[docusaurus]: https://docusaurus.io
+[react]: https://react.dev
+[tailwind css]: https://tailwindcss.com
+[typescript]: https://www.typescriptlang.org