Use code snippets for code examples

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "kudo"]
+	path = kudo
+	url = https://github.com/kudobuilder/kudo.git

content/.vuepress/config.js

@@ -76,6 +76,7 @@ module.exports = {
         lineNumbers: false,
         extendMarkdown: md => {
             md.use(require('markdown-it-footnote'))
+            md.use(require('markdown-it-vuepress-code-snippet-enhanced'))
         }
     },
     plugins: [

content/docs/developing-operators.md

@@ -20,61 +20,17 @@ The `operator.yaml` is the main YAML file defining both operator metadata as the
 ### Your First KUDO Operator
 First let’s create `operator.yaml` and place it in a `first-operator` folder.
 
-```yaml
-name: "first-operator"
-version: "0.1.0"
-maintainers:
-- Your name <[email protected]>
-url: https://kudo.dev
-tasks:
-  nginx:
-    resources:
-      - deployment.yaml
-plans:
-  deploy:
-    strategy: serial
-    phases:
-      - name: main
-        strategy: parallel
-        steps:
-          - name: everything
-            tasks:
-              - nginx
-```
+@[code](@/kudo/config/samples/first-operator/operator.yaml)
 
 This is an operator with just one plan `deploy`, which has one phase and one step and represents the minimal setup. The `deploy` plan is automatically triggered when you install instance of this operator into cluster.
 
 You can see that the task `nginx` references the resource `deployment.yaml`. KUDO expects this file to exist inside the `templates` folder. As the next step, create `templates/deployment.yaml`:
 
-```yaml
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: nginx-deployment
-spec:
-  selector:
-    matchLabels:
-      app: nginx
-  replicas: {{ .Params.Replicas }} # tells deployment to run X pods matching the template
-  template:
-    metadata:
-      labels:
-        app: nginx
-    spec:
-      containers:
-        - name: nginx
-          image: nginx:1.7.9
-          ports:
-            - containerPort: 80
-```
+@[code](@/kudo/config/samples/first-operator/templates/deployment.yaml)
 
 This is a pretty normal Kubernetes YAML file defining a deployment. However, you can already see the KUDO templating language in action on the line referencing `.Params.Replicas`. This will get substituted during installation by merging what is in `params.yaml` and overrides defined before install. So let’s define the last missing piece, `params.yaml`.
 
-```yaml
-replicas:
-  description: Number of replicas that should be run as part of the deployment
-  default: 2
-```
+@[code](@/kudo/config/samples/first-operator/params.yaml)
 
 Now your first operator is ready and you can install it to your cluster. You can do this by invoking `kubectl kudo install ./first-operator` where `./first-operator` is a relative path to the folder containing your operator. To do this, you need to have the KUDO CLI installed - [follow the instructions here](cli.md), if you haven't already.
 
@@ -90,31 +46,15 @@ kubectl kudo install ./config/samples/first-operator
 
 This is the main piece of every operator. It consists of two main parts. First one defines metadata about your operator.
 
-```yaml
-name: operator
-description: my first super awesome operator
-version: "5.7"
-kudoVersion: ">= 0.2.0"
-kubernetesVersion: ">= 1.14"
-maintainers:
-  - Bob <[email protected]>
-  - Alice <[email protected]>
-url: https://github.com/myoperator/myoperator
-```
+@[code transclude={1-5}](@/kudo/config/samples/first-operator/operator.yaml)
 
 Most of these are provided as a form of documentation. `kudoVersion` and `kubernetesVersion` use semver constraints to define minimal or maximal version of Kubernetes or KUDO that this operator supports. Under the hood, we use [this library](https://github.com/Masterminds/semver) to evaluate the constraints.
 
 ### Tasks Section
 
-Another part of `operator.yaml` is the tasks section. Tasks are the smallest pieces of work that get executed together. You usually group Kubernetes manifests that should be applied at once into one task. An example can be a deploy task that will result in `config.yaml` and `pod.yaml` being applied to your cluster.
+Another part of `operator.yaml` is the tasks section. Tasks are the smallest pieces of work that get executed together. You usually group Kubernetes manifests that should be applied at once into one task. An example can be an app that will result in `deployment.yaml` being applied to your cluster.
 
-```yaml
-tasks:
-  deploy-task:
-    resources:
-      - config.yaml
-      - pod.yaml
-```
+@[code transclude={6-9}](@/kudo/config/samples/first-operator/operator.yaml)
 
 ### Plans Section
 
@@ -136,22 +76,11 @@ Plan foo
 
 Plans consists of one or more `phases`. `Phases` consists of one or more `steps`. `Steps` contain one or more `tasks` (those are defined in the section we talked about in the last paragraph). Both phases and also steps can be configured with an execution `strategy`, either `serial` or `parallel`.
 
-The sample has a `deploy` plan with a `deploy-phase` and a `deploy-step`. From the `deploy-step` the `deploy-task` is referenced. This task gets executed when an instance is created using the operator.
+The sample has a `deploy` plan with a phase `main` and a step `everything`. From `everything` the `app` is referenced. This task gets executed when an instance is created using the operator.
 
 At the same time, `deploy` plan is the most important plan within your operator because that is the default plan that every operator has to have and also the plan that gets executed when you install an instance of your operator into the cluster. Another important plan that you might consider having is `update` (run when instance metadata is updated) or `upgrade` (run when instance is upgraded from one version of the operator to another). If you don't provide `update` and/or `upgrade` plans for your operator, the fallback is always `deploy`.
-
-```yaml
-plans:
-  deploy:
-    strategy: serial
-    phases:
-      - name: deploy-phase
-        strategy: parallel
-        steps:
-          - name: deploy-step
-            tasks:
-              - deploy-task
-```
+
+@[code transclude={10-19}](@/kudo/config/samples/first-operator/operator.yaml)
 
 Plans allow operators to see what the operator is currently doing, and to visualize the broader operation such as for a config rollout. The fixed structure of that information meanwhile makes it straightforward to build UIs and tooling on top.
 

package.json

@@ -11,6 +11,7 @@
   "dependencies": {
     "axios": "^0.19.0",
     "markdown-it-footnote": "^3.0.2",
+    "markdown-it-vuepress-code-snippet-enhanced": "^1.0.1",
     "vuepress-plugin-container": "^2.0.2"
   }
 }

yarn.lock

@@ -4307,6 +4307,11 @@ markdown-it-table-of-contents@^0.4.0:
   resolved "https://registry.yarnpkg.com/markdown-it-table-of-contents/-/markdown-it-table-of-contents-0.4.4.tgz#3dc7ce8b8fc17e5981c77cc398d1782319f37fbc"
   integrity sha512-TAIHTHPwa9+ltKvKPWulm/beozQU41Ab+FIefRaQV1NRnpzwcV9QOe6wXQS5WLivm5Q/nlo0rl6laGkMDZE7Gw==
 
+markdown-it-vuepress-code-snippet-enhanced@^1.0.1:
+  version "1.0.1"
+  resolved "https://registry.yarnpkg.com/markdown-it-vuepress-code-snippet-enhanced/-/markdown-it-vuepress-code-snippet-enhanced-1.0.1.tgz#516fda41378ab537453a0f64fc8ec8d80add0518"
+  integrity sha512-CfDWHyRWuNwvBIAQTXnlZVKRGxnOo82tnFrzxn2XLoI4jAK2mn1iNNQSyXB9ouxJKDn1YChHevnIG1woUi/g/g==
+
 markdown-it@^8.4.1:
   version "8.4.2"
   resolved "https://registry.yarnpkg.com/markdown-it/-/markdown-it-8.4.2.tgz#386f98998dc15a37722aa7722084f4020bdd9b54"