mirror of
https://github.com/grafana/grafana.git
synced 2026-08-18 17:15:08 -05:00
docs: contributing updates (#41836)
* contributing updates first draft * ran yarn prettier * updated links * removed test xref * Update contribute/documentation/README.md Co-authored-by: Fiona Artiaga <89225282+GrafanaWriter@users.noreply.github.com> Co-authored-by: Fiona Artiaga <89225282+GrafanaWriter@users.noreply.github.com>
This commit is contained in:
Christopher Moyer
co-authored by
Fiona Artiaga
Fiona Artiaga
parent
e4c84003fb
commit
e1ad692cb3
@@ -1,152 +0,0 @@
|
||||
# Markdown style guide
|
||||
|
||||
This guide for Markdown style helps keep contributions consistent across all documentation created for Grafana products. Refer to the guide and update its sections as needed when a Subject Matter Expert answers a question on Markdown style, or a decision is made about how to apply Markdown.
|
||||
|
||||
## Headers
|
||||
|
||||
In Markdown, the number of "#" symbols creates different heading levels, similar to HTML heading levels:
|
||||
|
||||
**Example**
|
||||
|
||||
- \# is \<h1>.
|
||||
- \#\# is \<h2>.
|
||||
- \#\#\# is \<h3>.
|
||||
|
||||
Start your document with a single `#` for the title of the page. Add the sub-headings with two `##`.
|
||||
|
||||
## Bold and emphasis
|
||||
|
||||
- Make text **bold** using two asterisks.
|
||||
|
||||
**Example:** It is `**important**` to use GitHub-flavored Markdown emoji consistently.
|
||||
|
||||
- Make text `_emphasized_` using single ` _underscores_`. Do not use the single asterisk, it can be easily confused with bold.
|
||||
|
||||
**Example:** GitHub-flavored markdown emoji should _only_ appear in specific cases.
|
||||
|
||||
## Links and references
|
||||
|
||||
Create links to other website by wrapping the display text in square brackets, and the web URL in curved brackets.
|
||||
|
||||
\[text to display](www.website.com)
|
||||
|
||||
**Example:** For more information on including emoji in GitHub-flavored markdown, refer to the [webfx page on emoji](https://www.webfx.com/tools/emoji-cheat-sheet/) for a list of emoji.
|
||||
|
||||
## Block quotes
|
||||
|
||||
Include block quotes inside text using right-facing arrows:
|
||||
|
||||
**Example**
|
||||
|
||||
> Any important information
|
||||
> about emoji can be separated into
|
||||
> a blockquote.
|
||||
|
||||
## Code blocks
|
||||
|
||||
Code blocks written with markdown can show off syntax highlighting specific to different languages. Use three back tics to create a code block:
|
||||
|
||||
```
|
||||
function testNum(a) {
|
||||
if (a > 0) {
|
||||
return "positive";
|
||||
} else {
|
||||
return "NOT positive";
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Write the name of the language after the first set of back tics, no spaces, to show specific syntax highlighting. For example; "\```javascript" produces the following:
|
||||
|
||||
```javascript
|
||||
function testNum(a) {
|
||||
if (a > 0) {
|
||||
return 'positive';
|
||||
} else {
|
||||
return 'NOT positive';
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Tables
|
||||
|
||||
Construct a table by typing the table headings, and separating them with a "|" character. Then, add a second line of dashes ("-") separated by another "|" character. When constructing the table cells, separate each cell data with another "|".
|
||||
|
||||
**Example**
|
||||
|
||||
Heading one | Heading two
|
||||
|
||||
\------------|------------
|
||||
|
||||
Cell one data| Cell two data
|
||||
|
||||
Will publish as:
|
||||
|
||||
| Heading one | Heading two |
|
||||
| ------------- | ------------- |
|
||||
| Cell one data | Cell two data |
|
||||
|
||||
## Lists
|
||||
|
||||
### Numbered lists
|
||||
|
||||
To avoid inconsistent list numbering, use repetitive list numbering:
|
||||
|
||||
\1. First
|
||||
|
||||
\1. Second
|
||||
|
||||
\1. Third
|
||||
|
||||
The list above will always display as:
|
||||
|
||||
1. First
|
||||
2. Second
|
||||
3. Third
|
||||
|
||||
### Unordered lists
|
||||
|
||||
Build a list of points - an unordered or unnumbered list - by using "\-" (hyphen) characters.
|
||||
|
||||
**Example**
|
||||
|
||||
- First
|
||||
- Another item
|
||||
- The last list item
|
||||
|
||||
## Images
|
||||
|
||||
_Do not_ use image shortcodes at this time.
|
||||
|
||||
Include images in a document using the following syntax:
|
||||
|
||||
```
|
||||
|
||||
```
|
||||
|
||||
> **Note:** Alt text does not appear when the user hovers the mouse over the image, but title text does.
|
||||
|
||||
**Examples:**
|
||||
|
||||
- \!\[Grafana logo](/link/to/grafanalogo/logo.png "Grafana logo")
|
||||
- \!\[Example](/static/img/docs/folder_name/alert_test_rule.png "Example title")
|
||||
|
||||
This follows the format of "!", alt text wrapped in "[]" and the link URL wrapped in "()".
|
||||
|
||||
You can also use HTML such as the following:
|
||||
|
||||
```
|
||||
<img src="example.png"
|
||||
alt="Example image"
|
||||
style="float: left; margin-right: 5px;" />
|
||||
```
|
||||
|
||||
In most cases, use the markdown syntax rather than the HTML syntax. Only use the HTML if you need to change the image in ways unsupported by Markdown.
|
||||
|
||||
## Comments
|
||||
|
||||
You can include comments that will not appear in published markdown using the following syntax:
|
||||
|
||||
\[comment]: <> (Comment text to display)
|
||||
|
||||
The word "comment" wrapped in "[]" followed by a ":", a space, "<>", and then the comment itself wrapped in "()".
|
||||
@@ -119,7 +119,7 @@ If that is the case, then use the following format for headings:
|
||||
- Assume all graphics will be exclusively viewed on the web.
|
||||
- Maximum image size is 3840px X 2160px.
|
||||
- Screenshots should be readable, but not too large.
|
||||
- _Do not_ use image shortcodes. Follow the guidance in the [Grafana markdown guide](https://github.com/grafana/grafana/blob/main/contribute/style-guides/documentation-markdown-guide.md#images).
|
||||
- _Do not_ use image shortcodes. Follow the guidance in [Markdown style guide](../documentation/documentation-markdown-guide.md#Images).
|
||||
- Markdown image links are preferred. Only use the HTML image links if you need to style the image in ways unsupported in Markdown.
|
||||
- When you name a file, follow the [file naming conventions](#file-naming-conventions). Example: image-name-7-3.png
|
||||
|
||||
|
||||
Reference in New Issue
Block a user