From 4067273d3655a7917d0c9dfa81792796fb06d1ae Mon Sep 17 00:00:00 2001 From: sspencerwire Date: Thu, 18 Jan 2024 08:57:29 -0600 Subject: [PATCH] Explanation addition to `rockydocs_formatting.md` * add admonition explaining the need to steer clear as much as possible from HTML elements in markdown --- docs/guides/contribute/rockydocs_formatting.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/guides/contribute/rockydocs_formatting.md b/docs/guides/contribute/rockydocs_formatting.md index 4fd5a4dc19..fc3bf102dc 100644 --- a/docs/guides/contribute/rockydocs_formatting.md +++ b/docs/guides/contribute/rockydocs_formatting.md @@ -33,6 +33,14 @@ A document may or may not need to contain any of these elements. If you feel you 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. +!!! 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 where 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: + + * Inline HTML [element name] + + If you find yourself needing to use a supported HTML element, see if you can find another way to write your document that will not use HTML elements. If you must use them, it is still allowed. + ## Admonitions Admonitions are special visual "boxes" that allow you to call attention to important facts and highlight them. Following are types of admonitions: