From 2625a3ee85c966043b215d296cce3fa7f9e43b51 Mon Sep 17 00:00:00 2001
From: Ryan Parman <ryan@ryanparman.com>
Date: Wed, 30 Oct 2024 11:28:18 -0600
Subject: [PATCH] docs: Small updates to the formatting of the README. (#335)

Signed-off-by: Ryan Parman <ryan@ryanparman.com>
---
 .gitignore              | 10 ++++++
 .husky/.gitignore       |  1 +
 .vscode/extensions.json | 13 ++++++++
 .vscode/settings.json   | 15 +++++++++
 README.md               | 72 +++++++++++++++++++++++++----------------
 5 files changed, 84 insertions(+), 27 deletions(-)
 create mode 100644 .husky/.gitignore
 create mode 100644 .vscode/extensions.json
 create mode 100644 .vscode/settings.json

diff --git a/.gitignore b/.gitignore
index e5f1f23a..23a7e3fb 100644
--- a/.gitignore
+++ b/.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.*
diff --git a/.husky/.gitignore b/.husky/.gitignore
new file mode 100644
index 00000000..31354ec1
--- /dev/null
+++ b/.husky/.gitignore
@@ -0,0 +1 @@
+_
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
new file mode 100644
index 00000000..248d1328
--- /dev/null
+++ b/.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"
+  ]
+}
diff --git a/.vscode/settings.json b/.vscode/settings.json
new file mode 100644
index 00000000..339fa090
--- /dev/null
+++ b/.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
+}
diff --git a/README.md b/README.md
index 2a2cb3f8..16745132 100644
--- a/README.md
+++ b/README.md
@@ -1,27 +1,26 @@
-<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 git@github.com:opentofu/opentofu.org.git
+git clone --recurse-submodules git@github.com:opentofu/opentofu.org.git
 ```
 
-2. Fetch the documentation:
+<details>
+<summary>Oops! I forgot to recurse submodules…</summary><br>
 
 ```bash
 cd opentofu.org
@@ -29,32 +28,51 @@ 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