Add info for reading Hugo log output (#296)

* Add info for hugo output * Update docs/sources/review/run-a-local-webserver/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update index.md * Update docs/sources/review/run-a-local-webserver/index.md * Update docs/sources/review/run-a-local-webserver/index.md * Share relref examples * Apply suggestions from code review Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update docs/sources/shared/hugo-error-example-bad-link.md * Apply suggestions from code review * Update docs/sources/shared/hugo-error-example-bad-link.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update docs/sources/shared/hugo-error-example-bad-link.md * Fix prettier and link version Signed-off-by: Jack Baldry <jack.baldry@grafana.com> --------- Signed-off-by: Jack Baldry <jack.baldry@grafana.com> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Jack Baldry <jack.baldry@grafana.com>
grafana · Sep 4, 2023 · 31c91e0 · 31c91e0
1 parent d12883b
commit 31c91e0
Show file tree

Hide file tree

Showing 4 changed files with 72 additions and 12 deletions.
diff --git a/docs/sources/review/run-a-local-webserver/index.md b/docs/sources/review/run-a-local-webserver/index.md
@@ -72,6 +72,40 @@ The format is `<PROJECT>[:VERSION[:REPOSITORY[:DIR]]].`
 The example mounts the `PROJECT` tempo, at the default `VERSION` latest, using the `REPOSITORY` `tempo-doc-work`, and the default `DIR` `docs/sources`.
 This example builds the Tempo documentation from the local working directory, `tempo-doc-work`, instead of the standard `tempo` directory.
 
+## Understand Hugo output from `make docs`
+
+When you run `make docs`, Hugo (our static site generator) processes the Markdown files and outputs warnings and error messages.
+
+![Hugo output for running make docs](/media/docs/writers-toolkit/screenshot-make-docs-output.png)
+
+These messages are in the following format:
+
+```text
+WARN <DATE> <TIME> <LANGUAGE> REF_NOT_FOUND: Ref <RELREF ARGUMENT>: “<SOURCE FILE>:<LINE>:<COLUMN>”: <ERROR>
+```
+
+where:
+
+- `SOURCE FILE` is the file with the broken `relref`
+- `RELREF ARGUMENT` is the argument to the `relref` shortcode that is not working.
+- `ERROR` is the reason `RELREF ARGUMENT` is not working.
+
+When you save a file with an active local build, the page is rechecked. If the error messages is not repeated, then the issue is fixed.
+
+### Example: Page not found
+
+{{< docs/shared source="writers-toolkit" lookup="hugo-error-example-bad-link.md" version="" >}}
+
+For more information about linking, refer to [Links and cross references]({{< relref "../../write/references" >}}).
+
+### Example: Rebuild failed due to missing shortcode
+
+In this example, the rebuild fails because the file `contribute-documentation/_index.md` is missing a closing shortcode for `admonition` on line 152.
+
+```
+ERROR Rebuild failed: assemble: "/hugo/content/docs/writers-toolkit/contribute-documentation/_index.md:152:1": failed to extract shortcode: shortcode "admonition" must be closed or self-closed
+```
+
 ## Reference
 
 The `make docs` target uses the [`make-docs`](https://github.com/grafana/writers-toolkit/blob/main/scripts/make-docs) script to mount local documentation into the Hugo build.

diff --git a/docs/sources/shared/hugo-error-example-bad-link.md b/docs/sources/shared/hugo-error-example-bad-link.md
@@ -0,0 +1,31 @@
+---
+headless: true
+description: Shared file for example Hugo error output.
+labels:
+  products:
+    - oss
+---
+
+[//]: # "This file documents an example Hugo error output for relref and links."
+[//]: # "This shared file is included in these locations:"
+[//]: # "/writers-toolkit/review/run-a-local-webserver"
+[//]: # "/writers-toolkit/write/references/index.md"
+[//]: # "/tempo/docs/sources/tempo/traceql/query_editor.md"
+[//]: #
+[//]: # "If you make changes to this file, verify that the meaning and content are not changed in any place where the file is included."
+[//]: # "Any links should be fully qualified and not relative: /docs/grafana/ instead of ../grafana/."
+
+Hugo emits `REF_NOT_FOUND` warnings indicating the filename and location of such references when building the docs, for example with `make docs` in `grafana/grafana` or `make server-quick` in `grafana/website`:
+
+```
+WARN 2022/08/04 21:35:37 [en] REF_NOT_FOUND: Ref "../../enterprise": "/hugo/content/docs/grafana/next/administration/roles-and-permissions/access-control/assign-rbac-roles.md:14:47": page not found
+```
+
+In this example,
+
+- `Ref "../../enterprise"` is the destination of the reference that Hugo can't resolve
+- `\/hugo/content/docs/grafana/next/administration/roles-and-permissions/access-control/assign-rbac-roles.md` is the document containing the reference, where the path after `/next/` is relative to the documentation root of the component repository
+- `:14` represents the line number containing the unresolved reference
+- `:47` represents the character in that line where the unresolved reference begins
+
+If the reference's destination appears to be invalid, for example due to a typo in the reference or the depth of the`relref` directory, then you should be able to resolve this by correcting the reference target.
diff --git a/docs/sources/shared/index.md b/docs/sources/shared/index.md
@@ -0,0 +1,4 @@
+---
+headless: true
+description: nothing
+---
diff --git a/docs/sources/write/references/index.md b/docs/sources/write/references/index.md
@@ -159,17 +159,8 @@ The following Markdown links are equivalent:
 
 ### Hugo error output
 
-Hugo emits `REF_NOT_FOUND` warnings indicating the filename and location of such references when building the docs, for example with `make docs` in `grafana/grafana` or `make server-quick` in `grafana/website`:
+<!-- The output example is also used in review/run-a-local-webserver. -->
 
-```
-WARN 2022/08/04 21:35:37 [en] REF_NOT_FOUND: Ref "../../enterprise": "/hugo/content/docs/grafana/next/administration/roles-and-permissions/access-control/assign-rbac-roles.md:14:47": page not found
-```
-
-In this example,
-
-- `Ref "../../enterprise"` is the destination of the reference that Hugo can't resolve
-- `/hugo/content/docs/grafana/next/administration/roles-and-permissions/access-control/assign-rbac-roles.md` is the document containing the reference, where the path after `/next/` is relative to the documentation root of the component repository
-- `:14` represents the line number containing the unresolved reference
-- `:47` represents the character in that line where the unresolved reference begins
+{{< docs/shared source="writers-toolkit" lookup="hugo-error-example-bad-link.md" version="" >}}
 
-If the reference's destination appears to be invalid, for example due to a typo in the reference or the depth of the`relref` directory, then you should be able to resolve this by correcting the reference target.
+For additional information about Hugo error output, refer to [Test documentation changes]({{< relref "../../review/run-a-local-webserver" >}}).