Docker instructions (#4733)

* Add docker instructions to preview website locally

Signed-off-by: Carlos Santana <csantana23@gmail.com>

* minor updates

Signed-off-by: Carlos Santana <csantana23@gmail.com>

contribute-to-docs/getting-started/previewing-docs-locally.md

@@ -2,9 +2,38 @@
 
 The Knative website uses [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
 to render documentation.
-You can choose to install MkDocs locally or use a Docker image.
 
-## Install Material for MkDocs locally
+If you don't want to use any tool locally, you can use [GitPod](https://gitpod.io/#https://github.com/knative/docs)
+this will allow you to edit the files on a Web IDE and live preview.
+
+If you choose to run the site locally, we strongly recommend using a container.
+
+Regardless of the method used, when you submit a PR, a live preview link will be available in a comment on the PR.
+
+## Use the Docker container
+
+To start the live preview, run the following script.
+```
+./hack/docker/run.sh
+```
+Then open a web browser on http://localhost:8000
+
+You can edit any file under `./docs` and the live preview autoreloads.
+
+When you're done with your changes, you can stop the container in another terminal.
+```
+./hack/docker/stop.sh
+```
+You can run a complete build of the website with all versions using.
+```
+./hack/docker/test.sh
+```
+The build output is the entire static site located in `./site`.
+
+You can preview the website locally by running a webserver using this directory like `npx http-server site -p 8000` if you have Node.js or `python3 -m http.server 8000` if you have Python 3
+
+
+### Install Material for MkDocs locally
 
 Material for MkDocs is Python based and uses pip to install most of its required
 packages, as well as the optional add-ons we use.
@@ -14,7 +43,7 @@ from the [Python website](https://www.python.org).
 
 For some (e.g. folks using RHEL), you might have to use pip3.
 
-### Install using pip
+#### Install using pip
 
 1. Install Material for MkDocs by running:
 
@@ -30,26 +59,9 @@ For some (e.g. folks using RHEL), you might have to use pip3.
     pip install mkdocs-material-extensions mkdocs-macros-plugin mkdocs-exclude mkdocs-awesome-pages-plugin mkdocs-redirects
     ```
 
-### Install using pip3
+If you have `pip3` you can use the above commands and replace `pip` with `pip3`
 
-1. Install Material for MkDocs by running:
+### Setting up local preview
-
-    ```
-    pip3 install mkdocs-material
-    ```
-
-    For more detailed instructions, see the [Material for MkDocs documentation](https://squidfunk.github.io/mkdocs-material/getting-started/#installation)
-
-1. Install the extensions to MkDocs needed for Knative by running:
-
-    ```
-    pip3 install mkdocs-material-extensions mkdocs-macros-plugin mkdocs-exclude mkdocs-awesome-pages-plugin mkdocs-redirects
-    ```
-
-## Use the Docker container
-//TODO DOCKER CONTAINER EXTENSIONS
-
-## Setting up local preview
 
 When using the local preview, anytime you change any file in your local copy of
 the `/docs` directory and hit save, the site automatically rebuilds to reflect your changes!
@@ -70,7 +82,7 @@ and clone the repo.
       ```
 
     - **Local Preview with Dirty Reload**
-    If you’re only changing a single page in the `/docs/` folder that is not the homepage or `nav.yml`, adding the flag `--dirtyreload` makes the site rebuild super crazy insta-fast.
+    If you’re only changing a single page in the `/docs/` folder that is not the homepage or `nav.yml`, adding the flag `--dirtyreload` makes the site rebuild faster.
 
       ```
       mkdocs serve --dirtyreload

hack/docker/Dockerfile

@@ -8,5 +8,3 @@ COPY ./requirements.txt /site/
 
 # Python Dependencies
 RUN pip --no-cache-dir install -r requirements.txt
-# NodeJS Dependencies
-RUN npm ci

hack/docker/build.sh

@@ -1,10 +0,0 @@
-#!/usr/bin/env sh
-
-set -x
-
-IMAGE=${1:-knative-docs-dev}
-
-SCRIPT_DIR=$(cd $(dirname $0); pwd -P)
-ROOT_DIR=$(cd "${SCRIPT_DIR}/../.."; pwd -P)
-
-docker build -t ${IMAGE} -f ${SCRIPT_DIR}/Dockerfile ${ROOT_DIR}

hack/docker/logs.sh

@@ -1,6 +0,0 @@
-#!/usr/bin/env sh
-
-set -x
-
-NAME=${1:-knative-docs-dev}
-docker logs -f ${NAME}

hack/docker/run.sh

@@ -4,9 +4,10 @@ set -x
 
 NAME=${1:-knative-docs-dev}
 PORT=${2:-8000}
-IMAGE=${3:-knative-docs-dev}
+IMAGE=${3:-ghcr.io/knative/knative-docs:latest}
+
+docker rm "${NAME}" --force 1> /dev/null 2> /dev/null
 
 docker run --name "${NAME}" -d -p "${PORT}:8000" -v "${PWD}:/site" ${IMAGE} serve --dirtyreload --dev-addr=0.0.0.0:8000
 echo "Dev environment running with live reloading enabled. Open http://localhost:${PORT} to see the site"
-echo "For live logs run:"
+docker logs -f ${NAME}
-echo "docker logs -f ${NAME}"

hack/docker/test.sh

@@ -4,6 +4,6 @@ set -x
 
 NAME=${1:-knative-docs-dev}
 PORT=${2:-8000}
-IMAGE=${3:-knative-docs-dev}
+IMAGE=${3:-ghcr.io/knative/knative-docs:latest}
 
 docker run --rm -v "${PWD}:/site" -it --entrypoint "" ${IMAGE} hack/build.sh

package.json

@@ -1,36 +0,0 @@
-{
-  "name": "knative",
-  "version": "0.1.0",
-  "description": "Knative docs",
-  "main": "index.js",
-  "devDependencies": {
-    "autoprefixer": "^10.2.6",
-    "http-server": "^0.12.3",
-    "postcss-cli": "^8.3.1"
-  },
-  "scripts": {
-    "predev": "./hack/docker/clean.sh knative-docs-dev",
-    "dev": "./hack/docker/run.sh knative-docs-dev 8000",
-    "postdev": "./hack/docker/logs.sh knative-docs-dev",
-    "dev:stop": "./hack/docker/clean.sh knative-docs-dev",
-    "dev:build": "./hack/docker/build.sh knative-docs-dev",
-    "serve": "./hack/mkdocs.sh",
-    "test": "./hack/docker/test.sh && exit 1"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/knative/docs.git"
-  },
-  "author": "",
-  "license": "ISC",
-  "bugs": {
-    "url": "https://github.com/knative/docs/issues"
-  },
-  "homepage": "https://knative.dev",
-  "engines": {
-    "node": ">12.0"
-  },
-  "dependencies": {
-    "postcss": "^8.3.0"
-  }
-}