From d93340a780b6c04d12fbdedbd850210adfd0f2f2 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Sun, 31 Aug 2025 12:53:43 -0700 Subject: [PATCH] content: Update documentation guide --- content/en/contribute/documentation.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/content/en/contribute/documentation.md b/content/en/contribute/documentation.md index cd56c6288..91d345b60 100644 --- a/content/en/contribute/documentation.md +++ b/content/en/contribute/documentation.md @@ -24,7 +24,15 @@ Follow Google's [developer documentation style guide]. Adhere to these Markdown conventions: - Use [ATX] headings (levels 2-4), not [setext] headings. -- Use [fenced code blocks], not [indented code blocks]. +- Use [collapsed link references][] instead of full or shortcut references. For example: + + ```text + This is a [link][]. + + [link]: https://example.org + ``` + +- Use [fenced code blocks] instead of [indented code blocks]. - Use hyphens, not asterisks, for unordered [list items]. - Use [callouts](#callouts) instead of bold text for emphasis. - Do not mix [raw HTML] within Markdown. @@ -522,6 +530,7 @@ Step 9 [ATX]: https://spec.commonmark.org/current/#atx-headings [basic english]: https://simple.wikipedia.org/wiki/Basic_English +[collapsed link references]: https://discourse.gohugo.io/t/55714 [developer documentation style guide]: https://developers.google.com/style [documentation repository]: https://github.com/gohugoio/hugoDocs/ [fenced code blocks]: https://spec.commonmark.org/current/#fenced-code-blocks