From 573b565fb05e3faf8e2704f9fe430316d4264ab7 Mon Sep 17 00:00:00 2001 From: Steven Spencer Date: Fri, 18 Feb 2022 21:45:09 -0600 Subject: [PATCH 1/3] WIP: New document for contributors on formatting * new document on using formatting in the documentation (admonitions, tables, numberd lists, block quotes) * also covers nesting of these features --- .../guides/contribute/rockydocs_formatting.md | 254 ++++++++++++++++++ 1 file changed, 254 insertions(+) create mode 100644 docs/guides/contribute/rockydocs_formatting.md diff --git a/docs/guides/contribute/rockydocs_formatting.md b/docs/guides/contribute/rockydocs_formatting.md new file mode 100644 index 0000000000..db80ca1625 --- /dev/null +++ b/docs/guides/contribute/rockydocs_formatting.md @@ -0,0 +1,254 @@ +--- +title: Rocky Docs Formatting +author: Steven Spencer +contributors: +update: +--- + +# Rocky Docs Formatting - Introduction + +Over the last year and change, a lot has changed with Rocky documentation. This guide is meant to help contributors who want to use admonitions, numbered lists, tables, and more, get the most out of using these markdown tools. To be clear, a document may or may not need to contain any of these elements. If you feel that your document will benefit from them, then this guide should help. + +## Admonitions + +Admonitions allow you to call attention to important facts and highlight them in a way that makes them stick out from the rest of the text. Admonitions types are as follows: + +| type | Description | +|-----------|-----------------------------------------------------------| +| attention | renders a light orange text box | +| caution | renders a light orange text box | +| danger | renders a red text box | +| error | renders a red text box | +| hint | renders a green text box | +| important | renders a green text box | +| note | renders a blue text box | +| tip | renders a green text box | +| warning | renders a orange text box | +| custom 1 | always renders a blue text box | +| custom 2 | uses a customer title within another type | + +So there is no limit on the types of admonitions you can use as noted in custom 1 above. A custom title can be added to any of the other admonition types to get the colored box you want for a specific admonition, as noted in custom 2 above. An admonition is always entered in this way: + +``` +!!! admonition_type + + text of admonition +``` +The text here, must be indented four (4) spaces from the beginning margin. It's easy to see where that is in this case, because it will always line up under the first letter of the admonition type. The extra line feed will not show up, but is required for our translation engine (Crowdin) to function correctly. + +The following shows examples of each admonition type and how it will format in your document: + +!!! attention + + text + +!!! caution + + text + +!!! danger + + text + +!!! error + + text + +!!! hint + + text + +!!! important + + text + +!!! note + + text + +!!! tip + + text + +!!! warning + + text + +!!! custom + + A custom 1 type. Here we've used "custom" as our admonition type. Again, this will always render in blue. + +!!! warning "custom title" + + A custom 2 type. Here we've modified the "warning" admonition type with a custom header. Here's what that looks like: + + ``` + !!! warning "custom title" + ``` + +## Numbered Lists + +Numbered lists sound like they are easy to create and use, and once you get the hang of them, they really are. If you just have a single list of items with no complexity, then this sort of format works fine: + +``` +1. Item 1 + +2. Item 2 + +3. Item 3 +``` + +1. Item 1 + +2. Item 2 + +3. Item 3 + +If you need to add code blocks, multiple lines or even paragraphs of text to a numbered list, then the text should be indented with those same four (4) spaces that we used in the admonitions. You can't use your eyes to line them up under the numbered item, however, as this is one space off. If you are using a good markdown editor, you can set your tab value to four (4), which will make entering the following easier. Here's an example of a multi-line numbered list with a code block thrown in for good measure: + +1. When dealing with numbered lists that are multi line and include things like code blocks, use the space indentation to get what you want. + + For example: this is indented four (4) spaces and represents a new paragraph of text. And here, we are adding a code block in. It is also indented by the same four (4) spaces as our paragraph: + + ``` + dnf update + ``` + +2. Here's our second listed item. Because we used the indentation (above) it renders with the next sequence of numbering (in other words, 2), but if we had entered item 1 without the indentation (in the subsequent paragraph and code), then this would show up as item 1 again, which is not what we want. + +## Tables + +Another formatting item is the use of tables. Tables help us to lay out command options, or in the above case, admonition types and descriptions. Here's how the table above is entered: + +``` +| type | Description | +|-----------|-----------------------------------------------------------| +| attention | renders a light orange text box | +| caution | renders a light orange text box | +| danger | renders a red text box | +| error | renders a red text box | +| hint | renders a green text box | +| important | renders a green text box | +| note | renders a blue text box | +| tip | renders a green text box | +| warning | renders a orange text box | +| custom 1 | always renders a blue text box | +| custom 2 | uses a customer title within another type | +``` + +Note that it isn't necessary to have each column broken down by size (as we've done in the first part of the table), but it is certainly more readable in the source documentation page, than stringing the items together, simply by breaking the columns with the pipe character "|" wherever the natural break would be, as in the last two items of the table. + +## Block Quotes + +Block quotes are actually designed for quoting text from other sources to include in your documentation, but they don't have to be used that way. We've had several people use block quotes instead of tables, for instance, to list out some options. Examples of block quotes in markdown would be: + +``` +> **an item** - A description of that item + +> **another item** - Another description of that item +``` +To avoid these running together, the extra line feed here is necessary. + +That ends up looking like this when the page is rendered: + +> **an item** - A description of that item + +> **another item** - Another description of an item + +## Grouping Different Formatting Types + +Thins really get crazy, when you need to combine multiple elements within another one. For instance, an admonition with a numbered list: + +!!! note + + Things can get a little crazy when you are grouping things together. Like when: + + 1. You add a numbered list of options within an admonition + + 2. Or you add a numbered list with multiple code blocks: + + ``` + dnf install some-great-package + ``` + + Which is also within a multi-paragraph numbered list. + +Or what if you have a numbered list, with an additional admonition: + +1. This item is something very important + +2. But this item is something very important and has multiple paragraphs to it + + And it has an admonition in the middle of it: + + !!! warning + + Things can get a little crazy with multiple elements within different formatting types! + +As long as you keep track of the magic four (4) spaces to separate these items, they will display logically and exactly the way you want them to. Sometimes that is really important. + +You can even embed a table or block quote (quite literally any formatting item type) within another one. Here we have a numbered list, an admonition, a table and some block quote elements all bundled together: + +1. Trying to keep up with everything that's going on in your document can be a real task when there are multiple elements to be considered. + +2. If you are feeling overwhelmed, consider: + + !!! important "important: I think my brain hurts!" + + When combining multiple formatting elements, your brain can go a little crazy. Consider sucking down some extra caffeine before you begin! + + | type | caffeine daily allowance | + |-----------------|----------------------------------| + | tea | it will get you there eventually | + | coffee | for discerning taste buds | + | red bull | tastes terrible - but it will keep you going!| + | mountain dew | over hyped | + + > **sugar** if caffeine isn't to your liking + + > **suffer** if all else fails, concentrate more + +3. There are more examples, but I think you get that everything can be nested within. Just remember the four (4) magic spaces. + +Here's what this example looks like in your editor: + +``` +As long as you keep track of the magic four (4) spaces to separate these items, they will display logically and exactly the way you want them to. Sometimes that is really important. + +You can even embed a table or block quote (quite literally any formatting item type) within another one. Here we have a numbered list, an admonition, a table and some block quote elements all bundled together: + +1. Trying to keep up with everything that's going on in your document can be a real task when there are multiple elements to be considered. + +2. If you are feeling overwhelmed, consider: + + !!! important "important: I think my brain hurts!" + + When combining multiple formatting elements, your brain can go a little crazy. Consider sucking down some extra caffeine before you begin! + + | type | caffeine daily allowance | + |-----------------|----------------------------------| + | tea | it will get you there eventually | + | coffee | for discerning taste buds | + | red bull | tastes terrible - but it will keep you going!| + | mountain dew | over hyped | + + > **sugar** if caffeine isn't to your liking + + > **suffer** if all else fails, concentrate more + +3. There are more examples, but I think you get that everything can be nested within. Just remember the four (4) magic spaces. +``` + +## More Reading + +* The Rocky Linux [how to contribute document](README.md) + +* More on [admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types) + +* More on [markdown quick reference](https://wordpress.com/support/markdown-quick-reference/) + +* More on [more quick references](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) + +## Conclusion + +Document formatting with admonitions, tables, numbered lists, and block quotes, can add clarity to your document. If you overuse these elements, however, they can simply add clutter where none is needed. Learning to use these formatting items conservatively and well can be very helpful to get your point across in a document. From 8c9522dead8b0df66fd3e0245442e1e62a3276be Mon Sep 17 00:00:00 2001 From: Steven Spencer Date: Sat, 19 Feb 2022 08:58:53 -0600 Subject: [PATCH 2/3] update conclusion * updated the concluding paragraph, thanks @jimcat8 --- docs/guides/contribute/rockydocs_formatting.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guides/contribute/rockydocs_formatting.md b/docs/guides/contribute/rockydocs_formatting.md index db80ca1625..937e2572ca 100644 --- a/docs/guides/contribute/rockydocs_formatting.md +++ b/docs/guides/contribute/rockydocs_formatting.md @@ -1,13 +1,13 @@ --- title: Rocky Docs Formatting author: Steven Spencer -contributors: -update: +contributors: tianci li +update: 19-Feb-2022 --- # Rocky Docs Formatting - Introduction -Over the last year and change, a lot has changed with Rocky documentation. This guide is meant to help contributors who want to use admonitions, numbered lists, tables, and more, get the most out of using these markdown tools. To be clear, a document may or may not need to contain any of these elements. If you feel that your document will benefit from them, then this guide should help. +Over the last year, a lot has changed with Rocky documentation. This guide is meant to help contributors who want to use admonitions, numbered lists, tables, and more, get the most out of using these markdown tools. To be clear, a document may or may not need to contain any of these elements. If you feel that your document will benefit from them, then this guide should help. ## Admonitions @@ -251,4 +251,4 @@ You can even embed a table or block quote (quite literally any formatting item t ## Conclusion -Document formatting with admonitions, tables, numbered lists, and block quotes, can add clarity to your document. If you overuse these elements, however, they can simply add clutter where none is needed. Learning to use these formatting items conservatively and well can be very helpful to get your point across in a document. +Document formatting with admonitions, tables, numbered lists, and block quotes, can add clarity to your document. When using admonitions, take care to pick the correct type. This can make it easier to visually see the importance of the admonition. Overuse of any of these elements can simply add clutter where none is needed. Learning to use these formatting items conservatively and well can be very helpful to get your point across in a document. To make formatting easier, consider changing your markdown editor's TAB value to four (4) spaces. From 3d91d77e80ee424899fdde04f0c689ad25710248 Mon Sep 17 00:00:00 2001 From: Ezequiel Bruni Date: Sun, 20 Feb 2022 01:52:23 -0600 Subject: [PATCH 3/3] Quick editing pass on formatting doc --- .../guides/contribute/rockydocs_formatting.md | 59 ++++++++++++++----- 1 file changed, 44 insertions(+), 15 deletions(-) diff --git a/docs/guides/contribute/rockydocs_formatting.md b/docs/guides/contribute/rockydocs_formatting.md index 937e2572ca..d7895c84c5 100644 --- a/docs/guides/contribute/rockydocs_formatting.md +++ b/docs/guides/contribute/rockydocs_formatting.md @@ -1,17 +1,19 @@ --- title: Rocky Docs Formatting author: Steven Spencer -contributors: tianci li +contributors: tianci li, Ezequiel Bruni update: 19-Feb-2022 --- # Rocky Docs Formatting - Introduction -Over the last year, a lot has changed with Rocky documentation. This guide is meant to help contributors who want to use admonitions, numbered lists, tables, and more, get the most out of using these markdown tools. To be clear, a document may or may not need to contain any of these elements. If you feel that your document will benefit from them, then this guide should help. +Over the last year, a lot has changed with Rocky documentation. This guide is meant to help contributors get familiar with our more advanced formatting options: including admonitions, numbered lists, tables, and more. + +To be clear, a document may or may not need to contain any of these elements. If you feel that your document will benefit from them, then this guide should help. ## Admonitions -Admonitions allow you to call attention to important facts and highlight them in a way that makes them stick out from the rest of the text. Admonitions types are as follows: +Admonitions are special visual "boxes" that allow you to call attention to important facts and highlight them in a way that makes them stick out from the rest of the text. Admonitions types are as follows: | type | Description | |-----------|-----------------------------------------------------------| @@ -25,18 +27,21 @@ Admonitions allow you to call attention to important facts and highlight them in | tip | renders a green text box | | warning | renders a orange text box | | custom 1 | always renders a blue text box | -| custom 2 | uses a customer title within another type | +| custom 2 | uses a custom title within another type | + +So there is no limit on the types of admonitions you can use as noted in custom 1 above. A custom title can be added to any of the other admonition types to get the colored box you want for a specific admonition, as noted in custom 2 above. -So there is no limit on the types of admonitions you can use as noted in custom 1 above. A custom title can be added to any of the other admonition types to get the colored box you want for a specific admonition, as noted in custom 2 above. An admonition is always entered in this way: +An admonition is always entered in this way: ``` !!! admonition_type text of admonition ``` -The text here, must be indented four (4) spaces from the beginning margin. It's easy to see where that is in this case, because it will always line up under the first letter of the admonition type. The extra line feed will not show up, but is required for our translation engine (Crowdin) to function correctly. -The following shows examples of each admonition type and how it will format in your document: +The body text of the admonition must be indented four (4) spaces from the beginning margin. It's easy to see where that is in this case, because it will always line up under the first letter of the admonition type. The extra line between the title and body will not show up, but is required for our translation engine (Crowdin) to function correctly. + +Here are examples of each admonition type, and how they will look in your document: !!! attention @@ -104,7 +109,11 @@ Numbered lists sound like they are easy to create and use, and once you get the 3. Item 3 -If you need to add code blocks, multiple lines or even paragraphs of text to a numbered list, then the text should be indented with those same four (4) spaces that we used in the admonitions. You can't use your eyes to line them up under the numbered item, however, as this is one space off. If you are using a good markdown editor, you can set your tab value to four (4), which will make entering the following easier. Here's an example of a multi-line numbered list with a code block thrown in for good measure: +If you need to add code blocks, multiple lines or even paragraphs of text to a numbered list, then the text should be indented with those same four (4) spaces that we used in the admonitions. + +You can't use your eyes to line them up under the numbered item, however, as this is one space off. If you are using a good markdown editor, you can set your tab value to four (4), which will make formatting everything a bit easier. + +Here's an example of a multi-line numbered list with a code block thrown in for good measure: 1. When dealing with numbered lists that are multi line and include things like code blocks, use the space indentation to get what you want. @@ -116,9 +125,24 @@ If you need to add code blocks, multiple lines or even paragraphs of text to a n 2. Here's our second listed item. Because we used the indentation (above) it renders with the next sequence of numbering (in other words, 2), but if we had entered item 1 without the indentation (in the subsequent paragraph and code), then this would show up as item 1 again, which is not what we want. + +And here's how that looks as raw text: + +```markdown +1. When dealing with numbered lists that are multi line and include things like code blocks, use the space indentation to get what you want. + + For example: this is indented four (4) spaces and represents a new paragraph of text. And here, we are adding a code block in. It is also indented by the same four (4) spaces as our paragraph: + + ``` + dnf update + ``` + +2. Here's our second listed item. Because we used the indentation (above) it renders with the next sequence of numbering (in other words, 2), but if we had entered item 1 without the indentation (in the subsequent paragraph and code), then this would show up as item 1 again, which is not what we want. +``` + ## Tables -Another formatting item is the use of tables. Tables help us to lay out command options, or in the above case, admonition types and descriptions. Here's how the table above is entered: +Tables help us to lay out command options, or in the above case, admonition types and descriptions. Here's how the table above is entered: ``` | type | Description | @@ -136,7 +160,7 @@ Another formatting item is the use of tables. Tables help us to lay out command | custom 2 | uses a customer title within another type | ``` -Note that it isn't necessary to have each column broken down by size (as we've done in the first part of the table), but it is certainly more readable in the source documentation page, than stringing the items together, simply by breaking the columns with the pipe character "|" wherever the natural break would be, as in the last two items of the table. +Note that it isn't necessary to have each column broken down by size (as we've done in the first part of the table), but it is certainly more readable in the markdown source file. It can get confusing when you string the items together, simply by breaking the columns with the pipe character "|" wherever the natural break would be, as you can see in the last two items of the table. ## Block Quotes @@ -147,7 +171,7 @@ Block quotes are actually designed for quoting text from other sources to includ > **another item** - Another description of that item ``` -To avoid these running together, the extra line feed here is necessary. +To keep the lines from running together, the extra "spacing" line is necessary here. That ends up looking like this when the page is rendered: @@ -185,7 +209,7 @@ Or what if you have a numbered list, with an additional admonition: Things can get a little crazy with multiple elements within different formatting types! -As long as you keep track of the magic four (4) spaces to separate these items, they will display logically and exactly the way you want them to. Sometimes that is really important. +As long as you keep track of the magic four (4) spaces to indent and separate these items, they will display logically and exactly the way you want them to. Sometimes that is really important. You can even embed a table or block quote (quite literally any formatting item type) within another one. Here we have a numbered list, an admonition, a table and some block quote elements all bundled together: @@ -213,6 +237,7 @@ You can even embed a table or block quote (quite literally any formatting item t Here's what this example looks like in your editor: ``` + As long as you keep track of the magic four (4) spaces to separate these items, they will display logically and exactly the way you want them to. Sometimes that is really important. You can even embed a table or block quote (quite literally any formatting item type) within another one. Here we have a numbered list, an admonition, a table and some block quote elements all bundled together: @@ -245,10 +270,14 @@ You can even embed a table or block quote (quite literally any formatting item t * More on [admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types) -* More on [markdown quick reference](https://wordpress.com/support/markdown-quick-reference/) +* [Markdown quick reference](https://wordpress.com/support/markdown-quick-reference/) -* More on [more quick references](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) +* [More quick references](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) for Markdown ## Conclusion -Document formatting with admonitions, tables, numbered lists, and block quotes, can add clarity to your document. When using admonitions, take care to pick the correct type. This can make it easier to visually see the importance of the admonition. Overuse of any of these elements can simply add clutter where none is needed. Learning to use these formatting items conservatively and well can be very helpful to get your point across in a document. To make formatting easier, consider changing your markdown editor's TAB value to four (4) spaces. +Document formatting with admonitions, tables, numbered lists, and block quotes, can add clarity to your document. When using admonitions, take care to pick the correct type. This can make it easier to visually see the importance of the particular admonition. + +Overuse of any of these elements can simply add clutter where none is needed. Learning to use these formatting items conservatively and well can be very helpful to get your point across in a document. + +Lastly, to make formatting easier, consider changing your markdown editor's TAB value to four (4) spaces. \ No newline at end of file