diff --git a/.devcontainer/docs/devcontainer.json b/.devcontainer/docs/devcontainer.json new file mode 100644 index 00000000000..287db0d90cf --- /dev/null +++ b/.devcontainer/docs/devcontainer.json @@ -0,0 +1,20 @@ +{ + "name": "Node.js", + "image": "mcr.microsoft.com/devcontainers/javascript-node:0-18", + "features": { + "ghcr.io/devcontainers/features/git:1": {} + }, + "forwardPorts": [3000], + "postCreateCommand": "cd docs && yarn install", + "customizations": { + "codespaces": { + "vscode": { + "extensions": ["esbenp.prettier-vscode", "streetsidesoftware.code-spell-checker"] + }, + "openFiles": ["docs/CODESPACES.md"] + } + } + + // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root. + // "remoteUser": "root" +} diff --git a/docs/CODESPACES.md b/docs/CODESPACES.md new file mode 100644 index 00000000000..d2129af7e5a --- /dev/null +++ b/docs/CODESPACES.md @@ -0,0 +1,24 @@ +# You're Using Codespaces + +Look at you go! Since this is running in a devcontainer, we've installed dependencies automatically for you 🔥 + +## The deets + +We've installed a few useful extensions for you, too: + +- **Prettier** because who formats their own code in this day and age? +- **code-spell-checker** because words are hard. + +We hope these additions make contributing a breeze. + +## Next steps + +In the terminal below, you should see a `postCreateCommand` script running. When it's done, you'll need to run the following command to fire up the dev server: + +```bash +cd docs && yarn start --host 0.0.0.0 +``` + +Happy contributing! + +❤️ Docs Team diff --git a/docs/static/img/wiki/codespaces-1.gif b/docs/static/img/wiki/codespaces-1.gif new file mode 100644 index 00000000000..061ca655e71 Binary files /dev/null and b/docs/static/img/wiki/codespaces-1.gif differ diff --git a/docs/static/img/wiki/codespaces-2.gif b/docs/static/img/wiki/codespaces-2.gif new file mode 100644 index 00000000000..cd2c09630c6 Binary files /dev/null and b/docs/static/img/wiki/codespaces-2.gif differ diff --git a/docs/wiki/contributions.mdx b/docs/wiki/contributions.mdx index 2d4e73eedc5..8dd55da3268 100644 --- a/docs/wiki/contributions.mdx +++ b/docs/wiki/contributions.mdx @@ -300,7 +300,7 @@ Assets are stored in `static/img/`. Just like the file-based rou file paths are important for images as well. However, instead of any output to the console, the page will simply crash and present a message indicating which image's path cannot be resolved. - + Use the erroneous image path to identify the error, facepalm, and then fix your typo. @@ -325,3 +325,31 @@ Perhaps the biggest pitfall we've encountered with Docusaurus is how delicate `. placement of code blocks and other text. If you've included a code block using common markdown syntax, and things aren't rendering as you think they should, try giving the block a bit of breathing room with a single empty line above and below it. + +## Codespaces + +:::info Note + +For Hasurians, we've recently introduced a new way to contribute to the docs: +[Codespaces](https://docs.github.com/en/codespaces). This is a new feature from GitHub that allows you to spin up a +fully-configured docs dev environment in the cloud. This means you can get started contributing to the docs without +having to install any dependencies on your local machine. + +::: + +### Step 1: Create a Codespace + +Head to the `hasura/graphql-engine-mono` repo and click the `Code` button. You should see a `Open with Codespaces` +button. Click it and choose `...` and then `+ New with options...` as in the example below: + + + +### Step 2: Configure your Codespace + +You'll be presented with a few options. Select the `docs` devcontainer, the region nearest to you, and a machine type +before clicking `Create codespace`: + + + +The Codespace will spin up and you'll be presented with a fully-configured dev environment. We automatically open you to +the `CODESPACES.md` file where you can follow the instructions to get started quickly.