Skip to content

Commit 3958527

Browse files
x0rwPLeVasseur
andauthored
Issue formatting guide for Guideline Form (#183)
* Create issue-formatting-guide.md * Clarification * Clarification * Clarification --------- Co-authored-by: Pete LeVasseur <[email protected]>
1 parent bad4e14 commit 3958527

File tree

1 file changed

+47
-0
lines changed

1 file changed

+47
-0
lines changed

docs/issue-formatting-guide.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
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

Comments
 (0)