Add shortcode to embed sections of code files (#1596)

* Add code snippet shortcode

* Add docs on shortcode

daprdocs/content/en/contributing/contributing-docs.md

@@ -219,6 +219,102 @@ brew install dapr/tap/dapr-cli
 
 {{< /tabs >}}
 
+### Embedded code snippets
+
+Use the `code-snippet` shortcode to reference code snippets from the `static/code` directory.
+
+```
+{{</* code-snippet file="myfile.py" lang="python" */>}}
+```
+
+{{% alert title="Warning" color="warning" %}}
+All Dapr sample code should be self-contained in separate files, not in markdown. Use the techniques described here to highlight the parts of the sample code users should focus on.
+{{% /alert %}}
+
+Use the `lang` (default `txt`) parameter to configure the language used for syntax highlighting.
+
+Use the `marker` parameter to limit the embedded snipped to a portion of the sample file. This is useful when you want to show just a portion of a larger file. The typical way to do this is surround the interesting code with comments, and then pass the comment text into `marker`.
+
+The shortcode below and code sample:
+
+```
+{{</* code-snippet file="./contributing-1.py" lang="python" marker="#SAMPLE" */>}}
+```
+
+```python
+import json
+import time
+
+from dapr.clients import DaprClient
+
+#SAMPLE
+with DaprClient() as d:
+    req_data = {
+        'id': 1,
+        'message': 'hello world'
+    }
+
+    while True:
+        # Create a typed message with content type and body
+        resp = d.invoke_method(
+            'invoke-receiver',
+            'my-method',
+            data=json.dumps(req_data),
+        )
+
+        # Print the response
+        print(resp.content_type, flush=True)
+        print(resp.text(), flush=True)
+
+        time.sleep(2)
+#SAMPLE
+```
+
+Will result in the following output:
+
+{{< code-snippet file="contributing-1.py" lang="python" marker="#SAMPLE" >}}
+
+Use the `replace-key-[token]` and `replace-value-[token]` parameters to limit the embedded snipped to a portion of the sample file. This is useful when you want abbreviate a portion of the code sample. Multiple replacements are supported with multiple values of `token`. 
+
+The shortcode below and code sample:
+
+```
+{{</* code-snippet file="./contributing-2.py" lang="python" replace-key-imports="#IMPORTS" replace-value-imports="# Import statements"  */>}}
+```
+
+```python
+#IMPORTS
+import json
+import time
+#IMPORTS
+
+from dapr.clients import DaprClient
+
+with DaprClient() as d:
+    req_data = {
+        'id': 1,
+        'message': 'hello world'
+    }
+
+    while True:
+        # Create a typed message with content type and body
+        resp = d.invoke_method(
+            'invoke-receiver',
+            'my-method',
+            data=json.dumps(req_data),
+        )
+
+        # Print the response
+        print(resp.content_type, flush=True)
+        print(resp.text(), flush=True)
+
+        time.sleep(2)
+```
+
+Will result in the following output:
+
+{{< code-snippet file="./contributing-2.py" lang="python" replace-key-imports="#IMPORTS" replace-value-imports="# Import statements"  >}}
+
 ### YouTube videos
 Hugo can automatically embed YouTube videos using a shortcode:
 ```

daprdocs/layouts/shortcodes/code-snippet.html

@@ -0,0 +1,23 @@
+{{ $file := .Get "file" }}
+{{ $filePath := (path.Join "/static/code/" $file ) }}
+{{ $fileContents := $filePath | readFile }}
+{{ $lang := .Get "lang" | default "txt" }}
+{{ $embed := .Get "embed" | default true }}
+{{ if $embed }}
+{{ if isset .Params "marker" }}
+    {{ $marker := .Get "marker" }}
+    {{ $regex := printf "(?s).*%s%s%s.*" $marker `(\n)?(?P<inner>.*?)(\n\s+)?` $marker }}
+    {{ $fileContents = replaceRE $regex "$inner" $fileContents}}
+{{ end }}
+{{ range $key, $value := $.Params }}
+    {{ if hasPrefix $key "replace-key" }}
+        {{ $replace := $value }}
+        {{ $replaceValueParameter := printf "replace-value-%s" (slicestr $key (len "replace-key-")) }}
+        <p>{{ $replaceValueParameter }}</p>
+        {{ $replaceWith := index $.Params $replaceValueParameter }}
+        {{ $regex := printf "(?s)%s%s%s" $replace `(\n)?(?P<inner>.*?)(\n\s+)?` $replace }}
+        {{ $fileContents = replaceRE $regex $replaceWith $fileContents}}
+    {{ end }}
+{{ end }}
+{{ (print "```" $lang "\n" $fileContents "\n```") | markdownify }}
+{{ end }}

daprdocs/static/code/contributing-1.py

@@ -0,0 +1,26 @@
+import json
+import time
+
+from dapr.clients import DaprClient
+
+#SAMPLE
+with DaprClient() as d:
+    req_data = {
+        'id': 1,
+        'message': 'hello world'
+    }
+
+    while True:
+        # Create a typed message with content type and body
+        resp = d.invoke_method(
+            'invoke-receiver',
+            'my-method',
+            data=json.dumps(req_data),
+        )
+
+        # Print the response
+        print(resp.content_type, flush=True)
+        print(resp.text(), flush=True)
+
+        time.sleep(2)
+#SAMPLE

daprdocs/static/code/contributing-2.py

@@ -0,0 +1,26 @@
+#IMPORTS
+import json
+import time
+#IMPORTS
+
+from dapr.clients import DaprClient
+
+with DaprClient() as d:
+    req_data = {
+        'id': 1,
+        'message': 'hello world'
+    }
+
+    while True:
+        # Create a typed message with content type and body
+        resp = d.invoke_method(
+            'invoke-receiver',
+            'my-method',
+            data=json.dumps(req_data),
+        )
+
+        # Print the response
+        print(resp.content_type, flush=True)
+        print(resp.text(), flush=True)
+
+        time.sleep(2)