Move standalone examples to a new top-level section (#10794)

**What this PR does / why we need it**:

Moves the standalone examples inside the _Configuration_ section to a
new top-level _Examples_ section.
We can use this section to add more examples in the future.

---------

Co-authored-by: Ashwanth <iamashwanth@gmail.com>
Co-authored-by: J Stickler <julie.stickler@grafana.com>

Makefile

@@ -786,33 +786,34 @@ check-doc: doc
 ###################
 # Example Configs #
 ###################
-CONFIG_DOC_PATH := $(DOC_SOURCES_PATH)/configure
+EXAMPLES_DOC_PATH := $(DOC_SOURCES_PATH)/configure/examples
-CONFIG_EXAMPLES_PATH := $(CONFIG_DOC_PATH)/examples
+EXAMPLES_DOC_OUTPUT_PATH := $(EXAMPLES_DOC_PATH)/configuration-examples.md
-CONFIG_EXAMPLES_SKIP_VALIDATION_FLAG := "doc-example:skip-validation=true"
+EXAMPLES_YAML_PATH := $(EXAMPLES_DOC_PATH)/yaml
+EXAMPLES_SKIP_VALIDATION_FLAG := "doc-example:skip-validation=true"
 
 # Validate the example configurations that we provide in ./docs/sources/configure/examples
 # We run the validation only for complete examples, not snippets.
 # Complete examples should contain "Example" in their file name.
 validate-example-configs: loki
-	for f in $$(grep -rL $(CONFIG_EXAMPLES_SKIP_VALIDATION_FLAG) $(CONFIG_EXAMPLES_PATH)/*.yaml); do echo "Validating provided example config: $$f" && ./cmd/loki/loki -config.file=$$f -verify-config || exit 1; done
+	for f in $$(grep -rL $(EXAMPLES_SKIP_VALIDATION_FLAG) $(EXAMPLES_YAML_PATH)/*.yaml); do echo "Validating provided example config: $$f" && ./cmd/loki/loki -config.file=$$f -verify-config || exit 1; done
 
 # Dynamically generate ./docs/sources/configure/examples.md using the example configs that we provide.
 # This target should be run if any of our example configs change.
 generate-example-config-doc:
-	echo "Removing existing doc at $(CONFIG_DOC_PATH)/examples.md and re-generating. . ."
+	echo "Removing existing doc at $(EXAMPLES_DOC_OUTPUT_PATH) and re-generating. . ."
 	# Title and Heading
-	echo -e "---\ntitle: Examples\ndescription: Loki Configuration Examples\n---\n # Examples" > $(CONFIG_DOC_PATH)/examples.md
+	echo -e "---\ntitle: Configuration\ndescription: Loki Configuration Examples and Snippets\nweight:  100\n---\n# Configuration" > $(EXAMPLES_DOC_OUTPUT_PATH)
 	# Append each configuration and its file name to examples.md
-	for f in $$(find $(CONFIG_EXAMPLES_PATH)/*.yaml -printf "%f\n" | sort -k1n); do \
+	for f in $$(find $(EXAMPLES_YAML_PATH)/*.yaml -printf "%f\n" | sort -k1n); do \
-		echo -e "\n## $$f\n\n\`\`\`yaml\n" >> $(CONFIG_DOC_PATH)/examples.md; \
+		echo -e "\n## $$f\n\n\`\`\`yaml\n" >> $(EXAMPLES_DOC_OUTPUT_PATH); \
-		grep -v $(CONFIG_EXAMPLES_SKIP_VALIDATION_FLAG) $(CONFIG_EXAMPLES_PATH)/$$f >> $(CONFIG_DOC_PATH)/examples.md; \
+		grep -v $(EXAMPLES_SKIP_VALIDATION_FLAG) $(EXAMPLES_YAML_PATH)/$$f >> $(EXAMPLES_DOC_OUTPUT_PATH); \
-		echo -e "\n\`\`\`\n" >> $(CONFIG_DOC_PATH)/examples.md; \
+		echo -e "\n\`\`\`\n" >> $(EXAMPLES_DOC_OUTPUT_PATH); \
 	done
 
 
 # Fail our CI build if changes are made to example configurations but our doc is not updated
 check-example-config-doc: generate-example-config-doc
-	@if ! (git diff --exit-code ./docs/sources/configure/examples.md); then \
+	@if ! (git diff --exit-code $(EXAMPLES_DOC_OUTPUT_PATH)); then \
 		echo -e "\nChanges found in generated example configuration doc"; \
 		echo "Run 'make generate-example-config-doc' and commit the changes to fix this error."; \
 		echo "If you are actively developing these files you can ignore this error"; \

docs/sources/configure/_index.md

@@ -15,7 +15,7 @@ Grafana Loki is configured in a YAML file (usually referred to as `loki.yaml` )
 which contains information on the Loki server and its individual components,
 depending on which mode Loki is launched in.
 
-Configuration examples can be found in the [Configuration Examples]({{< relref "./examples" >}}) document.
+Configuration examples can be found in the [Configuration Examples]({{< relref "./examples/configuration-examples" >}}) document.
 
 ## Printing Loki config at runtime
 

docs/sources/configure/examples/_index.md

@@ -0,0 +1,13 @@
+---
+title: Examples
+menuTitle: Examples
+description: Examples to help you run Grafana Loki.
+weight: 800
+---
+
+# Examples
+
+The following pages contain examples of how to configure Grafana Loki.
+
+- [Configuration snippets and ready-to-use configuration examples]({{< relref "./configuration-examples" >}}).
+- [Deploy a query frontend on a existing cluster]({{< relref "./query-frontend" >}}).

docs/sources/configure/examples/configuration-examples.md

@@ -1,8 +1,9 @@
 ---
-title: Examples
+title: Configuration
-description: Loki Configuration Examples
+description: Loki Configuration Examples and Snippets
+weight:  100
 ---
- # Examples
+# Configuration
 
 ## 1-Local-Configuration-Example.yaml
 

docs/sources/configure/examples/query-frontend.md

@@ -1,10 +1,7 @@
 ---
 title: Query frontend example
 menuTitle:  
-description: Kubernetes query frontent example.
+description: Kubernetes query frontend example.
-aliases: 
-  - ../configuration/query-frontend/
-  - ../configure/query-frontend/
 weight:  200
 ---
 # Query frontend example

docs/sources/configure/index.template

@@ -15,7 +15,7 @@ Grafana Loki is configured in a YAML file (usually referred to as `loki.yaml` )
 which contains information on the Loki server and its individual components,
 depending on which mode Loki is launched in.
 
-Configuration examples can be found in the [Configuration Examples]({{ `{{< relref "./examples" >}}` }}) document.
+Configuration examples can be found in the [Configuration Examples]({{ `{{< relref "./examples/configuration-examples" >}}` }}) document.
 
 ## Printing Loki config at runtime