Add docs markdown linter and readme

.github/workflows/previews.yaml

@@ -14,36 +14,53 @@ env:
   JETPACK_SECRET_KEY: ${{ secrets.JETPACK_SECRET_KEY }}
 
 jobs:
-  deploy-docs-preview:
-      runs-on: ubuntu-latest
-      steps:
-        - uses: actions/checkout@v3
-        - uses: dorny/paths-filter@v2
-          id: filter
-          with:
-            filters: |
-              docs:
-                - 'docs/**'
-        - uses: bahmutov/npm-install@v1
-          if: steps.filter.outputs.docs == 'true'
-          with:
-            working-directory: docs/app
-        - name: Mount docs node_modules
-          if: steps.filter.outputs.docs == 'true'
-          uses: actions/cache@v3
-          with:
-            path: docs/app/node_modules
-            key: docs-node-modules
-        - name: Docs build
-          if: steps.filter.outputs.docs == 'true'
-          run: |
-            yarn install
-            yarn run build
+  markdown-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: dorny/paths-filter@v2
+        id: filter
+        with:
+          filters: |
+            docs:
+              - 'docs/**'
+      - name: markdownlint-cli
+        uses: nosborn/github-action-markdown-cli@v3.2.0
+        with:
+          files: docs/app/docs
+          config_file: docs/.markdownlint.yaml
+
+  deploy-to-preview:
+    runs-on: ubuntu-latest
+    needs: markdown-lint
+    steps:
+      - uses: actions/checkout@v3
+      - uses: dorny/paths-filter@v2
+        id: filter
+        with:
+          filters: |
+            docs:
+              - 'docs/**'
+      - uses: bahmutov/npm-install@v1
+        if: steps.filter.outputs.docs == 'true'
+        with:
           working-directory: docs/app
-        - name: Deploy docs preview
-          if: steps.filter.outputs.docs == 'true'
-          run: |
-            curl https://get.jetpack.io -fsSL | bash -s -- -y
-            jetpack up docs \
-              --ttl 300 --debug \
-              -n jetpack-io-preview-$(echo "${GITHUB_REF_NAME}" | sed "s/[^0-9a-zA-Z]/-/g")
+      - name: Mount docs node_modules
+        if: steps.filter.outputs.docs == 'true'
+        uses: actions/cache@v3
+        with:
+          path: docs/app/node_modules
+          key: docs-node-modules
+      - name: Docs build
+        if: steps.filter.outputs.docs == 'true'
+        run: |
+          yarn install
+          yarn run build
+        working-directory: docs/app
+      - name: Deploy docs preview
+        if: steps.filter.outputs.docs == 'true'
+        run: |
+          curl https://get.jetpack.io -fsSL | bash -s -- -y
+          jetpack up docs \
+            --ttl 300 --debug \
+            -n jetpack-io-preview-$(echo "${GITHUB_REF_NAME}" | sed "s/[^0-9a-zA-Z]/-/g")

docs/.markdownlint.yaml

@@ -0,0 +1,10 @@
+# Autoformatter friendly markdownlint config (all formatting rules disabled)
+default: true
+blank_lines: false
+bullet: false
+html: false
+indentation: false
+line_length: false
+spaces: false
+url: false
+whitespace: false

docs/app/README.md → docs/README.md

@@ -5,7 +5,9 @@ This website is built using [Docusaurus 2](https://docusaurus.io/), a modern sta
 ### Installation
 
 ```
-$ yarn
+$ cd docs/app     # from the devbox root directory
+$ devbox shell    # optional, develop inside a devbox
+$ yarn install    # run in devbox shell
 ```
 
 ### Local Development
@@ -26,16 +28,6 @@ This command generates static content into the `build` directory and can be serv
 
 ### Deployment
 
-Using SSH:
-
-```
-$ USE_SSH=true yarn deploy
-```
-
-Not using SSH:
-
-```
-$ GIT_USER=<Your GitHub username> yarn deploy
-```
-
-If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+When a pull request is opened, it will automatically deploy via CICD to a preview.
+When a pull request is merged, it will automatically deploy to production.
+Check https://www.jetpack.io/devbox/ after merge to see the latest changes.

docs/app/devbox.json

@@ -0,0 +1,6 @@
+{
+  "packages": [],
+  "shell": {
+    "init_hook": null
+  }
+}

docs/app/docs/configuration.md

@@ -14,8 +14,8 @@ Your devbox configuration is stored in a `devbox.json` file, located in your pro
     "install_stage": {
         "command": "..."
     },
-    "build_stage":{
-        "command":"..."
+    "build_stage": {
+        "command": "..."
     },
     "start_stage": {
         "command": "..."
@@ -45,7 +45,7 @@ This is an example `devbox.json` that customizes the prompt and prints a welcome
 
 When run, you'll see:
 
-```
+```text
 > devbox shell
 Installing nix packages. This may take a while...
 Starting a devbox shell...
@@ -57,9 +57,9 @@ Welcome! See CONTRIBUTING.md for tips on contributing to devbox.
 
 Stages are used to configure and run commands at different points of container creation. For languages that support autodetction, Devbox will automatically detect and configure the correct stage commands for your project based on your source code. You can override any of these stages by configuring them in your devbox.json
 
-* The **install stage** will run after your base container has been initialized and your Nix packages are installed. This stage should be used to download and build your application's dependencies
-* The **build stage** runs after the install stage, and should be used to build or bundle your application.
-* The **start stage** will run when your container is started. This stage should include any commands needed to start and run your application.
+-   The **install stage** will run after your base container has been initialized and your Nix packages are installed. This stage should be used to download and build your application's dependencies
+-   The **build stage** runs after the install stage, and should be used to build or bundle your application.
+-   The **start stage** will run when your container is started. This stage should include any commands needed to start and run your application.
 
 Each stage takes a single command that will be run when the stage is reached in your container build.
 

docs/app/docs/installing_devbox.md

@@ -11,10 +11,10 @@ In addition to installing Devbox itself, you will need to install nix and docker
 
 2. Install [Docker Engine](https://docs.docker.com/engine/install/) or [Docker Desktop](https://www.docker.com/get-started/). Note that docker is only needed if you want to create containers – the shell functionality works without it.
 
-## Install Devbox:
+## Install Devbox
 
 Use the following install script to get the latest version of Devbox:
 
-```
+```bash
 curl -fsSL https://get.jetpack.io/devbox | bash
-```
+```

docs/app/docs/language_support/nginx.md

@@ -21,22 +21,22 @@ Devbox will use the nginx provided by the Nix Package manager. It is currently n
 
 ### Included Nix Packages
 
-- `nginx`
+-   `nginx`
 
 ### Default Stages
 
 These stages can be customized by adding them to your `devbox.json`. See the [Configuration Guide](../configuration.md) for more details
 
 ### Install Stage
 
-*No install stage for nginx planner*
+Skipped: _No install stage for nginx planner_
 
 ### Build Stage
 
-*No build stage for nginx planner*
+Skipped: _No build stage for nginx planner_
 
 ### Start Stage
 
 ```bash
 nginx -c <your_config> -g 'daemon off;'
-```
+```

docs/app/docs/language_support/nodejs.md

@@ -9,54 +9,89 @@ Devbox will automatically create a NodeJs Build plan whenever a `package.json` f
 ### Supported Versions
 
 Devbox will attempt to detect the Node version set in your `package.json` file. The following major versions are supported (Devbox will always use the latest minor version for each major version):
-* 10
-* 12
-* 16 
-* 18
+
+-   10
+-   12
+-   16
+-   18
 
 If no version is set, Devbox will use 16 as the default version
 
 ### Included Nix Packages
 
-* Depending on the detected Node Version:
-  * `nodejs`
-  * `nodejs10_x`
-  * `nodejs12_x`
-  * `nodejs16_x`
-  * `nodejs18_x`
-* If a `package-lock.json` is detected, or if no lockfile is detected:
-  * `npm`
-* If a `yarn.lock` file is detected: 
-  * `yarn`
-
+-   Depending on the detected Node Version:
+    -   `nodejs`
+    -   `nodejs10_x`
+    -   `nodejs12_x`
+    -   `nodejs16_x`
+    -   `nodejs18_x`
+-   If a `package-lock.json` is detected, or if no lockfile is detected:
+    -   `npm`
+-   If a `yarn.lock` file is detected:
+    -   `yarn`
 
 ### Default Stages
 
 These stages can be customized by adding them to your `devbox.json`. See the [Configuration Guide](../configuration.md) for more details
-#### Install Stage
+
+### Install Stage
 
 If a `package-lock.json` is detected:
+
 ```bash
 npm install
 ```
 
-If a `yarn.lock` is detected: 
+If a `yarn.lock` is detected:
+
 ```bash
 yarn install
 ```
 
-Otherwise: 
+Otherwise:
 
 ```bash
 npm install
 ```
 
-#### Build Stage
+### Build Stage
+
+This stage will copy over the rest of your project files.
+
+If a `package-lock.json` is detected and a `build` script is found in `package.json`:
+
+```bash
+npm run build && npm prune --production
+```
+
+If a `yarn.lock` is detected and a `build` script is found in `package.json`:
 
-This stage will copy over the rest of your project files, but will not run a command.
+```bash
+yarn build && yarn install --production --ignore-scripts --prefer-offline
+```
 
-#### Start Stage
+Otherwise, we simply remove the dev packages:
+
+```bash
+npm prune --production
+```
+
+### Start Stage
+
+If a `package-lock.json` is detected and a `start` script is found in `package.json`:
+
+```bash
+npm start
+```
+
+If a `yarn.lock` is detected and a `start` script is found in `package.json`:
+
+```bash
+yarn start
+```
+
+Otherwise:
 
 ```bash
 node index.js
-```
+```

docs/app/docs/language_support/php.md

@@ -4,27 +4,27 @@ title: PHP
 
 ### Detection
 
-Devbox will automatically create a PHP Build plan whenever a `composer.json` or `composer.lock` file is detected in the project's root directory. 
+Devbox will automatically create a PHP Build plan whenever a `composer.json` or `composer.lock` file is detected in the project's root directory.
 
-Building a container with Devbox also requires a `public/index.php` file in your project directory. Running `devbox build` will return an error if one is not found. 
+Building a container with Devbox also requires a `public/index.php` file in your project directory. Running `devbox build` will return an error if one is not found.
 
 ### Supported Versions
 
 Devbox will attempt to detect the PHP version set in your `composer.json` file. The following major versions are supported (Devbox will always use the latest minor version for each major version):
-* 7.4
-* 8.0
-* 8.1
+
+-   7.4
+-   8.0
+-   8.1
 
 If no version is set, Devbox will use 8.1 as the default version
 
 ### Included Nix Packages
 
-* Depending on the detected PHP Version:
-  * `php81`
-  * `php80`
-  * `php74`
-* `phpPackages.composer`
-
+-   Depending on the detected PHP Version:
+    -   `php81`
+    -   `php80`
+    -   `php74`
+-   `phpPackages.composer`
 
 ### Default Stages
 
@@ -36,10 +36,9 @@ These stages can be customized by adding them to your `devbox.json`. See the [Co
 composer install --no-dev --no-ansi
 ```
 
-
 #### Build Stage
 
-*This stage is skipped for PHP projects*
+Skipped: _This stage is skipped for PHP projects_
 
 #### Start Stage