You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* add in a section for "Forcing line breaks"
* add in a section for "Non-displaying characters"
* replace some passive voice phrasing with active voice
* some additional sentence simplification
* other minor corrections
Copy file name to clipboardExpand all lines: docs/guides/contribute/rockydocs_formatting.md
+99-44Lines changed: 99 additions & 44 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,7 +11,7 @@ tags:
11
11
12
12
This guide highlights our more advanced formatting options, including admonitions, numbered lists, tables, and more.
13
13
14
-
A document may or may not need to contain any of these elements. However, if you feel your document will benefit from special formatting, this guide should help.
14
+
A document might or might not need to contain any of these elements. However, if you feel your document will benefit from special formatting, this guide should help.
15
15
16
16
!!! note "A Note About Headings"
17
17
@@ -45,22 +45,22 @@ A document may or may not need to contain any of these elements. However, if you
45
45
46
46
Admonitions are special visual "boxes" that allow you to call attention to important facts and highlight them. The following are types of admonitions:
| tip | displays text in a blue-green box (icon slightly greener) |
54
+
| success | displays text in a green box |
55
+
| question | displays text in a light green box |
56
+
| warning | displays text in an orange box |
57
+
| failure | displays text in a light red box |
58
+
| danger | displays text in a red box |
59
+
| bug | displays text in a red box |
60
+
| example | displays text in a purple box |
61
+
| quote | displays text in a gray box |
62
+
| custom ^1^ | always displays text in a blue box |
63
+
| custom ^2^ | displays text in the color of the box of the chosen type |
64
64
65
65
As noted in custom <sub>1</sub> above, admonitions are limitless. Add a custom title to any admonition type to get the box color you want for a specific admonition, as noted in custom <sub>2</sub> above.
66
66
@@ -142,7 +142,7 @@ Which looks like this in your editor:
142
142
143
143
## Tabbed content within a document
144
144
145
-
Formatting tabbed content is similar to admonitions. Instead of three exclamation marks or question marks, it begins with three equal signs. All the admonition formatting (4 spaces and so on) applies to this content. For example, a document might need a different procedure for a different Rocky Linux version. When using tabbed content for versions, the most recent release of Rocky Linux should come first. At the time of this writing, that was 9.0:
145
+
Formatting tabbed content is similar to admonitions. Instead of three exclamation marks or question marks, it begins with three equal signs. All the admonition formatting (4 spaces and so on) applies to this content. For example, a document might need a different procedure for a different Rocky Linux version. When using tabbed content for versions, the most recent release of Rocky Linux should come first. At the time of this writing, it was 9.0:
146
146
147
147
=== "9.0"
148
148
@@ -216,33 +216,33 @@ And here is how that looks as raw text:
216
216
217
217
## Tables
218
218
219
-
In the above case, tables help us lay out command options or admonition types and descriptions. Here is how the table in the Admonitions section was entered:
219
+
In the above case, tables help us lay out command options or admonition types and descriptions. This shows the entry of the table in the Admonitions section:
| tip | displays text in a blue-green box (icon slightly greener) |
228
+
| success | displays text in a green box |
229
+
| question | displays text in a light green box |
230
+
| warning | displays text in an orange box |
231
+
| failure | displays text in a light red box |
232
+
| danger | displays text in a red box |
233
+
| bug | displays text in a red box |
234
+
| example | displays text in a purple box |
235
+
| quote | displays text in a gray box |
236
+
| custom^1^ | always displays text in a blue box |
237
+
| custom^2^ | displays text in a box with the color of the chosen type|
238
238
239
239
```
240
240
241
241
Note that it is not necessary to have each column broken down by size (as we have donein 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 is, as you can see in the last item in the table.
242
242
243
243
## Block quotes
244
244
245
-
Block quotes are designed forquoting text from other sources to includein your documentation. Examples of block quotes in markdown would be:
245
+
Block quotes are forquoting text from other sources to includein your documentation. Examples of block quotes in markdown would be:
And yes, the code block you just saw used five backticks at the beginning and end to make it render correctly.
293
+
Yes, the code block you just saw used five backticks at the beginning and end to make it render correctly.
294
294
295
295
### Suppressing the displayed prompt and automatic line feed
296
296
@@ -326,6 +326,13 @@ A list of accepted keyboard commands [in this document](https://facelessuser.git
326
326
327
327
These keyboard shortcuts are always entered in lower case except where a custom keyboard command is used within the quotes.
328
328
329
+
## Forcing line breaks
330
+
331
+
There are times when a simple ++enter++ on the keyboard will not give you a new line in markdown. This sometimes occurs when bulleted items use a lot of formatting characters. You may want to add a line break to better format text as well. In cases like these, you need to add two spaces to the end of the line where you want a new line. Since spaces will not be visible in some markdown editors, this example shows the spaces being entered:
332
+
333
+
* **A bullet item with extra formatting** ++space+space++
334
+
* **Another item**
335
+
329
336
## Superscript, subscript and special symbols
330
337
331
338
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:
@@ -354,7 +361,7 @@ Enter subscript by surrounding your text with the `~` tag (H~2~0 is `H~2~0`) and
354
361
355
362
Some of you may 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.
356
363
357
-
Following the conclusion, you can have your notations in a numbered list to match the superscript or enter them as links. Both examples are shown here:
364
+
Following the conclusion, you can have your notations in a numbered list to match the superscript or enter them as links. Shown here are both examples:
358
365
359
366
1. "How Multiples Are Used In Text" by Wordy W. McWords [https://site1.com](https://site1.com)
360
367
2. "Using Superscript In Text" by Sam B. Supersecret [https://site2.com](https://site2.com)
@@ -364,7 +371,7 @@ or
364
371
[1](https://site1.com) "How Multiples Are Used In Text" by Wordy W. McWords
365
372
[2](https://site2.com) "Using Superscript In Text" by Sam B. Supersecret
366
373
367
-
And here is what that all looks like in your editor:
374
+
Here is what that all looks like in your editor:
368
375
369
376
```text
370
377
1. "How Multiples Are Used In Text" by Wordy W. McWords [https://site1.com](https://site1.com)
@@ -379,17 +386,17 @@ or
379
386
380
387
## Highlighting text
381
388
382
-
Another possible way to enhance documentation is with ==highlighting==. Highlighting is handled by surrounding the text with `==`.
389
+
Another possible way to enhance documentation is with ==highlighting==. You can use highlighting by surrounding the text with `==`.
383
390
384
391
This looks like this in your editor:
385
392
386
393
```bash
387
-
Another possible way to enhance documentation is with ==highlighting==. Highlighting is handled by surrounding the text with `==`.
394
+
Another possible way to enhance documentation is with ==highlighting==. You can use highlighting by surrounding the text with `==`.
388
395
```
389
396
390
397
## Grouping different formatting types
391
398
392
-
Rocky documentation offers some elegant formatting options when combining multiple elements within another element. For instance, an admonition with a numbered list:
399
+
Rocky documentation offers some elegant formatting options when combining multiple elements within another element. For example, an admonition with a numbered list:
393
400
394
401
!!! note
395
402
@@ -476,9 +483,57 @@ You can even embed a table or block quote (literally any formatting item type) w
476
483
3. Many examples exist, but the above illustrates that it is possible to nest everything within. Just remember the four (4) magic spaces.
477
484
```
478
485
486
+
## Non-displaying characters
487
+
488
+
There are some characters in markdown that will not display properly. Sometimes it is because these characters are HTML or other tag types (links for example). There might be times when writing documentation that you **need** to display these characters to get your point across. The rule to display these characters is to escape them. Here is a table of these non-displaying characters followed by a code block that shows the table code.
| < > | angle brackets (used for direct HTML) |
518
+
| \( \) | parentheses (used for link content) |
519
+
| \# | pound sign (used for markdown headers) |
520
+
| | | pipe (used in tables) |
521
+
| + | plus sign (used in tables) |
522
+
| - | minus sign or hyphen (used in tables and bullets) |
523
+
| ! | exclamation (used in admonitions and tables) |
524
+
```
525
+
526
+
The last code shows that certain characters require their HTML character code if used in a table.
527
+
528
+
In actual text, you would escape the character. For example, `\|` will show the pipe symbol, `\>` will show the angle bracket symbol, `\+` will show the plus sign, `\-` will show the minus sign, and `\!` will show the exclamation mark.
529
+
530
+
You can see that if we get rid of the back ticks in this sentence:
531
+
532
+
In actual text, you would escape the character. For example, \| will show the pipe symbol, \> will show the angle bracket symbol, \+ will show the plus sign, \- will show the minus sign, and \! will show the exclamation mark.
533
+
479
534
## One final item - comments
480
535
481
-
From time to time, you may want to add a comment to your markdown that will not display when rendered. Many reasons exist for this. For instance, if you want to add a placeholder for something that will be added later, you could use a comment to mark your spot.
536
+
From time to time, you might want to add a comment to your markdown that will not display when rendered. Many reasons exist for this. If you want to add a placeholder for something that you are adding later, you could use a comment to mark your spot.
482
537
483
538
The best way to add a comment to your markdown is to use the square brackets "[]" around two forward slashes "//" followed by a colon and the content. This would look like this:
484
539
@@ -504,6 +559,6 @@ A comment should have a blank line before and after the comment.
504
559
505
560
Document formatting with headings, 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.
506
561
507
-
You do not *have* to use advanced formatting options. Overuse of special elements can 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.
562
+
You do not *have* to use advanced formatting options. Overuse of special elements can add clutter. Learning to use these formatting items conservatively and well can be very helpful to get your point across in a document.
508
563
509
564
Lastly, to make formatting easier, consider changing your markdown editor's TAB value to four (4) spaces.
0 commit comments