|
| 1 | +# Issue Formatting Guide |
| 2 | + |
| 3 | +## Purpose |
| 4 | +This guide outlines Markdown standards when submitting a [Coding Guideline issue template](https://github.com/rustfoundation/safety-critical-rust-coding-guidelines/issues/new?template=CODING-GUIDELINE.yml). |
| 5 | + |
| 6 | +We follow these rules to ensure our content converts cleanly from Markdown to reStructuredText (.rst) when an Issue converted to a Pull Request. During that process the [m2r](https://pypi.org/project/m2r/) converter is used, which is then fed into Sphinx for documentation. |
| 7 | + |
| 8 | +--- |
| 9 | + |
| 10 | +## Supported formatting (does not break conversion from Issue => Pull Request) |
| 11 | +- **Bold** for emphasis or labels (`**Important Note**`). |
| 12 | +- *Italics* for a single word or phrase (`*Warning*`). |
| 13 | +- `inline code` for identifiers and short tokens (`cargo build`). |
| 14 | +- Simple unordered lists: |
| 15 | + - Item 1 |
| 16 | + - Item 2 |
| 17 | +- Simple ordered lists: |
| 18 | + 1. First step |
| 19 | + 2. Second step |
| 20 | + |
| 21 | + |
| 22 | +- Tables with basic content: |
| 23 | + |
| 24 | +| Header 1 | Header 2 | Header 3 | |
| 25 | +|----------|----------|----------| |
| 26 | +| Row 1 Col 1 | Row 1 Col 2 | Row 1 Col 3 | |
| 27 | +| Row 2 Col 1 | Row 2 Col 2 | Row 2 Col 3 | |
| 28 | + |
| 29 | +- Links with clear, simple syntax: `[link text](https://example.com)`. |
| 30 | +- Simple blockquotes: `> This is a quote.`. |
| 31 | + |
| 32 | +--- |
| 33 | +## Unsupported formatting (breaks conversion from Issue => Pull Request) |
| 34 | + |
| 35 | +The following types of formatting are not currently supported in the bodies of text submitted. This may change in the future if we find ways to support them. |
| 36 | + |
| 37 | +- **Nested formatting:** Combining different formatting styles, like **bold around `inline code`**, is unreliable. |
| 38 | +- **Markdown headings:** Using `#`, `##`, or `###` conflicts with Sphinx's heading structure. |
| 39 | +- **Complex lists:** Lists with inconsistent indentation or mixed bullet types often fail. |
| 40 | + - Example: |
| 41 | + ``` |
| 42 | + - A list item |
| 43 | + - Another sub-item |
| 44 | + 1. A nested list. |
| 45 | + ``` |
| 46 | +- **Complex tables:** Tables with merged cells, multi-line content, or rich/nested formatting will likely break. |
| 47 | +- **Standalone horizontal rules:** Using `---` or `***` will be misinterpreted. |
0 commit comments