Do you know all the cool stuff you can do on SSW Rules?
Loading last updated info...
<introEmbed
body={<>
SSW Rules are **technical documentation** presented as practical guidelines that help teams build better software and work more effectively. They capture best practices across coding, architecture, communication, design and project management, making them a living knowledge base that supports consistency, clarity and quality in every project.
This is an **example rule + Markdown/MDX cheatsheet** to give you some guidance around how to write rules and show you the things you can use to format an SSW Rule. For more info see our [GitHub Wiki page.](https://github.com/SSWConsulting/SSW.Rules.Content/wiki/Using-Markdown)
</>}
/>
## Concepts to write rules
There are a few concepts that are applied to structure most SSW Rules:
1. **Show the pain** - Usually in the intro, explain the problem and context around why that rule exists
2. **Give good and bad examples** - Include practical examples for people to better understand the concepts. [Using images is usually the best way to go](/use-images-to-replace-words)
3. **Explain the why, not the how** - A rule isn't a place to document how to use a 3rd party product. You should focus on the reasons **why** we do something, and then link to external documentation on **how** to do something
See a few examples of SSW Rules that follow the structure of good and bad examples, then link off to external documentation for more information:
* [GitHub Issues - Do you use Issue Templates?](/github-issue-templates)
* [Bicep - Do you use User-defined Data Types?](/bicep-user-defined-data-types)
* [Do you know how to backup data on SQL Azure?](/do-you-know-how-to-backup-data-on-sql-azure)
### 1. Headings, paragraphs, and blockquotes
```markdown
## This is a heading 2
### This is a heading 3
#### This is a heading 4
##### This is a heading 5
###### This is a heading 6 and below is a blockquote
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.
> \- Someone famous
```
**Figure: Markdown to generate headings and blockquotes**
<asideEmbed
variant="info"
body={<>
Do **not** use Heading 1 (`<h1>`) in the content, even with the good intention of improving SEO. The page title already uses `<h1>`, and adding more can harm accessibility and semantic structure. As per [MDN guidelines - avoid multiple \<h1> elements on the same page](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements#avoid_using_multiple_h1_elements_on_one_page).
</>}
figureEmbed={{ preset: "default", figure: "XXX", shouldDisplay: false }}
/>
## This is a heading 2
Lorem ipsum dolor sit amet. Ut enim ad minim veniam, quis nostrud exercitation. qui officia deserunt mollit anim id est laboru.
## This is a heading 2 with some **emphasized text** by making it bold
**Tip:** See [text decoration section](#2-text-decorations) for more details on making the text bold.
### This is a heading 3
Lorem ipsum dolor sit amet. Ut enim ad minim veniam, quis nostrud exercitation. qui officia deserunt mollit anim id est laboru.
#### This is a heading 4
Lorem ipsum dolor sit amet. Ut enim ad minim veniam, quis nostrud exercitation. qui officia deserunt mollit anim id est laboru.
##### This is a heading 5
Lorem ipsum dolor sit amet. Ut enim ad minim veniam, quis nostrud exercitation. qui officia deserunt mollit anim id est laboru.
###### This is a heading 6
Lorem ipsum dolor sit amet. Ut enim ad minim veniam, quis nostrud exercitation. qui officia deserunt mollit anim id est laboru.
...and this is a blockquote:
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.\
> \- Someone famous
***
### 2. Text decorations
```markdown
_This text will be italic._
**And this text will be bold.**
~~strikethrough.~~
_You **can** combine them_.
And ==these words== will be highlighted.
```
**Figure: Markdown to generate different text styles**
*This text will be italic.*
**And this text will be bold.**
~~strikethrough.~~
*You **can** combine them*.
And ==these words== will be highlighted.
***
### 3. Lists
```markdown
#### Unordered lists
- This is the first item of an unordered list
- This is the second item of an unordered list
1. This is the first item of an ordered list inside an unordered list
2. This is the second item of an ordered list inside an unordered list
- This is the third item of an unordered list
- This is the first item of an unordered list inside another
- This is the second item of an unordered list inside another
1. This is the first item of an ordered list inside a nested unordered list
2. This is the second item of an ordered list inside a nested unordered list
#### Ordered lists
1. This is the first item of an ordered list
2. This is the second item of an ordered list
3. This is the third item of an ordered list
- This is the first item of an unordered list inside an ordered list
- This is the second item of an unordered list inside an ordered list
1. This is the first item of an ordered list inside another
2. This is the second item of an ordered list inside another
```
**Figure: Markdown to generate lists**
#### Unordered lists
* This is the first item of an unordered list
* This is the second item of an unordered list
1. This is the first item of an ordered list inside an unordered list
2. This is the second item of an ordered list inside an unordered list
* This is the third item of an unordered list
* This is the first item of an unordered list inside another
* This is the second item of an unordered list inside another
1. This is the first item of an ordered list inside a nested unordered list
2. This is the second item of an ordered list inside a nested unordered list
#### Ordered lists
1. This is the first item of an ordered list
2. This is the second item of an ordered list
3. This is the third item of an ordered list
* This is the first item of an unordered list inside an ordered list
* This is the second item of an unordered list inside an ordered list
1. This is the first item of an ordered list inside another
2. This is the second item of an ordered list inside another
***
### 4. Links
```md
[link text](https://www.url.com "link title")
```
**Figure: Markdown to generate links**
This is [an internal link](https://www.ssw.com.au).
This is [an internal link with title](https://www.ssw.com.au "This is a link title") (hover me).
This is [an external link](https://www.google.com).
<asideEmbed
variant="greybox"
body={<>
**Cool link features:**
* We use [icons on files' links](/use-icons-to-not-surprise-users) to not to surprise users
* Our main headings auto-generated [anchor links](/anchor-links) so users can easily access a section of a long page like this one.
E.g. To go straight to this section of the page, you can access [https://ssw.com.au/rules/rule/#4-links](#4-links)
</>}
figureEmbed={{ preset: "default", figure: "XXX", shouldDisplay: false }}
/>
***
### 5. Boxes
```md
<asideEmbed
variant="greybox"
body={<>
This is a box using the class "greybox".
</>}
figureEmbed={{
preset: "default",
figure: "XXX",
shouldDisplay: false
}}
/>
```
**Figure: MDX to generate boxes**
<asideEmbed
variant="greybox"
body={<>
This is a box using the class "greybox".
</>}
figureEmbed={{ preset: "default", figure: "XXX", shouldDisplay: false }}
/>
<asideEmbed
variant="highlight"
body={<>
This is a box using the class "highlight".
</>}
figureEmbed={{ preset: "default", figure: "XXX", shouldDisplay: false }}
/>
<asideEmbed
variant="info"
body={<>
This is a \<div> using the class "info". Works the same as using a \<p> . Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation.
</>}
figureEmbed={{ preset: "default", figure: "XXX", shouldDisplay: false }}
/>
<asideEmbed
variant="china"
body={<>
This is a \<div> using the class "china". Works the same as using a \<p> . Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
</>}
figureEmbed={{ preset: "default", figure: "XXX", shouldDisplay: false }}
/>
<asideEmbed
variant="codeauditor"
body={<>
This is a \<div> using the class "codeauditor". Works the same as using a \<p> . Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
</>}
figureEmbed={{ preset: "default", figure: "XXX", shouldDisplay: false }}
/>
<asideEmbed
variant="todo"
body={<>
This is a \<div> using the class "todo". Works the same as using a \<p> . Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco.
</>}
figureEmbed={{ preset: "default", figure: "XXX", shouldDisplay: false }}
/>
<asideEmbed
variant="warning"
body={<>
This is a \<div> using the class "warning". Works the same as using a \<p> . Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
</>}
figureEmbed={{ preset: "default", figure: "XXX", shouldDisplay: false }}
/>
<asideEmbed
variant="tips"
body={<>
This is a \<div> using the class "tips". Works the same as using a \<p> . Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
</>}
figureEmbed={{ preset: "default", figure: "XXX", shouldDisplay: false }}
/>
***
### 6. Images
```md
<imageEmbed
alt="Image"
size="large"
showBorder={true}
figureEmbed={ {
preset: "default",
figure: "Caption text",
shouldDisplay: true
} }
src="/uploads/rules/rule/image-file.jpg"
/>
```
#### Classes for images
<imageEmbed
alt="Image"
size="small"
showBorder={true}
figureEmbed={{
preset: "default",
figure: 'Image rendered with size="small"',
shouldDisplay: true
}}
src="/uploadshttps://images.unsplash.com/photo-1513677785800-9df79ae4b10b?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1000&q=80"
/>
<imageEmbed
alt="Image"
size="medium"
showBorder={true}
figureEmbed={{
preset: "default",
figure: 'Image rendered with size="medium"',
shouldDisplay: true
}}
src="/uploadshttps://images.unsplash.com/photo-1513677785800-9df79ae4b10b?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1000&q=80"
/>
<imageEmbed
alt="Image"
size="large"
showBorder={true}
figureEmbed={{
preset: "default",
figure: 'Image rendered with size="large"',
shouldDisplay: true
}}
src="/uploadshttps://images.unsplash.com/photo-1513677785800-9df79ae4b10b?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1000&q=80"
/>
<imageEmbed
alt="Image"
size="large"
showBorder={false}
figureEmbed={{
preset: "default",
figure: 'Image rendered with showBorder="false"',
shouldDisplay: true
}}
src="/uploadshttps://images.unsplash.com/photo-1513677785800-9df79ae4b10b?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1000&q=80"
/>
#### Extra examples
<imageEmbed
alt="Image"
size="small"
showBorder={false}
figureEmbed={{
preset: "default",
figure:
"How a smaller image (400px) works with long caption. Full screen on mobile, real width on larger screens...",
shouldDisplay: true
}}
src="/uploadshttps://images.unsplash.com/photo-1528820454441-189cd70a6c3c?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=400&q=80"
/>
<imageEmbed
alt="Image"
size="small"
showBorder={false}
figureEmbed={{
preset: "default",
figure: "...and with a short caption",
shouldDisplay: true
}}
src="/uploadshttps://images.unsplash.com/photo-1528820454441-189cd70a6c3c?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=400&q=80"
/>
<asideEmbed
variant="todo"
body={<>
TODO: Make these images hosted internally as per [Do you make sure your images are hosted internally?](/images-should-be-hosted-internally)
</>}
figureEmbed={{ preset: "default", figure: "XXX", shouldDisplay: false }}
/>
***
### 7. Captions
```md
<figureEmbed figureEmbed={ {
preset: "badExample",
figure: "Figure: Caption for bad examples",
shouldDisplay: true
} } />
<figureEmbed figureEmbed={ {
preset: "okExample",
figure: "Figure: Caption for OK examples",
shouldDisplay: true
} } />
<figureEmbed figureEmbed={ {
preset: "goodExample",
figure: "Figure: Caption for good examples",
shouldDisplay: true
} } />
```
#### Captions on images
<imageEmbed
alt="Image"
size="large"
showBorder={true}
figureEmbed={{
preset: "badExample",
figure: "Caption for bad images",
shouldDisplay: true
}}
src="/uploadshttps://images.unsplash.com/photo-1542014740373-51ad6425eb7c?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1000&q=80"
/>
<imageEmbed
alt="Image"
size="large"
showBorder={true}
figureEmbed={{
preset: "default",
figure: "Caption for regular images",
shouldDisplay: true
}}
src="/uploadshttps://images.unsplash.com/photo-1513677785800-9df79ae4b10b?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1000&q=80"
/>
<imageEmbed
alt="Image"
size="large"
showBorder={true}
figureEmbed={{
preset: "okExample",
figure: "Caption for OK images",
shouldDisplay: true
}}
src="/uploadshttps://images.unsplash.com/photo-1478998674531-cb7d22e769df?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1000&q=80"
/>
<imageEmbed
alt="Image"
size="large"
showBorder={true}
figureEmbed={{
preset: "goodExample",
figure: "Caption for good images",
shouldDisplay: true
}}
src="/uploadshttps://images.unsplash.com/photo-1491472253230-a044054ca35f?ixlib=rb-1.2.1&auto=format&fit=crop&w=1000&q=80"
/>
#### Captions on boxes
<asideEmbed
variant="greybox"
body={<>
This is an example of a bad grey box.
</>}
figureEmbed={{
preset: "badExample",
figure: "Caption for bad examples",
shouldDisplay: true
}}
/>
<asideEmbed
variant="greybox"
body={<>
This is an example of a normal grey box.
</>}
figureEmbed={{
preset: "default",
figure: "Caption for normal examples",
shouldDisplay: true
}}
/>
<asideEmbed
variant="greybox"
body={<>
This is an example of a OK grey box.
</>}
figureEmbed={{
preset: "okExample",
figure: "Caption for ok examples",
shouldDisplay: true
}}
/>
<asideEmbed
variant="greybox"
body={<>
This is an example of a good grey box.
</>}
figureEmbed={{
preset: "goodExample",
figure: "Caption for good examples",
shouldDisplay: true
}}
/>
***
### 8. Videos
#### Code for videos
```md
<youtubeEmbed url="https://www.youtube.com/embed/0ugMkda9IBw" description={"Video: Top 5 Reasons Why ASP.NET MVC is Great (3 min)"} />
```
**Figure: MDX to add videos and video captions**
#### Example
Check out this video - it's responsive!
<youtubeEmbed url="https://www.youtube.com/embed/0ugMkda9IBw" description="Video: Top 5 Reasons Why ASP.NET MVC is Great (3 min)" />
***
### 9. Code
To include code block in Markdown, start with 3 backticks \`\`\` on a new line, write or paste your code, and then end with 3 backticks on a new line.
For syntax highlighting in code blocks, add the language name right after the opening backticks. Learn more on [Do you set the language on code blocks?](/set-language-on-code-blocks)
To add inline code in Markdown, wrap the code snippet with single backticks. See `this text` as inline code for example.
```md
This is a piece of code in a code block
```
<figureEmbed
figureEmbed={{
preset: "badExample",
figure:
"Figure: Bad example - Because this code doesn't include the language used",
shouldDisplay: true
}}
/>
See this [json file](https://unpkg.com/[email protected]/lib/grammars/manifest.json) for all supported languages and their aliases we can use in SSW Rules. See some examples:
```javascript
let iceCream = "chocolate";
if (iceCream === "chocolate") {
alert("Yay, I love chocolate ice cream!");
} else {
alert("Awwww, but chocolate is my favorite...");
}
```
**Figure: Javascript code block**
```sql
IF EXISTS (SELECT 1 FROM
INFORMATION_SCHEMA.TABLES
WHERE
TABLE_TYPE='BASE TABLE' AND
TABLE_NAME='Employees'
)
ALTER TABLE [dbo].[Employees]( …… ) ON [PRIMARY]
ELSE
CREATE TABLE [dbo].[Employees]( …… ) ON [PRIMARY]
```
**Figure: SQL code block**
```csharp
public class MyClass
{
public string myField = string.Empty;
public MyClass()
{
}
public void MyMethod(int parameter1, string parameter2)
{
Console.WriteLine("First Parameter {0}, second parameter {1}",
parameter1, parameter2);
}
public int MyAutoImplementedProperty { get; set; }
private int myPropertyVar;
public int MyProperty
{
get { return myPropertyVar; }
set { myPropertyVar = value; }
}
}
```
**Figure: C Sharp code block**
```json
{
"glossary": {
"title": "example glossary",
"GlossDiv": {
"title": "S",
"GlossList": {
"GlossEntry": {
"ID": "SGML",
"SortAs": "SGML",
"GlossTerm": "Standard Generalized Markup Language",
"Acronym": "SGML",
"Abbrev": "ISO 8879:1986",
"GlossDef": {
"para": "A meta-markup language, used to create markup languages such as DocBook.",
"GlossSeeAlso": ["GML", "XML"]
},
"GlossSee": "markup"
}
}
}
}
}
```
**Figure: JSON code block**
***
### 10. Email Templates
#### Code for email template
```md
<emailEmbed
from=""
to="XXX"
cc="YYY"
bcc="ZZZ"
subject="{{ EMAIL SUBJECT }}"
shouldDisplayBody={true}
body={<>
## Hi XXX,
{{ EMAIL CONTENT }}
</>}
figureEmbed={{
preset: "goodExample",
figure: "Good example - Nice email template",
shouldDisplay: true
}}
/>
```
**Figure: Markdown for email templates**
<emailEmbed
from=""
to="XXX"
cc="YYY"
bcc="ZZZ"
subject="{{ EMAIL SUBJECT }}"
shouldDisplayBody={true}
body={<>
## Hi XXX
{{ EMAIL CONTENT }}
</>}
figureEmbed={{
preset: "goodExample",
figure: "Good example - Nice email template",
shouldDisplay: true
}}
/>
***
### 11. Tables
#### Code for tables
```md
| Tables | Are | Cool |
| :-----------: | ------------: | ----- |
| col 3 is | right-aligned | $1600 |
| col 2 is | centered | $12 |
| zebra stripes | are neat | $1 |
```
**Figure: Markdown to generate tables**
#### Examples
| Tables | Are | Cool |
| :-----------: | ------------: | ----- |
| col 3 is | right-aligned | $1600 |
| col 2 is | centered | $12 |
| zebra stripes | are neat | $1 |
| Markdown | Less | Pretty |
| -------- | --------- | ---------- |
| *Still* | `renders` | **nicely** |
| 1 | 2 | 3 |
***
### 12. Thematic breaks (horizontal rules)
#### Code for hr
```md
---
```
#### Examples
***