From 90d66155fb100873f6eae903d4821e7905e0f4dc Mon Sep 17 00:00:00 2001 From: sspencerwire Date: Fri, 2 Feb 2024 08:17:06 -0600 Subject: [PATCH] Add new features * replacement for some former HTML * new highlighting feature --- .../guides/contribute/rockydocs_formatting.md | 42 ++++++++++++------- 1 file changed, 26 insertions(+), 16 deletions(-) diff --git a/docs/guides/contribute/rockydocs_formatting.md b/docs/guides/contribute/rockydocs_formatting.md index 666155dd78..9d845ac022 100644 --- a/docs/guides/contribute/rockydocs_formatting.md +++ b/docs/guides/contribute/rockydocs_formatting.md @@ -59,8 +59,8 @@ Admonitions are special visual "boxes" that allow you to call attention to impor | bug | displays text in a red box | | example | displays text in a purple box | | quote | displays text in a grey box | -| custom 1 | always displays text in a blue box | -| custom 2 | displays text in the color of the box of the chosen type | +| custom ^1^ | always displays text in a blue box | +| custom ^2^ | displays text in the color of the box of the chosen type | Admonitions are limitless, as noted in custom 1 above. It is possible to add a custom title to any admonition type to get the box color you want for a specific admonition, as noted in custom 2 above. @@ -114,11 +114,11 @@ Here are examples of each admonition type, and how they will look in your docume !!! custom - A custom 1 type. We have used "custom" as our admonition type. Again, this will always render in blue. + A custom^1^ type. We have used "custom" as our admonition type. Again, this will always render in blue. !!! warning "custom title" - A custom 2 type. We have modified the "warning" admonition type with a custom header. Here is what that looks like: + A custom^2^ type. We have modified the "warning" admonition type with a custom header. Here is what that looks like: ``` !!! warning "custom title" @@ -233,8 +233,8 @@ In the above case, tables help us lay out command options or admonition types an | bug | displays text in a red box | | example | displays text in a purple box | | quote | displays text in a grey box | -| custom 1 | always displays text in a blue box | -| custom 2 | displays text in a box with the color of the chosen type | +| custom^1^ | always displays text in a blue box | +| custom^2^ | displays text in a box with the color of the chosen type | ``` @@ -323,31 +323,31 @@ A list of accepted keyboard commands [in this document](https://facelessuser.git ## Superscript, subscript and special symbols -Superscript and subscript notation are not normal markdown, but are supported in Rocky Linux documentation via the HTML tags used for the same purpose. Superscript places text entered between the tags slightly above the normal text, while subscript places the text slightly below. Superscript is by far the more commonly used of these two in writing. Some special characters already appear in superscript without adding the tags, but you can also combine the tag to change the orientation of those characters as seen with the copyright symbol below. You can use superscript to: +Superscript and subscript notation are supported in Rocky Linux documentation by use of the `^` for superscript and `~` for subscript. Superscript places text entered between the tags slightly above the normal text, while subscript places the text slightly below. Superscript is by far the more commonly used of these two in writing. Some special characters already appear in superscript without adding the tags, but you can also combine the tag to change the orientation of those characters as seen with the copyright symbol below. You can use superscript to: -* represent ordinal numbers, such as 1st, 2nd, 3rd -* copyright and trademark symbols, like ©, TM, or ™, ® -* as notation for references, such as this1, this2 and this3 +* represent ordinal numbers, such as 1^st^, 2^nd^, 3^rd^ +* copyright and trademark symbols, like ^©^, ^TM^, or ^™^, ^®&^ +* as notation for references, such as this^1^, this^2^ and this^3^ Some of the special characters, such as © are not normally superscript, while others such as ™, are. Here is how all the above looks in your markdown code: ```text -* represent ordinal numbers, such as 1st, 2nd, 3rd -* copyright and trademark symbols, like ©, TM or ™, ® -* as notation for references, such as this1, this2 and this3 +* represent ordinal numbers, such as 1^st^, 2^nd^, 3^rd^ +* copyright and trademark symbols, like ^©^, ^TM^ or ^™^, ^®^ +* as notation for references, such as this^1^, this^2^ and this^3^ Some of the special characters, such as © are not normally superscript, while others such as ™, are. ``` -As you can see, to force superscript you can use the supported HTML tags of ``. +To force superscript you surround what you want superscript with `^`. -Enter subscript with the `` tags, and as noted earlier, is not used nearly as much in writing. +Enter subscript with the `~` tag, and as noted earlier, is not ~used nearly as much~ in writing. ### Superscript for references -Some of you may feel the need to reference outside sources when writing documentation. If you only have a single source, you may wish to include it in your conclusion as a single link, but if you have multiples1, you can use superscript to note them in your text2 and then list them at the end of your document. Note that the positioning of references should come after the "Conclusion" section. +Some of you may feel the need to reference outside sources when writing documentation. If you only have a single source, you can include it in your conclusion as a single link, but if you have multiples^1^, you can use superscript to note them in your text^2^ and then list them at the end of your document. Note that the positioning of references should come after the "Conclusion" section. Following the conclusion, you can have your notations in a numbered list to match the superscript, or you can enter them as links. Both examples are shown here: @@ -372,6 +372,16 @@ or ``` +## Highlighting text + +Another possible way to enhance documentation is with ==highlighting==. Highlighting is handled by surrounding the text with `==`. + +This looks like this in your editor: + +```bash +Another possible way to enhance documentation is with ==highlighting==. Higlighting is handled by surrounding the text with `==`. +``` + ## Grouping different formatting types Rocky documentation offers some elegant formatting options when combining multiple elements within another element. For instance, an admonition with a numbered list: