Docs: fix broken link to moved content (#77147)

* Remove docs/reference shortcode for moved content

* Updated transformers content file

* Updated README.md to make Transformations section more prominent

* Updated index file to make super clear where you must update this content

* Added doc/ref back in with new format

* Removed bracket

* Added missing quotation marks

* Added reference style link and removed link from docs/ref shortcode

* Updated link

* Add warning to only use reference style links in content.ts

* ihm/251023-link-fix/ update scripts/docs/generate-transformations.ts with proposed changes, and build markdown

* ihm/251023-link-fix/ build docs

* Fix extraneous whitespace

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

* Add precheck for ONESHELL support

Otherwise the recipe doesn't work.

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>

---------

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
Co-authored-by: jev forsberg <jev.forsberg@grafana.com>
Co-authored-by: Jack Baldry <jack.baldry@grafana.com>

docs/Makefile

@@ -7,10 +7,17 @@ MAKEFLAGS += --no-builtin-rule
 
 include docs.mk
 
+PRECHECK :=
+ifneq ($(filter oneshell,$(.FEATURES)),)
+else
+$(error This Makefile requires GNU Make version 4 or higher)
+endif
+
 .PHONY: sources/panels-visualizations/query-transform-data/transform-data/index.md
 sources/panels-visualizations/query-transform-data/transform-data/index.md: ## Generate the Transform Data page source.
 sources/panels-visualizations/query-transform-data/transform-data/index.md:
+	@$(PRECHECK)
 	cd $(CURDIR)/..
-	npx tsc ../scripts/docs/generate-transformations.ts
-	node ../scripts/docs/generate-transformations.js > $(CURDIR)/$@
+	npx tsc ./scripts/docs/generate-transformations.ts
+	node ./scripts/docs/generate-transformations.js > $(CURDIR)/$@
 	npx prettier -w $(CURDIR)/$@

docs/README.md

@@ -25,15 +25,21 @@ If you have the grafana/website repo checked out in the same directory as the gr
 
 Generally, one can edit content in the `sources` directory.
 
-NOTE: the following paths are built instead from a typescript file and are auto-generated. Please do not edit these files directly.
+The following paths are built instead from a typescript file and are auto-generated. Please do not edit these files directly.
 Instead, navigate to the appropriate typescript source file and edit the content there, then follow the build instructions to generate the markdown files.
 
-- Transformations
-  - Auto-generated markdown location:
-    - docs/sources/panels-visualizations/query-transform-data/transform-data/index.md
-  - Typescript location for editing and instructions:
-    - scripts/docs/generate-transformations.ts - Includes all content not specific to a transformation.
-    - public/app/features/transformers/docs/content.ts - Transformation-specific content.
+### Transformations
+
+Auto-generated markdown location:
+
+- docs/sources/panels-visualizations/query-transform-data/transform-data/index.md
+
+Typescript location for editing and instructions:
+
+- scripts/docs/generate-transformations.ts - Includes all content not specific to a transformation.
+- public/app/features/transformers/docs/content.ts - Transformation-specific content.
+
+Only use [reference style links](https://grafana.com/docs/writers-toolkit/write/shortcodes/#docsreference) in the `content.ts` file or else link text will be visible in the UI.
 
 ### [Contributing](/contribute/documentation/README.md)
 

docs/sources/panels-visualizations/query-transform-data/transform-data/index.md

@@ -1,6 +1,14 @@
 ---
 comments: |
-  This Markdown file is auto-generated. Do not edit this file directly.
+  This Markdown file is auto-generated. DO NOT EDIT THIS FILE DIRECTLY.
+
+  To update this Markdown, navigate to the following Typescript files and edit them based on what you need to update:
+
+  scripts/docs/generate-transformations.ts - Includes all content not specific to a transformation.
+  public/app/features/transformers/docs/content.ts - Transformation-specific content.
+
+  Only use reference style links in the 'content.ts' file or else link text will be visible in the UI.
+
   To build this Markdown, do the following:
 
   $ cd /docs (from the root of the repository)
@@ -1103,9 +1111,6 @@ For each generated "Trend" field value calculation function can be selected. Def
 [Table panel]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/visualizations/table"
 [Table panel]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/visualizations/table"
 
-[Data frames]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/developers/plugins/introduction-to-plugin-development/data-frames"
-[Data frames]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/developers/plugins/introduction-to-plugin-development/data-frames"
-
 [Calculation types]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/calculation-types"
 [Calculation types]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/calculation-types"
 
@@ -1128,3 +1133,5 @@ For each generated "Trend" field value calculation function can be selected. Def
 [dashboard variable]: "/docs/grafana-cloud/ -> docs/grafana/<GRAFANA VERSION>/dashboards/variables"
 
 {{% /docs/reference %}}
+
+[Data frames]: https://grafana.com/developers/plugin-tools/introduction/data-frames/

scripts/docs/generate-transformations.ts

@@ -6,7 +6,15 @@ import {
 
 const template = `---
 comments: |
-  This Markdown file is auto-generated. Do not edit this file directly.
+  This Markdown file is auto-generated. DO NOT EDIT THIS FILE DIRECTLY.
+
+  To update this Markdown, navigate to the following Typescript files and edit them based on what you need to update:
+
+  scripts/docs/generate-transformations.ts - Includes all content not specific to a transformation.
+  public/app/features/transformers/docs/content.ts - Transformation-specific content.
+
+  Only use reference style links in the 'content.ts' file or else link text will be visible in the UI.
+
   To build this Markdown, do the following:
 
   $ cd /docs (from the root of the repository)
@@ -126,9 +134,6 @@ ${buildTransformationDocsContent(transformationDocsContent)}
 [Table panel]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/visualizations/table"
 [Table panel]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/visualizations/table"
 
-[Data frames]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/developers/plugins/introduction-to-plugin-development/data-frames"
-[Data frames]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/developers/plugins/introduction-to-plugin-development/data-frames"
-
 [Calculation types]: "/docs/grafana/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/calculation-types"
 [Calculation types]: "/docs/grafana-cloud/ -> /docs/grafana/<GRAFANA VERSION>/panels-visualizations/calculation-types"
 
@@ -151,6 +156,8 @@ ${buildTransformationDocsContent(transformationDocsContent)}
 [dashboard variable]: "/docs/grafana-cloud/ -> docs/grafana/<GRAFANA VERSION>/dashboards/variables"
 
 {{% /docs/reference %}}
+
+[Data frames]: https://grafana.com/developers/plugin-tools/introduction/data-frames/
 `;
 
 function buildTransformationDocsContent(transformationDocsContent: TransformationDocsContentType) {