From 1f025bf6c92bbff0cd63e095101f2a9acb6f1e01 Mon Sep 17 00:00:00 2001 From: Sean Packham Date: Thu, 29 Aug 2024 11:13:44 +0100 Subject: [PATCH 01/18] Add grot guide docs --- docs/sources/write/shortcodes/index.md | 115 +++++++++++++++++++++++++ 1 file changed, 115 insertions(+) diff --git a/docs/sources/write/shortcodes/index.md b/docs/sources/write/shortcodes/index.md index ee6a9edb..2acdaeca 100644 --- a/docs/sources/write/shortcodes/index.md +++ b/docs/sources/write/shortcodes/index.md @@ -333,6 +333,121 @@ compactor: {{< /collapse >}} +## Guide + +The `guide` shortcode embeds a Grot guide into the docs that people can follow to get help and guidance on topics and directed to the right documentation resources. + +```markdown +{{< guide name="instrument" title="title" text="text" button="button" >}} +``` + +The website looks up guide Markdown files from the website repository in the `content/guides` folder. The shortcode accepts the following parameters: + +| Parameter | Description | Required | +| --------- | --------------------------------------------------------------------------- | -------- | +| `name` | The name of the guide Markdown file in the website `content/guides` folder. | yes | +| `title` | A custom guide title to override the default guide title. | no | +| `text` | Custom body text to override the default guide text. | no | +| `button` | Custom button copy to override the default guide button copy. | no | + +If you don't set custom title, text, and button values, the guide introduction screen will use the following default text: + +![Grot guide introduction screen with default copy](https://grafana.com/media/docs/writers-toolkit/grot-guide.png) + +Guide content consists of various YAML structures in Markdown front matter for the guide meta, header, welcome, and screens. + +### Meta + +Customize the `name`, `api`, and `title` fields, and leave the rest as is: + +```yaml +# name that matches the filename and name used to embed +name: instrument +# match the name field +api: instrument +title: Applicating Instrumentation +type: guides +layout: single +# Hugo rendering options +_build: + render: false + list: true +``` + +### Header + +The header structure defines the guide's image and image spacing: + +```yaml +header: + image: + src: /media/guides/grafana-guides-whichgrafana-header.svg + alt: Grot metrics wizard + width: 221 + height: 131 +``` + +### Welcome + +A guide needs a single welcome object, defined with a `welcome` field and the following attributes. Define a list of `ctas` with at least one item which points to the next `screen_id`. + +```yaml +welcome: + type: welcome + title: Let's get started with application instrumentation + body: Answer a few questions and Grot can help you find the documentation you need to instrument your application. + ctas: + - text: Let's go! + screen_id: instrument +``` + +### Screens + +Define subsequent screens as a list of objects under a `screens` field: + +```yaml +screens: + - type: question + id: ... + + - type: result + id: ... +``` + +#### Question screen + +A question screen is a branch node in a decision tree and presents one or many options to further screens. A question screen has the following structure: + +```yaml +- type: question + id: instrument + title: What programming language do you want to instrument? + options: + - text: JVM (Java, Scala, Kotlin) + screen_id: jvm + - text: .Net + screen_id: dotnet + - text: Node.js + screen_id: nodejs +``` + +### Result screen + +A result screen is a leaf node in a decision tree and terminates with one or many links. A question screen has the following structure: + +```yaml + - type: result + id: beyla + title: Grafana Beyla + body: | + Grafana Beyla is a Linux eBPF kernel module application to auto-instrument applications without modifying them by monitoring an executable or port. + links: + - type: docs + title: Grafana Beyla + link_text: Visit docs page + href: /docs/beyla/latest/ +``` + ## Docs/alias The `docs/alias` shortcode determines the relative alias between two pages. From d0616ffce771c29a93dc8ddcefd10a6d14288a40 Mon Sep 17 00:00:00 2001 From: Sean Packham Date: Thu, 29 Aug 2024 11:38:26 +0100 Subject: [PATCH 02/18] Edit --- docs/sources/write/shortcodes/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sources/write/shortcodes/index.md b/docs/sources/write/shortcodes/index.md index 2acdaeca..ffd5dd10 100644 --- a/docs/sources/write/shortcodes/index.md +++ b/docs/sources/write/shortcodes/index.md @@ -335,10 +335,10 @@ compactor: ## Guide -The `guide` shortcode embeds a Grot guide into the docs that people can follow to get help and guidance on topics and directed to the right documentation resources. +The `guide` shortcode embeds a Grot guide into the docs that people can follow to get help and guidance on topics and direction to documentation resources. ```markdown -{{< guide name="instrument" title="title" text="text" button="button" >}} +{{}} ``` The website looks up guide Markdown files from the website repository in the `content/guides` folder. The shortcode accepts the following parameters: From 040fc00d12819d481b5c8aafefca1652fa1b44fd Mon Sep 17 00:00:00 2001 From: Sean Packham Date: Thu, 29 Aug 2024 12:16:00 +0100 Subject: [PATCH 03/18] shortcode params Co-authored-by: Jack Baldry --- docs/sources/write/shortcodes/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/write/shortcodes/index.md b/docs/sources/write/shortcodes/index.md index ffd5dd10..90220918 100644 --- a/docs/sources/write/shortcodes/index.md +++ b/docs/sources/write/shortcodes/index.md @@ -338,7 +338,7 @@ compactor: The `guide` shortcode embeds a Grot guide into the docs that people can follow to get help and guidance on topics and direction to documentation resources. ```markdown -{{}} +{{" title="" text="<TEXT>" button="<BUTTON>" */>}} ``` The website looks up guide Markdown files from the website repository in the `content/guides` folder. The shortcode accepts the following parameters: From d03b0a8ec8398e0addfa0965a0b62e315000526f Mon Sep 17 00:00:00 2001 From: Sean Packham <sean.packham@grafana.com> Date: Thu, 29 Aug 2024 12:16:51 +0100 Subject: [PATCH 04/18] Edit Co-authored-by: Jack Baldry <jack.baldry@grafana.com> --- docs/sources/write/shortcodes/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/write/shortcodes/index.md b/docs/sources/write/shortcodes/index.md index 90220918..0eae5374 100644 --- a/docs/sources/write/shortcodes/index.md +++ b/docs/sources/write/shortcodes/index.md @@ -350,7 +350,7 @@ The website looks up guide Markdown files from the website repository in the `co | `text` | Custom body text to override the default guide text. | no | | `button` | Custom button copy to override the default guide button copy. | no | -If you don't set custom title, text, and button values, the guide introduction screen will use the following default text: +If you don't set custom title, text, and button values, the guide introduction screen uses the following default text: ![Grot guide introduction screen with default copy](https://grafana.com/media/docs/writers-toolkit/grot-guide.png) From b6a9fd515a7ef10e24edf5eea300cfaaa44ba0ed Mon Sep 17 00:00:00 2001 From: Sean Packham <sean.packham@grafana.com> Date: Thu, 29 Aug 2024 12:17:02 +0100 Subject: [PATCH 05/18] Edit Co-authored-by: Jack Baldry <jack.baldry@grafana.com> --- docs/sources/write/shortcodes/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/sources/write/shortcodes/index.md b/docs/sources/write/shortcodes/index.md index 0eae5374..9e8f1fe9 100644 --- a/docs/sources/write/shortcodes/index.md +++ b/docs/sources/write/shortcodes/index.md @@ -341,7 +341,8 @@ The `guide` shortcode embeds a Grot guide into the docs that people can follow t {{</* guide name="<NAME>" title="<TITLE>" text="<TEXT>" button="<BUTTON>" */>}} ``` -The website looks up guide Markdown files from the website repository in the `content/guides` folder. The shortcode accepts the following parameters: +The website looks up guide Markdown files from the website repository in the `content/guides` directory. +The shortcode accepts the following parameters: | Parameter | Description | Required | | --------- | --------------------------------------------------------------------------- | -------- | From cfe514444571769bf8b47d652b7b69a194e7cf3a Mon Sep 17 00:00:00 2001 From: Sean Packham <sean.packham@grafana.com> Date: Thu, 29 Aug 2024 12:17:37 +0100 Subject: [PATCH 06/18] Edit Co-authored-by: Jack Baldry <jack.baldry@grafana.com> --- docs/sources/write/shortcodes/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/write/shortcodes/index.md b/docs/sources/write/shortcodes/index.md index 9e8f1fe9..a7ce40d9 100644 --- a/docs/sources/write/shortcodes/index.md +++ b/docs/sources/write/shortcodes/index.md @@ -335,7 +335,7 @@ compactor: ## Guide -The `guide` shortcode embeds a Grot guide into the docs that people can follow to get help and guidance on topics and direction to documentation resources. +The `guide` shortcode embeds a Grot guide into the documentation that people can follow to get help and guidance on topics and direction to documentation resources. ```markdown {{</* guide name="<NAME>" title="<TITLE>" text="<TEXT>" button="<BUTTON>" */>}} From f1b44fdafc70696cd7078e02e9461bfabbf99b77 Mon Sep 17 00:00:00 2001 From: Sean Packham <sean.packham@grafana.com> Date: Thu, 29 Aug 2024 12:39:53 +0100 Subject: [PATCH 07/18] Move to dedicated page --- docs/sources/write/grot-guides/index.md | 124 ++++++++++++++++++++++++ docs/sources/write/shortcodes/index.md | 116 ---------------------- 2 files changed, 124 insertions(+), 116 deletions(-) create mode 100644 docs/sources/write/grot-guides/index.md diff --git a/docs/sources/write/grot-guides/index.md b/docs/sources/write/grot-guides/index.md new file mode 100644 index 00000000..845e9712 --- /dev/null +++ b/docs/sources/write/grot-guides/index.md @@ -0,0 +1,124 @@ +--- +title: Grot guides +review_date: "2024-08-29" +description: Understand what Grot guides are and how to use them in your Markdown. +keywords: + - Hugo + - shortcodes +weight: 501 +--- + +# Grot guides + +The `guide` shortcode embeds a Grot guide into the docs that people can follow to get help and guidance on topics and direction to documentation resources. + +```markdown +{{</* guide name="instrument" title="title" text="text" button="button" */>}} +``` + +The website looks up guide Markdown files from the website repository in the `content/guides` folder. The shortcode accepts the following parameters: + +| Parameter | Description | Required | +| --------- | --------------------------------------------------------------------------- | -------- | +| `name` | The name of the guide Markdown file in the website `content/guides` folder. | yes | +| `title` | A custom guide title to override the default guide title. | no | +| `text` | Custom body text to override the default guide text. | no | +| `button` | Custom button copy to override the default guide button copy. | no | + +If you don't set custom title, text, and button values, the guide introduction screen uses the following default text: + +![Grot guide introduction screen with default copy](https://grafana.com/media/docs/writers-toolkit/grot-guide.png) + +Guide content consists of various YAML structures in Markdown front matter for the guide meta, header, welcome, and screens. + +## Meta + +Customize the `name`, `api`, and `title` fields, and leave the rest as is: + +```yaml +# name that matches the filename and name used to embed +name: instrument +# match the name field +api: instrument +title: Applicating Instrumentation +type: guides +layout: single +# Hugo rendering options +_build: + render: false + list: true +``` + +## Header + +The header structure defines the guide's image and image spacing: + +```yaml +header: + image: + src: /media/guides/grafana-guides-whichgrafana-header.svg + alt: Grot metrics wizard + width: 221 + height: 131 +``` + +## Welcome + +A guide needs a single welcome object, defined with a `welcome` field and the following attributes. Define a list of `ctas` with at least one item which points to the next `screen_id`. + +```yaml +welcome: + type: welcome + title: Let's get started with application instrumentation + body: Answer a few questions and Grot can help you find the documentation you need to instrument your application. + ctas: + - text: Let's go! + screen_id: instrument +``` + +## Screens + +Define subsequent screens as a list of objects under a `screens` field: + +```yaml +screens: + - type: question + id: ... + + - type: result + id: ... +``` + +### Question + +A question screen is a branch node in a decision tree and presents one or many options to further screens. A question screen has the following structure: + +```yaml +- type: question + id: instrument + title: What programming language do you want to instrument? + options: + - text: JVM (Java, Scala, Kotlin) + screen_id: jvm + - text: .Net + screen_id: dotnet + - text: Node.js + screen_id: nodejs +``` + +### Result + +A result screen is a leaf node in a decision tree and terminates with one or many links. A question screen has the following structure: + +```yaml + - type: result + id: beyla + title: Grafana Beyla + body: | + Grafana Beyla is a Linux eBPF kernel module application to auto-instrument applications without modifying them by monitoring an executable or port. + links: + - type: docs + title: Grafana Beyla + link_text: Visit docs page + href: /docs/beyla/latest/ +``` diff --git a/docs/sources/write/shortcodes/index.md b/docs/sources/write/shortcodes/index.md index a7ce40d9..ee6a9edb 100644 --- a/docs/sources/write/shortcodes/index.md +++ b/docs/sources/write/shortcodes/index.md @@ -333,122 +333,6 @@ compactor: {{< /collapse >}} -## Guide - -The `guide` shortcode embeds a Grot guide into the documentation that people can follow to get help and guidance on topics and direction to documentation resources. - -```markdown -{{</* guide name="<NAME>" title="<TITLE>" text="<TEXT>" button="<BUTTON>" */>}} -``` - -The website looks up guide Markdown files from the website repository in the `content/guides` directory. -The shortcode accepts the following parameters: - -| Parameter | Description | Required | -| --------- | --------------------------------------------------------------------------- | -------- | -| `name` | The name of the guide Markdown file in the website `content/guides` folder. | yes | -| `title` | A custom guide title to override the default guide title. | no | -| `text` | Custom body text to override the default guide text. | no | -| `button` | Custom button copy to override the default guide button copy. | no | - -If you don't set custom title, text, and button values, the guide introduction screen uses the following default text: - -![Grot guide introduction screen with default copy](https://grafana.com/media/docs/writers-toolkit/grot-guide.png) - -Guide content consists of various YAML structures in Markdown front matter for the guide meta, header, welcome, and screens. - -### Meta - -Customize the `name`, `api`, and `title` fields, and leave the rest as is: - -```yaml -# name that matches the filename and name used to embed -name: instrument -# match the name field -api: instrument -title: Applicating Instrumentation -type: guides -layout: single -# Hugo rendering options -_build: - render: false - list: true -``` - -### Header - -The header structure defines the guide's image and image spacing: - -```yaml -header: - image: - src: /media/guides/grafana-guides-whichgrafana-header.svg - alt: Grot metrics wizard - width: 221 - height: 131 -``` - -### Welcome - -A guide needs a single welcome object, defined with a `welcome` field and the following attributes. Define a list of `ctas` with at least one item which points to the next `screen_id`. - -```yaml -welcome: - type: welcome - title: Let's get started with application instrumentation - body: Answer a few questions and Grot can help you find the documentation you need to instrument your application. - ctas: - - text: Let's go! - screen_id: instrument -``` - -### Screens - -Define subsequent screens as a list of objects under a `screens` field: - -```yaml -screens: - - type: question - id: ... - - - type: result - id: ... -``` - -#### Question screen - -A question screen is a branch node in a decision tree and presents one or many options to further screens. A question screen has the following structure: - -```yaml -- type: question - id: instrument - title: What programming language do you want to instrument? - options: - - text: JVM (Java, Scala, Kotlin) - screen_id: jvm - - text: .Net - screen_id: dotnet - - text: Node.js - screen_id: nodejs -``` - -### Result screen - -A result screen is a leaf node in a decision tree and terminates with one or many links. A question screen has the following structure: - -```yaml - - type: result - id: beyla - title: Grafana Beyla - body: | - Grafana Beyla is a Linux eBPF kernel module application to auto-instrument applications without modifying them by monitoring an executable or port. - links: - - type: docs - title: Grafana Beyla - link_text: Visit docs page - href: /docs/beyla/latest/ -``` - ## Docs/alias The `docs/alias` shortcode determines the relative alias between two pages. From 1f28cfbc7f33f983ae65a5858a4d93d46691f5f7 Mon Sep 17 00:00:00 2001 From: Sean Packham <sean.packham@grafana.com> Date: Thu, 29 Aug 2024 13:14:33 +0100 Subject: [PATCH 08/18] Update docs/sources/write/grot-guides/index.md Co-authored-by: Jack Baldry <jack.baldry@grafana.com> --- docs/sources/write/grot-guides/index.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/sources/write/grot-guides/index.md b/docs/sources/write/grot-guides/index.md index 845e9712..8b3614b8 100644 --- a/docs/sources/write/grot-guides/index.md +++ b/docs/sources/write/grot-guides/index.md @@ -10,7 +10,9 @@ weight: 501 # Grot guides -The `guide` shortcode embeds a Grot guide into the docs that people can follow to get help and guidance on topics and direction to documentation resources. +Grot guides are interactive guides embedded in a documentation page that people can follow to get help and guidance on topics and direction to documentation resources. + +The [`guide` shortcode](/docs/writers-toolkit/write-shortcodes/#guide) embeds a Grot guide into a page. ```markdown {{</* guide name="instrument" title="title" text="text" button="button" */>}} From 90518d763374e4f1087e442738fd1144068337a5 Mon Sep 17 00:00:00 2001 From: Sean Packham <sean.packham@grafana.com> Date: Thu, 29 Aug 2024 13:14:49 +0100 Subject: [PATCH 09/18] Update docs/sources/write/grot-guides/index.md Co-authored-by: Jack Baldry <jack.baldry@grafana.com> --- docs/sources/write/grot-guides/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/write/grot-guides/index.md b/docs/sources/write/grot-guides/index.md index 8b3614b8..bfdd04e4 100644 --- a/docs/sources/write/grot-guides/index.md +++ b/docs/sources/write/grot-guides/index.md @@ -15,7 +15,7 @@ Grot guides are interactive guides embedded in a documentation page that people The [`guide` shortcode](/docs/writers-toolkit/write-shortcodes/#guide) embeds a Grot guide into a page. ```markdown -{{</* guide name="instrument" title="title" text="text" button="button" */>}} +{{</* guide name="<NAME>" title="<TITLE>" text="<TEXT>" button="<BUTTON>" */>}} ``` The website looks up guide Markdown files from the website repository in the `content/guides` folder. The shortcode accepts the following parameters: From 591dfc3a61ea9698cb220b6a4d99c144c547eefd Mon Sep 17 00:00:00 2001 From: Sean Packham <sean.packham@grafana.com> Date: Thu, 29 Aug 2024 13:42:09 +0100 Subject: [PATCH 10/18] Address feedback --- docs/sources/write/grot-guides/index.md | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/docs/sources/write/grot-guides/index.md b/docs/sources/write/grot-guides/index.md index bfdd04e4..5516da4d 100644 --- a/docs/sources/write/grot-guides/index.md +++ b/docs/sources/write/grot-guides/index.md @@ -31,18 +31,20 @@ If you don't set custom title, text, and button values, the guide introduction s ![Grot guide introduction screen with default copy](https://grafana.com/media/docs/writers-toolkit/grot-guide.png) +## Structure of a Grot guide + Guide content consists of various YAML structures in Markdown front matter for the guide meta, header, welcome, and screens. -## Meta +### Meta -Customize the `name`, `api`, and `title` fields, and leave the rest as is: +The meta sections covers general information about the guide. Customize the `name`, `api`, and `title` fields, and leave the rest as is: ```yaml # name that matches the filename and name used to embed -name: instrument +name: <GUIDE NAME> # match the name field -api: instrument -title: Applicating Instrumentation +api: <GUIDE NAME> +title: <GUIDE TITLE> type: guides layout: single # Hugo rendering options @@ -53,7 +55,7 @@ _build: ## Header -The header structure defines the guide's image and image spacing: +The header structure defines the guide's image and image spacing. The following example sets a `src`, `alt`, and image dimensions: ```yaml header: @@ -96,7 +98,10 @@ screens: A question screen is a branch node in a decision tree and presents one or many options to further screens. A question screen has the following structure: ```yaml -- type: question +screens: + ... + + - type: question id: instrument title: What programming language do you want to instrument? options: @@ -113,6 +118,9 @@ A question screen is a branch node in a decision tree and presents one or many o A result screen is a leaf node in a decision tree and terminates with one or many links. A question screen has the following structure: ```yaml +screens: + ... + - type: result id: beyla title: Grafana Beyla From 2b756b4eb1c4cc245bb6e4c1759c6270b1e5389f Mon Sep 17 00:00:00 2001 From: Sean Packham <sean.packham@grafana.com> Date: Thu, 29 Aug 2024 13:59:39 +0100 Subject: [PATCH 11/18] Update docs/sources/write/grot-guides/index.md Co-authored-by: Jack Baldry <jack.baldry@grafana.com> --- docs/sources/write/grot-guides/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/sources/write/grot-guides/index.md b/docs/sources/write/grot-guides/index.md index 5516da4d..2d5ae562 100644 --- a/docs/sources/write/grot-guides/index.md +++ b/docs/sources/write/grot-guides/index.md @@ -119,7 +119,6 @@ A result screen is a leaf node in a decision tree and terminates with one or man ```yaml screens: - ... - type: result id: beyla From 3e81ff4addea45d009b0014e7cd9c67b22643ee7 Mon Sep 17 00:00:00 2001 From: Sean Packham <sean.packham@grafana.com> Date: Thu, 29 Aug 2024 13:59:49 +0100 Subject: [PATCH 12/18] Update docs/sources/write/grot-guides/index.md Co-authored-by: Jack Baldry <jack.baldry@grafana.com> --- docs/sources/write/grot-guides/index.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/sources/write/grot-guides/index.md b/docs/sources/write/grot-guides/index.md index 2d5ae562..7d3ccef3 100644 --- a/docs/sources/write/grot-guides/index.md +++ b/docs/sources/write/grot-guides/index.md @@ -99,8 +99,6 @@ A question screen is a branch node in a decision tree and presents one or many o ```yaml screens: - ... - - type: question id: instrument title: What programming language do you want to instrument? From a8ad1b3a4520d1fb014a9f5161a77d1d7c21dc36 Mon Sep 17 00:00:00 2001 From: Sean Packham <sean.packham@grafana.com> Date: Thu, 29 Aug 2024 14:00:08 +0100 Subject: [PATCH 13/18] Update docs/sources/write/grot-guides/index.md Co-authored-by: Jack Baldry <jack.baldry@grafana.com> --- docs/sources/write/grot-guides/index.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/sources/write/grot-guides/index.md b/docs/sources/write/grot-guides/index.md index 7d3ccef3..3141c597 100644 --- a/docs/sources/write/grot-guides/index.md +++ b/docs/sources/write/grot-guides/index.md @@ -40,14 +40,11 @@ Guide content consists of various YAML structures in Markdown front matter for t The meta sections covers general information about the guide. Customize the `name`, `api`, and `title` fields, and leave the rest as is: ```yaml -# name that matches the filename and name used to embed name: <GUIDE NAME> -# match the name field api: <GUIDE NAME> title: <GUIDE TITLE> type: guides layout: single -# Hugo rendering options _build: render: false list: true From 3aa88ef7e8f496bddad9d8f0f1a409d24d341c1a Mon Sep 17 00:00:00 2001 From: Sean Packham <sean.packham@grafana.com> Date: Thu, 29 Aug 2024 14:01:14 +0100 Subject: [PATCH 14/18] Update docs/sources/write/grot-guides/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- docs/sources/write/grot-guides/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/sources/write/grot-guides/index.md b/docs/sources/write/grot-guides/index.md index 3141c597..7c5cd60b 100644 --- a/docs/sources/write/grot-guides/index.md +++ b/docs/sources/write/grot-guides/index.md @@ -114,7 +114,6 @@ A result screen is a leaf node in a decision tree and terminates with one or man ```yaml screens: - - type: result id: beyla title: Grafana Beyla From 11eeffa12176486f811418fdcda4fd690cb4b221 Mon Sep 17 00:00:00 2001 From: Sean Packham <sean.packham@grafana.com> Date: Thu, 29 Aug 2024 14:21:19 +0100 Subject: [PATCH 15/18] Update with templates --- docs/sources/write/grot-guides/index.md | 47 ++++++++++++------------- 1 file changed, 23 insertions(+), 24 deletions(-) diff --git a/docs/sources/write/grot-guides/index.md b/docs/sources/write/grot-guides/index.md index 7c5cd60b..4c1c23af 100644 --- a/docs/sources/write/grot-guides/index.md +++ b/docs/sources/write/grot-guides/index.md @@ -65,16 +65,16 @@ header: ## Welcome -A guide needs a single welcome object, defined with a `welcome` field and the following attributes. Define a list of `ctas` with at least one item which points to the next `screen_id`. +A guide needs a single welcome object, defined with a `welcome` field and the following attributes: ```yaml welcome: type: welcome - title: Let's get started with application instrumentation - body: Answer a few questions and Grot can help you find the documentation you need to instrument your application. + title: <WELCOME TITLE> + body: <WELCOME BODY> ctas: - - text: Let's go! - screen_id: instrument + - text: <CTA TEXT> + screen_id: <SCREEN ID TO LINK TO> ``` ## Screens @@ -84,44 +84,43 @@ Define subsequent screens as a list of objects under a `screens` field: ```yaml screens: - type: question - id: ... + id: <UNIQUE SCREEN ID> - type: result - id: ... + id: <UNIQUE SCREEN ID> ``` ### Question -A question screen is a branch node in a decision tree and presents one or many options to further screens. A question screen has the following structure: +A question screen is a branch node in a decision tree and presents one or many options to further screens. question screen has the following structure: ```yaml screens: - type: question - id: instrument - title: What programming language do you want to instrument? + id: <UNIQUE SCREEN ID> + title: <SCREEN TITLE> options: - - text: JVM (Java, Scala, Kotlin) - screen_id: jvm - - text: .Net - screen_id: dotnet - - text: Node.js - screen_id: nodejs + - text: <OPTION TEXT> + screen_id: <SCREEN ID TO LINK TO> ``` ### Result -A result screen is a leaf node in a decision tree and terminates with one or many links. A question screen has the following structure: +A result screen is a leaf node in a decision tree and terminates with one or many links. A question screen has the following structure, with examples for docs and play links: ```yaml screens: - type: result - id: beyla - title: Grafana Beyla - body: | - Grafana Beyla is a Linux eBPF kernel module application to auto-instrument applications without modifying them by monitoring an executable or port. + id: <UNIQUE SCREEN ID> + title: <SCREEN TITLE> + body: <SCREEN BODY> links: - type: docs - title: Grafana Beyla - link_text: Visit docs page - href: /docs/beyla/latest/ + title: <LINK TITLE> + link_text: <LINK TEXT> + href: <ABSOLUTE DOCS LINK> + - type: play + title: <LINK TITLE> + link_text: <LINK TEXT> + href: <FULL GRAFANA PLAY LINK> ``` From 72d834dac3246209df0b630c5c0393bf6ef6a565 Mon Sep 17 00:00:00 2001 From: Sean Packham <sean.packham@grafana.com> Date: Thu, 29 Aug 2024 14:23:29 +0100 Subject: [PATCH 16/18] Update index.md --- docs/sources/write/grot-guides/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/write/grot-guides/index.md b/docs/sources/write/grot-guides/index.md index 4c1c23af..ad631098 100644 --- a/docs/sources/write/grot-guides/index.md +++ b/docs/sources/write/grot-guides/index.md @@ -92,7 +92,7 @@ screens: ### Question -A question screen is a branch node in a decision tree and presents one or many options to further screens. question screen has the following structure: +A question screen is a branch node in a decision tree and presents one or many options to further screens. question screen has the following structure: ```yaml screens: From 3098a17309a7c0da61d9fcf25729538007a8d5c7 Mon Sep 17 00:00:00 2001 From: Sean Packham <sean.packham@grafana.com> Date: Thu, 29 Aug 2024 16:56:13 +0100 Subject: [PATCH 17/18] Update whats-new.md --- docs/sources/whats-new.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/sources/whats-new.md b/docs/sources/whats-new.md index 5f1de4cb..88074931 100644 --- a/docs/sources/whats-new.md +++ b/docs/sources/whats-new.md @@ -22,5 +22,6 @@ This page provides a summary of notable changes to Writers' Toolkit guidance. | New guidance or change | Page | | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | +| Added documentation for Grot guides. | [Grot guides](/docs/writers-toolkit/write/grot-guides/) | | Revised Vale rule for use of exclamation marks and reduced its Vale severity from "error" to "warning". | [`Grafana.Exclamation`](/docs/writers-toolkit/review/lint-prose/rules/#grafanaexclamation) | | Added a What's new page used to summarize notable changes. | [What's new](./) | From c9ee2d0dd2cf9ef7ae07e6c736f0de8254a1e9d8 Mon Sep 17 00:00:00 2001 From: Sean Packham <sean.packham@grafana.com> Date: Fri, 30 Aug 2024 13:41:47 +0100 Subject: [PATCH 18/18] Add overview to shortcode page --- docs/sources/write/shortcodes/index.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/sources/write/shortcodes/index.md b/docs/sources/write/shortcodes/index.md index ee6a9edb..86313e0f 100644 --- a/docs/sources/write/shortcodes/index.md +++ b/docs/sources/write/shortcodes/index.md @@ -707,6 +707,12 @@ The `max-width` value must have a unit of measurement, such as pixels or percent {{</* figure max-width="50%" src="/static/img/docs/grafana-cloud/k8sPods.png" caption="Pod view in Grafana Kubernetes Monitoring" */>}} ``` +## Grot guides + +Grot guides are interactive guides embedded in a documentation page that people can follow to get help and guidance on topics and direction to documentation resources. + +To learn more about Grot guides, refer to the [Grot guides](/docs/writers-toolkit/write/grot-guides/) documentation in the Writers' Toolkit. + ## Hero (simple) A hero section is a large section that contains a title, description, and image, usually placed at the top of a page.