You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title: #ARTICLE TITLE in 35 chars or less, most important for SEO. Best to match H1 and TOC, but doesn't have to.
3
3
titleSuffix: Configuration Manager
4
-
description:
4
+
description: # A summary of the content. 75-300 characters. Used in site search. Sometimes used on a search engine results page for improved SEO. Always end with period.
5
5
ms.date: mm/dd/yyyy
6
6
ms.prod: configuration-manager
7
7
ms.technology: configmgr-other #analytics app client comanage compliance core mdm mdt osd other protect sdk sum
This docs.ms template contains examples of markdown syntax, as well as guidance on setting the metadata. It is available in the root directory of each EM Pilot repository (e.g. ~/Azure-RMSDocs-pr
20
-
/template.md) and is meant to be read as a markdown file, although you can refer to [the published version](https://stage.docs.microsoft.com/en-us/rights-management/template) to see how the markdown examples rendeer.
21
-
22
-
When creating a markdown file you should copy the template to a new file, fill out the metadata as specified below, set the H1 heading above to the title of the article, and delete the content.
19
+
This docs.ms template contains examples of markdown syntax, and guidance on setting the metadata. It's available in the root directory of the MEM repository (`~\memdocs-pr\template-configmgr.md`).
23
20
21
+
When you create a new markdown file article, **Save as** this template to a new file, fill out the metadata as specified below, set the H1 heading above (`#`) to the title of the article, and delete the template content.
24
22
25
23
## Metadata
26
24
27
-
The full metadata block is above, divided into required fields and optional fields; see the [OPS metadata cheatsheet](https://ppe.msdn.microsoft.com/en-us/ce-csi-docs/ops/ops-onboarding/managing-content/content-meta-data) for more details. Some key notes:
25
+
The full metadata block is above the markdown between the `---` lines. For more information, see [Metadata attributes](https://review.docs.microsoft.com/en-us/help/contribute/metadata-attributes?branch=main) in the contributor guide. Some key notes:
26
+
27
+
- You _must_ have a space between the colon (`:`) and the value for a metadata element.
28
+
29
+
- Remove all metadata comments (`#`)
30
+
31
+
- Colons in a value (like the title) break the metadata parser. In their place, use the HTML encoding `:` (for example, `title: Azure Rights Management: the basics`).
32
+
33
+
-`title`: This title appears in search engine results and the browser tab.
34
+
- Don't include a pipe (`|`) with the product name, the build handles that automatically with the `titleSuffix` attribute.
35
+
- Don't end with a period.
36
+
- Use Microsoft style _sentence case_.
37
+
- The title can match the H1 heading (`#`) and the name in the tox.yml, but doesn't have to.
38
+
- It should be roughly 35 characters or less to allow for the titleSuffix and best search engine optimization (SEO).
39
+
40
+
-`titleSuffix`: Should always be `Configuration Manager` for ConfigMgr content. This value is appended to the title, for example, "title - titleSuffix | Microsoft Docs"
41
+
42
+
-`description`: Summarize the content, shows in search engine results. 75-300 characters. Always end with a period.
43
+
44
+
-`ms.date`: After you Save As this template to the target file, with the Docs Authoring Pack extension installed, right-click anywhere in the .md file to **Update `ms.date` metadata value** and save the file.
45
+
46
+
-`author`: The author field contains the **Github username** of the author.
47
+
- This value is used in GitHub notifications, assignments, and other build automation in both the private and public repositories.
48
+
- It's also used to display the first (left-most) contributor in the published article.
49
+
50
+
-`ms.author` & `manager`: Microsoft aliases. ms.author and author are typically the same.
51
+
-`reviewer`: Optionally can specify the name of the PM associated with the article. Just for reference, not currently used by any automation.
52
+
53
+
-`ms.prod`: Should always be `configuration-manager` for ConfigMgr content.
54
+
55
+
-`ms.technology`: Select one of the options based on the feature area. Prefix all options with `configmgr-`.
28
56
29
-
- You **must** have a space between the colon (:) and the value for a metadata element.
30
-
- If an optional metadata element does not have a value, comment out the element with a # (do not leave it blank or use "na"); if you are adding a value to an element that was commented out, be sure to remove the #.
31
-
- Colons in a value (e.g., a title) break the metadata parser. In their place, use the HTML encoding of : (e.g., "title: Azure Rights Management: the basics | Azure RMS").
32
-
-**title**: This title will appear in search engine results. The title should end with a pipe (|) followed by the name of the service (e.g. see above). The title need not (and probably should not) be identical to the title in your H1 heading. It should be roughly 65 characters (including | SERVICE NAME)
33
-
-**author**, **manager**, **reviewer**: The author field should contain the **Github username** of the author, not their alias. The "manager" and "reviewer" fields, on the other hand, should contain aliases. ms.reviewer specifies the name of the PM associated with the article or service.
34
-
-**ms.assetid**: This is the GUID of the article from CAPS. When creating a new markdown file, get a GUID from [https://www.guidgenerator.com](https://www.guidgenerator.com).
35
-
-**ms.prod**, **ms.service**, **ms.technology**, **ms.devlang**, **ms.topic**, **ms.tgt_pltfrm**: Possible values for these elements can be found [here](https://microsoft.sharepoint.com/teams/STBCSI/Insights/_layouts/15/WopiFrame.aspx?sourcedoc=%7b7A321BF1-0611-4184-84DA-A0E964C435FA%7d&file=WEDCS_MasterList_CSIValues.xlsx&action=default).
57
+
-`ms.topic`: Select one of the options based on the content type. This attribute is used in calculating content health (different content types are used differently by customers, so have different metrics).
36
58
37
-
## Basic Markdown and GFM
59
+
-`ms.localizationpriority`: Medium is the default, which is machine translation. For specific, high priority content that requires human translation (extra cost), set this value to high. For SDK, MDT, or other components that are only en-us, set this value to null for no localization.
38
60
39
-
All basic and Github-flavored markdown is supported. For more information on these, see:
61
+
## Basic markdown and GFM
40
62
63
+
All basic and Github-flavored markdown (GFM) is supported. For more information, see the following articles:
64
+
65
+
-[Docs Markdown reference in the Contributor Guide](https://review.docs.microsoft.com/help/contribute/markdown-reference?branch=main)
Examples of first- and second-level headings are above.
47
72
48
-
There **must** be only one first-level heading in your topic, which will be displayed as the on-page title.
73
+
There **must** be only one first-level heading (`#`, also known as H1) in your article, which is displayed as the published title at the top of the page.
74
+
75
+
Second-level headings (`##`, also known as H2) generate the on-page TOC that appears in the **In this article** section beside or underneath the on-page title.
76
+
77
+
Limit the length of second-level headings to avoid excessive line wraps.
49
78
50
-
Second-level headings will generate the on-page TOC that appears in the "In this article" section underneath the on-page title.
79
+
Make sure _all_ headings of any level have a unique name for the article. The build creates an anchor for all headings on the page using kebab formatting. For example, from the [Docs Markdown reference](https://review.docs.microsoft.com/help/contribute/markdown-reference?branch=main) article, the heading **Alerts (Note, Tip, Important, Caution, Warning)** becomes the anchor `#alerts-note-tip-important-caution-warning`. If there are duplicate headings, then the anchors don't behave properly. This behavior also applies when using include files, make sure the headings are unique across the main markdown file, and all include markdown files.
80
+
81
+
Don't skip levels. For example, don't have an H3 (`###`) without a parent H2 (`##`).
82
+
83
+
Configuration Manager content does use custom anchors in some articles. They're almost always prefixed with `bkmk_`, for example, `bkmk_client`. These anchors can help reduce the anchor size, but does require HTML code that may not always be supported by the docs build system. There's other functionality with the Docs Authoring Pack and the build validation that only works with native header anchors. Use custom anchors sparingly, and remove them in older articles when possible. When removing custom anchors, make sure to update all internal links from the old custom anchor to the native header kebab format.
51
84
52
85
### Third-level heading
86
+
87
+
Third-level headings (and beyond) can be any length, as they don't appear **In this article**.
88
+
53
89
#### Fourth-level heading
90
+
54
91
##### Fifth level heading
55
-
###### Sixth-level heading
56
92
57
93
## Text styling
58
94
59
-
*Italics*
95
+
_Italics_ (a single asterisk (`*`) also works, but the underscore (`_`) helps differentiate with the double asterisk (`**`) for bold)
60
96
61
97
**Bold**
62
98
63
99
~~Strikethrough~~
64
100
101
+
## Links
65
102
103
+
> [!TIP]
104
+
> Use the **Docs Authoring Pack** extension to easily add links!
105
+
>
106
+
> 1.**Alt** + **M** to open the Docs Authoring Pack menu.
107
+
> 1. Select **Link** and then follow the prompts.
108
+
>
109
+
> It supports headings in the current and other files too! (Just not the custom `bkmk` anchors that are sometimes used in this content.)
66
110
67
-
## Links
111
+
For more information, see [Add links to articles](https://review.docs.microsoft.com/help/contribute/links-how-to?branch=main) in the contributor guide.
68
112
69
-
To link to a markdown file in the same repo, use [relative links](https://www.w3.org/TR/WD-html40-970917/htmlweb.html#h-5.1.2).
113
+
### Article in the same repo
70
114
71
-
- Example: [What is Azure Rights Management](./understand-explore/what-is-azure-rights-management.md)
115
+
To link to an article in the same repo (for example, Configuration Manager, Intune, or Autopilot), use **file-relative links**. These links have the path to the target as relative to the current file, and always include the `.md` or `.yml` extension. For example, `[Get support for Endpoint analytics](../analytics/get-support.md)`
72
116
73
-
To link to a header in the same markdown file, view the source of the published article, find the id of the head (e.g. `id="blockquote"`, and link using # + id (e.g. `#blockquote`).
117
+
#### Link to headings
74
118
75
-
- Example: [Blockquotes](#blockquote)
119
+
To link to a heading _in the same markdown file_, add just the anchor as the link. It's either a custom HTML anchor (`#bkmk_client`) or the kebab case of the header. For example: `[Ordered list with an embedded list](#ordered-list-with-an-embedded-list)`.
76
120
77
-
To link to a header in a markdown file in the same repo, use relative linking + hashtag linking.
121
+
To link to a heading _in a markdown file in the same repo_, use relative linking + hashtag linking. For example: `[Help and support](../analytics/get-support.md#help-and-support)`
78
122
79
-
- Example: [technical overiew of the sign-up process](./understand-explore/rms-for-individuals-user-signup.md#technical-overview-of-the-sign-up-process)
123
+
### Another docs.ms article
80
124
81
-
To link to an external file, use the full URL as the link.
125
+
To link to another docs.ms article not in the same repo, use a **root-relative link**. This style supports the potential future use of the doc content in a separate disconnected environment, like for a high security government customer, which would have a different domain. For example, `[Public contributor guide](/contribute/additional-resources)`.
82
126
83
-
- Example: [Github](http://www.github.com)
127
+
### External URLs
84
128
85
-
If a URL appears in a markdown file, it will be transformed into a clickable link.
129
+
To link to an external file, use the full URL as the link. For example: `[Github](https://www.github.com)`
86
130
87
-
- Example: http://www.github.com
131
+
- The link should always be **HTTPS**.
132
+
- Remove any local from the URL, unless it doesn't work without it. Most all microsoft.com properties support language neutral URLs.
88
133
89
-
##Lists
134
+
### Example links
90
135
91
-
### Ordered lists
136
+
If you need to provide an example of a URL in the article, enclose it in a code block. For example: `https://www.contoso.com`
137
+
This style makes sure the URL is ignored during build validation and the broken links report.
92
138
93
-
1. This
94
-
1. Is
95
-
1. An
96
-
1. Ordered
97
-
1. List
139
+
### Tips for links
98
140
141
+
When your pull request runs, the build system validates all file-relative links and non-custom anchors. It will return a warning if it can't resolve a link.
99
142
100
-
#### Ordered list with an embedded list
143
+
VSCode supports file-relative links and anchors, so you can easily navigate between pages, and test that links are valid.
101
144
102
-
1. Here
103
-
1. comes
104
-
1. an
105
-
1. embedded
106
-
1. Miss Scarlett
107
-
1. Professor Plum
108
-
1. ordered
109
-
1. list
145
+
There's a broken link report that runs once a week in the build system:
110
146
147
+
1. Go to https://ops.microsoft.com.
148
+
1. Sign in with GitHub.
149
+
1. Go to the **memdocs-pr** repo.
150
+
1. Select the **Broken Links** tab.
111
151
112
-
### Unordered Lists
152
+
Don't use URL shorteners like `go.microsoft.com/fwlink` or `aka.ms`. Include the full URL to the target.
153
+
154
+
For more information, see [Add links to articles](https://review.docs.microsoft.com/help/contribute/links-how-to?branch=main) in the contributor guide.
113
155
114
-
- This
115
-
- is
116
-
- a
117
-
- bulleted
118
-
- list
156
+
## Lists
119
157
158
+
### Ordered lists
159
+
160
+
1. This list is ordered.
161
+
1. This list is ordered.
162
+
1. This list is ordered.
163
+
1. This list is ordered.
164
+
1. This list is ordered.
165
+
166
+
You can explicitly number each line if needed, but this style lets the build autonumber it. This style is beneficial if you need to add or remove a step.
167
+
168
+
#### Ordered list with an embedded list
120
169
121
-
##### Unordered list with an embedded lists
170
+
1. This list is ordered.
171
+
1. This list is ordered.
172
+
1. This list is ordered.
173
+
1. This list is ordered.
174
+
1. This list is embedded.
175
+
1. This list is embedded.
176
+
1. This list is ordered.
177
+
1. This list is ordered.
122
178
123
-
- This
124
-
- bulleted
125
-
- list
126
-
- Mrs. Peacock
127
-
- Mr. Green
128
-
- contains
129
-
- other
130
-
1. Colonel Mustard
131
-
1. Mrs. White
132
-
- lists
179
+
### Unordered Lists
133
180
181
+
- This list is bulleted.
182
+
- This list is bulleted.
183
+
- This list is bulleted.
184
+
- This list is bulleted.
185
+
- This list is bulleted.
186
+
187
+
#### Unordered list with embedded lists
188
+
189
+
- This list is bulleted.
190
+
- This list is bulleted.
191
+
- This list is bulleted.
192
+
- This list is embedded.
193
+
- This list is embedded.
194
+
- This list is bulleted.
195
+
- This list is bulleted.
196
+
1. This list is embedded and ordered.
197
+
1. This list is embedded and ordered.
198
+
- This list is bulleted.
134
199
135
200
## Horizontal rule
136
201
@@ -144,6 +209,7 @@ If a URL appears in a markdown file, it will be transformed into a clickable lin
144
209
| col 2 is | centered | $12 |
145
210
| col 1 is default | left-aligned | $1 |
146
211
212
+
The Docs Authoring Pack has features to manage markdown tables. Select the entire table, then right-click to see the options.
147
213
148
214
## Code
149
215
@@ -156,33 +222,37 @@ If a URL appears in a markdown file, it will be transformed into a clickable lin
156
222
flushTimeout": "00:00:30"
157
223
}
158
224
}
159
-
```
225
+
```
160
226
161
227
### In-line code
162
228
163
-
This is an example of `in-line code`.
229
+
This sentence includes an example of `in-line code`.
164
230
165
-
## Blockquotes
231
+
## Blockquote
166
232
167
233
> The drought had lasted now for ten million years, and the reign of the terrible lizards had long since ended. Here on the Equator, in the continent which would one day be known as Africa, the battle for existence had reached a new climax of ferocity, and the victor was not yet in sight. In this barren and desiccated land, only the small or the swift or the fierce could flourish, or even hope to survive.
168
234
169
235
## Images
170
236
237
+
Use the Docs Authoring Pack menu to easily insert media.
238
+
239
+
Always include alt text for accessibility, and always end it with a period.
240
+
171
241
### Static Image
172
242
173
-
:::image type="content" source="memdocs/media/docs-github-edit.png" alt-text="This is the alt text.":::
243
+
:::image type="content" source="memdocs/media/docs-github-edit.png" alt-text="This sentence is the alt text.":::
174
244
175
245
### Image with lightbox
176
246
177
-
:::image type="content" source="memdocs/media/docs-github-edit.png" alt-text="This is the alt text." lightbox="memdocs/media/docs-github-edit.png":::
247
+
:::image type="content" source="memdocs/media/docs-github-edit.png" alt-text="This sentence is the alt text." lightbox="memdocs/media/docs-github-edit.png":::
178
248
179
249
### Animated gif
180
250
181
-
:::image type="content" source="memdocs/media/docs-filter-toc.gif" alt-text="This is the alt text.":::
251
+
:::image type="content" source="memdocs/media/docs-filter-toc.gif" alt-text="This sentence is the alt text.":::
182
252
183
253
### Linked Image
184
254
185
-
[](https://azure.microsoft.com)
255
+
[](https://azure.microsoft.com)
186
256
187
257
## Alerts
188
258
@@ -213,30 +283,11 @@ This is an example of `in-line code`.
0 commit comments