From c7a26d4ab0a4bfe3050c3b788e7b883893f27504 Mon Sep 17 00:00:00 2001 From: sspencerwire Date: Thu, 12 Dec 2024 08:42:31 -0600 Subject: [PATCH] Add to `rockydocs_formatting.md` (#2541) * note about the Level 1 heading being replaced by the `title:` meta --- docs/guides/contribute/rockydocs_formatting.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/guides/contribute/rockydocs_formatting.md b/docs/guides/contribute/rockydocs_formatting.md index ddc012161..0f7f718d0 100644 --- a/docs/guides/contribute/rockydocs_formatting.md +++ b/docs/guides/contribute/rockydocs_formatting.md @@ -7,7 +7,7 @@ tags: - formatting --- -# Introduction +## Introduction This guide highlights our more advanced formatting options, including admonitions, numbered lists, tables, and more. @@ -33,6 +33,19 @@ A document might or might not need to contain any of these elements. However, if The key here is that you can use as many of the 2 through 6 headings as necessary, but only **ONE** level 1 heading. While the document will appear correct with more than one level 1 heading, the automatically generated table of contents for the document that appears on the right-hand side will **NOT** display correctly (or sometimes at all) with more than one. Keep this in mind when writing your documents. + Another important note about the Level 1 heading: If the `title:` meta is in use, then this will be the default Level 1 heading. You should not add another one. An example is that this document's title meta is: + + ``` + --- + title: Document Formatting + ``` + + The very first heading added, then, is "Introduction" at Level 2. + + ``` + ## Introduction + ``` + !!! warning "A note about supported HTML elements" There are HTML elements that are technically supported in markdown. Some of these are described in this document, and no markdown syntax exists to replace them. These supported HTML tags should be used rarely, because markdown linters will complain about them in a document. For example: