Enhance the index page of docs (#14)

Noah Lee · web-flow · commit 277d32ac9de3 · 2022-01-23T21:55:40.000+09:00
diff --git a/docs/concepts/deploy.yml.md b/docs/concepts/deploy.yml.md
@@ -12,8 +12,7 @@ Gitploy configures a pipeline with a simple, easy‑to‑read file that you comm
 
 If you want to get started quickly, you should click the *New Configuration* link, copy the `deploy.yml` file, and push it into your git repository. Then you can find the `production` environment in Gitploy.
 
-```yaml
-# deploy.yml
+```yaml title="deploy.yml"
 envs:
   - name: production
     auto_merge: false
@@ -28,7 +27,7 @@ envs:
 
 For multi-environment, Gitploy provides you can make different pipelines for each environment, respectively. The configuration has to be defined under the `envs` field. The following example shows each environment has a different configuration.
 
-```yaml
+```yaml title="deploy.yml"
 envs:
   # Development environment
   - name: development
@@ -47,7 +46,7 @@ envs:
 
 Internally, Gitploy posts a deployment to GitHub [deployments API](https://docs.github.com/en/rest/reference/repos#create-a-deployment) with parameters from the configuration file. These parameters help you can verify the artifact before you start to deploy.  The configuration provides fields to set all parameters of GitHub deployment API. You can check the [document](../references/deploy.yml.md) for the detail.
 
-```yaml
+```yaml title="deploy.yml"
 envs:
   - name: production
     task: deploy:lambda
@@ -63,7 +62,7 @@ envs:
 
 Gitploy provides not only manual deployment but also auto-deployment. Gitploy is listening for the push event dispatched from GitHub and triggers to deploy automatically when the ref is matched with the `auto_deploy_on` of the configuration file. 
 
-```yaml
+```yaml title="deploy.yml"
 envs:
   - name: production
     auto_deploy_on: refs/heads/main
@@ -74,7 +73,7 @@ envs:
 
 Gitploy support to add a window to prevent unintended deployment for the environment. You can freeze a window periodically by a cron expression.
 
-```yaml
+```yaml title="deploy.yml"
 envs:
   - name: production
     frozen_windows:
@@ -92,7 +91,7 @@ envs:
 
 Gitploy provides the review process. You can list up to users on the configuration file. You can check the [document](./review.md) for the detail.
 
-```yaml
+```yaml title="deploy.yml"
 envs:
   - name: production
     review:
diff --git a/docs/concepts/review.md b/docs/concepts/review.md
@@ -10,7 +10,7 @@ Gitploy has the review to require at least one approval for the deployment. You
 
 1\. To enable review, you must configure the `review` field first.
 
-```yaml
+```yaml title="deploy.yml"
 envs:
   - name: production
     review:
diff --git a/docs/index.md b/docs/index.md
@@ -1,13 +1,46 @@
 ---
 sidebar_position: 1
+title: What is Gitploy?
 ---
 
-# Gitploy
 
-## What is Gitploy?
+![Gitploy](../static/img/docs/gitploy.gif)
 
-GitHub provides the [deployment API](https://docs.github.com/en/rest/reference/deployments#deployments) to deploy a specific ref(branch, SHA, tag). It offers strong features to make your team (or organization) can deploy fast and safely. But it takes a lot of resources to build the deployment system around GitHub deployment API. 
+Gitploy is the tooling that helps your organization build the deployment system in minutes. It enables your organization **to deploy in the same manner** without worrying about the details of different types of applications and **to deploy differently** for each application, respectively. And as a result, your organization can get a robust system to deploy fast and safely. 🚀
 
-Gitploy makes your team or organization build the deployment system around GitHub in minutes. Now, do not waste time building the deployment system.
+## Deploy in the same manner
 
-![Gitploy](../static/img/docs/gitploy.gif)
+An organization has different types of applications, and it needs different deployment toolings for each application. For example, if an organization uses the Kubernetes for servers and the S3 for static websites, they generally choose different toolings. In my case, I used to choose Spinnaker for Kubernetes and CI tools (Ex. GitHub Action) for S3.
+
+But multiple tooling has a risk of increasing the complexity of the system. It costs users who want to deploy to learn because each tooling has a different interface. And also, it is hard to manage distributed deployments in one place. If an organization needs it, they should collect and aggregate it by themselves.
+
+Gitploy resolves the complexity perfectly in minutes. It always provides **the way to deploy in the same manner.** The users who want to deploy don't need to know which infrastructure they deploy or which toolings they use anymore. They just deploy what they want and check how it goes.
+
+Gitploy provides an intuitive UI similar to GitHub. Users can select one of the commits, branches, or tags to deploy and follow up on the deployment status.
+
+## Deploy differently
+
+Each application needs a customizable pipeline. If an organization has essential applications to deploy carefully, it should enforce a gateway like a review or deploy freeze window. And an organization chooses continuous delivery or continuous deployment for application.
+ 
+Gitploy provides a way **to configure a pipeline with a simple, easy‑to‑read file for each repository (each environment).** The default path is `deploy.yml` at the root directory, but you can replace the file path in the settings tab of Gitploy. 
+
+```yaml title="deploy.yml"
+envs:
+  - name: production
+    task: deploy:kubernetes
+    # Verify that the format of ref is the semantic versioning.
+    deployable_ref: 'v.*\..*\..*'
+    # Check the Docker image exists.
+    required_contexts:
+      - "publish-image"
+    # Collect the metrics
+    production_environment: true
+    # Enable review
+    review:
+      enabled: true
+      reviewers: 
+        - octocat
+```
+
+
+Currently, Gitploy provides powerful options such as *`ref` verification*, *continuous delivery vs continuous deployment*, and *review*. You can check the documentation for the detail.
diff --git a/docs/tasks/usecases.md b/docs/tasks/usecases.md
@@ -8,7 +8,7 @@ sidebar_position: 3
 
 The general way of deployment is deploying the head of the `main` branch that has only verified commits. To constrain deploying only the head of the `main` branch, we can use the `auto_merge` parameter of GitHub [deployment API](https://docs.github.com/en/rest/reference/repos#create-a-deployment) to ensure that the deployment is the head of the branch, and set `deployable_ref` field with the `main`.
 
-```yaml
+```yaml title="deploy.yml"
 envs:
   - name: production
     auto_merge: true
@@ -20,7 +20,7 @@ envs:
 
 The versioning is the general way to specify the artifact or the commit, and GitHub provides the release page for versioning. If your team (or organization) wants to constrain deploying with the version, you can use the `deployable_ref` field like below.
 
-```yaml
+```yaml title="deploy.yml"
 envs:
   - name: production
     auto_merge: false
@@ -32,7 +32,7 @@ envs:
 
 The artifact could be a binary file from compiling source codes or a docker image, which means we have to build the artifact before we deploy. The commit status is the best way to verify if the artifact exists or not. The builder, such as GitHub Action or Circle CI, posts the commit status after building the artifact, and we can verify it by the `required_contexts` parameter when we deploy. You can reference the `deploy.yml` of Gitploy.
 
-```yaml
+```yaml title="deploy.yml"
 envs:
   - name: production
     auto_merge: false
@@ -45,7 +45,7 @@ envs:
 
 If you want to enable the auto-deployment when the pull request is merged into the main branch, you should configure the `auto_deploy_on` field like the below.
 
-```yaml
+```yaml title="deploy.yml"
 envs:
   - name: production
     auto_merge: true
