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
This core-docs template contains examples of Markdown syntax, as well as guidance on setting the metadata. To get the most of it, you must view both the [raw Markdown](https://raw.githubusercontent.com/dotnet/docs/master/styleguide/template.md) and the [rendered view](https://github.com/dotnet/docs/blob/master/styleguide/template.md) (for instance, the raw Markdown shows the metadata block, while the rendered view does not).
3
+
This C++ repo-specific core-docs template contains examples of Markdown syntax, and guidance on setting the metadata. To get the most of it, you must view both the [raw Markdown](https://raw.githubusercontent.com/MicrosoftDocs/cpp-docs/main/styleguide/template.md) and the [rendered view](https://github.com/MicrosoftDocs/cpp-docs/blob/master/styleguide/template.md) (for instance, the raw Markdown shows the metadata block, while the rendered view doesn't).
4
4
5
5
When creating a Markdown file, you should copy 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 content.
6
6
7
7
## Metadata
8
8
9
-
The full metadata block is above (in the [raw Markdown](https://raw.githubusercontent.com/dotnet/docs/master/styleguide/template.md)), divided into required fields and optional fields. Some key notes:
9
+
The full metadata block is yaml data between two lines that only contain `---` at the top of the document contents (in the [raw Markdown](https://raw.githubusercontent.com/MicrosoftDocs/cpp-docs/main/styleguide/template.md)). It's divided into required fields and optional fields. Some key notes:
10
10
11
-
- You **must** have a space between the colon (:) and the value for a metadata element.
12
-
- If an optional metadata element does not have a value, comment out the element with a # or remove it (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 #.
13
-
- Colons in a value (for example, a title) break the metadata parser. In this case, surround the title with double quotes (for example, `title: "Writing .NET Core console apps: An advanced step-by-step guide"`).
14
-
-**title**: This title will appear in search engine results. You can also add a pipe (|) followed by the product name (for example, `title: Developing Libraries with Cross Platform Tools | .NET Core`). The title doesn't need be identical to the title in your H1 heading and it should contain 65 characters or less (including | PRODUCT NAME).
15
-
-**author**, **manager**, **ms.reviewer**: The author field should contain the **GitHub username** of the author, not their alias. The "manager" and "ms.reviewer" fields, on the other hand, should contain Microsoft aliases. ms.reviewer specifies the name of the PM/dev associated with the article or feature.
16
-
-**ms.devlang** defines the technology. Some of the supported values are: `dotnet`, `cpp`, `csharp`, `fsharp`, `vb` and `xml`.
17
-
-**ms.assetid**: This is the GUID of the article that is used for internal tracking purposes such as Business Intelligence (BI). When creating a new Markdown file, you can get a GUID from [Online GUID Generator](https://www.guidgenerator.com/).
11
+
- You **must** have a space between the colon (`:`) and the value for a metadata element.
12
+
- If an optional metadata element doesn't have a value, comment out the element with a `#` or remove it (don't leave it blank or use "na"); if you're adding a value to an element that was commented out, be sure to remove the `#`.
13
+
- Colons in a value (for example, a title) break the metadata parser. In this case, surround the title with double quotes (for example, `title: "Writing Windows console apps: An advanced step-by-step guide"`).
14
+
-**`title`**: This title will appear in search engine results. You can also add a pipe (|) followed by the product name (for example, `title: Developing Libraries with Cross Platform Tools | Microsoft C++`). The default product name is set in the *`docfx.json`* file, so only specify it if necessary. The title doesn't need to be identical to the title in your H1 heading. It should contain 65 characters or less (including \| PRODUCT NAME).
15
+
-**`author`**, **`manager`**, **`ms.author`**: These values are optional and will default to per-directory settings in the *`docfx.json`* file. Set them only if the value is different from the default. The `author` field should contain the **GitHub username** of the author, not their alias. The `manager` and `ms.author` fields, on the other hand, should contain Microsoft aliases. We don't normally include the **`ms.reviewer`** value, but if present, it specifies the name of the PM/dev associated with the article or feature.
16
+
-**`ms.devlang`** defines the technology. This value is optional and will default to per-directory settings in the *`docfx.json`* file. Set it only if the value is different from the default. Some of the supported values are: `dotnet`, `cpp`, `csharp`, `fsharp`, `vb` and `xml`.
17
+
-**`ms.assetid`**: Don't set this value in new articles. It exists only as a historical link to archived versions of the document.
18
18
19
19
## Basic Markdown, GFM, and special characters
20
20
21
-
All basic and GitHub Flavored Markdown (GFM) is supported. For more information on these, see:
21
+
All basic and GitHub Flavored Markdown (GFM) is supported. For more information on Markdown, see:
@@ -27,24 +27,25 @@ Markdown uses special characters such as \*, \`, and \# for formatting. If you w
27
27
28
28
- Put a backslash before the special character to "escape" it (for example, `\*` for a \*)
29
29
- Use the [HTML entity code](https://www.ascii.cl/htmlcodes.htm) for the character (for example, `*` for a *).
30
+
- Markdown allows you to use two spaces at the end of a line to indicate a line break. Because the spaces are invisible in most editors and easy to break, use the alternative of a single backslash (`\`) instead.
30
31
31
32
## Markdown editing tools
32
33
33
34
You can use [Visual Studio Code](https://code.visualstudio.com/) to edit Markdown documents. VS Code has many helpful Markdown extensions, such as:
34
35
35
-
-[docs-markdown](https://marketplace.visualstudio.com/items?itemName=docsmsft.docs-markdown) by Microsoft
36
+
-[Docs Authoring Pack](https://marketplace.visualstudio.com/items?itemName=docsmsft.docs-authoring-pack) by Microsoft
- Contain only lowercase letters, numbers, and hyphens.
43
-
- No spaces or punctuation characters. Use the hyphens to separate words and numbers in the file name.
44
-
- Use action verbs that are specific, such as develop, buy, build, troubleshoot. No -ing words.
45
-
- No small words - don't include a, and, the, in, or, etc.
46
-
- Must be in Markdown and use the .md file extension.
47
-
- Keep file names reasonably short. They are part of the URL for your articles.
44
+
- No spaces or punctuation characters. Use hyphens to separate words and numbers in the file name.
45
+
- Use action verbs that are specific, such as "develop", "buy", "build", "troubleshoot". Don't use "-ing" words.
46
+
- No small words: Don't include "a", "and", "the", "in", "or", and so on.
47
+
- Must be in Markdown and use the `.md` file extension.
48
+
- Keep file names reasonably short. They're part of the URL for your articles.
48
49
49
50
## Headings
50
51
@@ -53,13 +54,13 @@ Use sentence-style capitalization. Always capitalize:
53
54
- The first word of a heading.
54
55
- The word following a colon in a title or heading (for example, "How to: Sort an array").
55
56
56
-
Headings should be done using atx-style, that is, use 1-6 hash characters (#) at the start of the line to indicate a heading, corresponding to HTML headings levels H1 through H6. Examples of first- and second-level headers are used above.
57
+
Headings should be done using atx-style, that is, use 1-6 hash characters (`#`) at the start of the line to indicate a heading, corresponding to HTML headings levels H1 through H6. Examples of first- and second-level headers are used above.
57
58
58
-
There **must** be only one first-level heading (H1) in your topic, which will be displayed as the on-page title.
59
+
There **must** be only one first-level heading (H1) in your article, which will be displayed as the on-page title.
59
60
60
-
If your heading finishes with a `#` character, you need to add an extra `#` character in the end in order for the title to render correctly. For example, `# Async Programming in F# #`.
61
+
If your heading ends with a `#` character, you need to add an extra `#` character in the end in order for the title to render correctly. For example, `# Async Programming in F# #`.
61
62
62
-
There should always be one blank line before and after a heading (except for first-level headings).
63
+
There should always be one blank line before and after a heading (except for first-level headings, which shouldn't have a blank line before).
63
64
64
65
Second-level headings will generate the on-page TOC that appears in the "In this article" section underneath the on-page title.
65
66
@@ -75,18 +76,37 @@ Second-level headings will generate the on-page TOC that appears in the "In this
75
76
76
77
## Text styling
77
78
78
-
*Italics*
79
-
Use for user-generated filenames, folders, and paths (for long items, split onto their own line); new terms; parameter names; user-entered values; and URLs (unless rendered as links, which is the default).
79
+
*Italics*\
80
+
\*Italics\*\
81
+
Use for user-generated filenames, folders, and paths (for long items, split onto their own line); new terms; user-entered values; and URLs (unless rendered as links, which is the default).
80
82
81
-
**Bold**
82
-
Use for UI elements and language keywords.
83
+
**Bold**\
84
+
\*\*Bold\*\*\
85
+
Use for UI elements.
86
+
87
+
**`Bold Code`**\
88
+
\*\*\`Bold Code\`\*\*\
89
+
Use for keywords, operators, and compiler and tool options.
90
+
91
+
*`Italic Code`*\
92
+
\*\`Italic Code\`\*\
93
+
Use for parameters.
94
+
95
+
`Inline Code`\
96
+
\`Inline Code\`\
97
+
Use for non-localizable elements such as library function names, preprocessor macros, fixed filenames, and inline code such as a single variable, expression, or statement.
98
+
99
+
> Blockquote\
100
+
\> Blockquote
101
+
102
+
Use blockquote for error and warning messages, syntax sections, and EBNF content.
83
103
84
104
## Links
85
105
86
106
### Internal Links
87
107
88
-
To link to a header in the same Markdown file (also known as anchor links), you'll need to find out the id of the header you're trying to link to. To confirm the ID, view the source of the rendered article, find the id of the header (for example, `id="blockquote"`), and link using # + id (for example, `#blockquote`).
89
-
The id is auto-generated based on the header text. So, for example, given a unique section named `## Step 2`, the id would look like this `id="step-2"`.
108
+
To link to a header in the same Markdown file (also known as anchor links), you'll need to find out the ID of the header you're trying to link to. To confirm the ID, view the source of the rendered article, find the ID of the header (for example, `id="blockquote"`), and link using `#` + ID (for example, `#blockquote`).
109
+
The ID is auto-generated based on the header text. So, for example, given a unique section named `## Step 2`, the ID would look like this `id="step-2"`.
90
110
91
111
- Example: [Chapter 1](#chapter-1)
92
112
@@ -101,7 +121,7 @@ To link to a header in a Markdown file in the same repo, use relative linking +
101
121
102
122
### Docs Links
103
123
104
-
To link to a file in a different Docs repo, use the docs.microsoft.com relative URL as the link. Do not include the .md suffix.
124
+
To link to a file in a different Docs repo, use the docs.microsoft.com relative URL as the link. Don't include the .md suffix or the language/locale element.
105
125
106
126
- Example: [Universal Windows Platform documentation](/windows/uwp)
107
127
@@ -117,10 +137,11 @@ If a URL appears in a Markdown file, it will be transformed into a clickable lin
117
137
118
138
### Links to APIs
119
139
120
-
The build system has some extensions that allow us to link to .NET Core APIs without having to use external links.
140
+
The build system has some extensions that allow us to link to Managed APIs without having to use external links.
141
+
121
142
When linking to an API, you can use its unique identifier (UID) that is auto-generated from the source code.
122
143
123
-
You can use one of the following syntax:
144
+
You can use one of the following syntax forms:
124
145
125
146
1. Markdown link: `[link_text](xref:UID)`
126
147
2. Auto link: `<xref:UID>`
@@ -135,7 +156,7 @@ For more information about using this notation, see [Using cross reference](http
135
156
136
157
When the UID contains the special characters \` or \#, the UID value needs to be HTML encoded as %60 and %23 respectively as in the following examples:
@@ -144,8 +165,8 @@ Lists should be surrounded by blank lines.
144
165
145
166
### Ordered lists
146
167
147
-
1.This
148
-
1.Is
168
+
1.Example
169
+
1.Of
149
170
1. An
150
171
1. Ordered
151
172
1. List
@@ -156,30 +177,30 @@ Lists should be surrounded by blank lines.
156
177
1. comes
157
178
1. an
158
179
1. embedded
159
-
1.Miss Scarlett
160
-
1.Professor Plum
180
+
1.Scarlet
181
+
1. Plum
161
182
1. ordered
162
183
1. list
163
184
164
185
### Unordered Lists
165
186
166
-
-This
167
-
-is
187
+
-Example
188
+
-of
168
189
- a
169
190
- bulleted
170
191
- list
171
192
172
193
#### Unordered list with an embedded list
173
194
174
-
-This
195
+
-Sometimes
175
196
- bulleted
176
-
-list
177
-
-Mrs. Peacock
178
-
-Mr. Green
179
-
-contains
197
+
-lists
198
+
-Chartreuse
199
+
-Lime
200
+
-contain
180
201
- other
181
-
1.Colonel Mustard
182
-
1.Mrs. White
202
+
1.Magenta
203
+
1.Fuchsia
183
204
- lists
184
205
185
206
## Horizontal rule
@@ -188,13 +209,14 @@ ___
188
209
189
210
## Tables
190
211
191
-
| Tables | Are | Cool|
192
-
| ------------- |:-------------:| -----:|
193
-
| col 3 is | right-aligned | $1600 |
194
-
| col 2 is | centered | $12 |
195
-
| col 1 is default | left-aligned | $1 |
212
+
| Tables | Are | Cool |
213
+
|--|:-:|-:|
214
+
| col 3 is | right-aligned | $1600 |
215
+
| col 2 is | centered | $12 |
216
+
| col 1 is default | left-aligned | $1 |
196
217
197
218
You can use a [Markdown table generator tool](https://www.tablesgenerator.com/markdown_tables) to help creating them more easily. See also [Markdown editing tools](#markdown-editing-tools).
219
+
The C++ standard is to use the table format created by the **`Docs: Consolidate selected table`** tool in the Docs Authoring Pack. Don't try to align the vertical lines in your tables; it's extra work that's easy to break.
198
220
199
221
## Code
200
222
@@ -224,7 +246,7 @@ code that should be included. Use the `#region` and `#endregion` preprocessor sy
224
246
to specify the region of code to include.
225
247
226
248
For cases where regions don't work, you can specify the start and end of a snippet
227
-
using an XML element name in a single line comment. For example, you could write this in C#:
249
+
using an XML element name in a single line comment. For example, you could write this sample region in C#:
228
250
229
251
```csharp
230
252
// <CodeToInclude>
@@ -237,15 +259,35 @@ int sum = i + j;
237
259
In other languages, use the comment syntax for that language.
238
260
239
261
Finally, you can use line numbers: `#L1-L10` would include lines 1 through 10. We discourage line numbers
240
-
because they are very brittle.
262
+
because they're brittle.
241
263
242
264
Including snippets from full programs ensures that all code runs through our Continuous Integration (CI)
243
265
system. However, if you need to show something that causes compile time or runtime errors, you can
244
266
use inline code blocks.
245
267
246
268
### Inline code blocks with language identifier
247
269
248
-
Use three backticks (\`\`\`) + a language ID to apply language-specific color coding to a code block. Here is the entire list of [GFM language IDs](https://github.com/jmm/gfm-lang-ids/wiki/GitHub-Flavored-Markdown-(GFM)-language-IDs).
270
+
Use three backticks (\`\`\`) + a language ID to apply language-specific color coding to a code block. Here's the entire list of [GFM language IDs](https://github.com/jmm/gfm-lang-ids/wiki/GitHub-Flavored-Markdown-(GFM)-language-IDs).
271
+
272
+
#### C++
273
+
274
+
```cpp
275
+
#include<iostream>
276
+
intmain()
277
+
{
278
+
std::cout << "Hello World!\n";
279
+
}
280
+
```
281
+
282
+
#### C
283
+
284
+
```C
285
+
#include<stdio.h>
286
+
intmain()
287
+
{
288
+
printf("Hello World!\n");
289
+
}
290
+
```
249
291
250
292
#### C\#
251
293
@@ -318,19 +360,21 @@ Use backticks (`) for `inline code`. Use inline code for command-line comman
318
360
319
361
## Videos
320
362
321
-
### Channel 9
363
+
### Shows
322
364
323
-
[
[
0 commit comments