Skip to content

Commit

Permalink
Add to rockydocs_formatting.md (#2541)
Browse files Browse the repository at this point in the history
* note about the Level 1 heading being replaced by the `title:` meta
  • Loading branch information
sspencerwire authored Dec 12, 2024
1 parent b7891db commit c7a26d4
Showing 1 changed file with 14 additions and 1 deletion.
15 changes: 14 additions & 1 deletion docs/guides/contribute/rockydocs_formatting.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ tags:
- formatting
---

# Introduction
## Introduction

This guide highlights our more advanced formatting options, including admonitions, numbered lists, tables, and more.

Expand All @@ -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:
Expand Down

0 comments on commit c7a26d4

Please sign in to comment.