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 and the rendered view (for instance, the raw Markdown shows the metadata block, while the rendered view doesn't).
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.
The full metadata block is yaml data between two lines that only contain ---
at the top of the document contents (in the raw Markdown). It's divided into required fields and optional fields. Some key notes:
- You must have a space between the colon (
:
) and the value for a metadata element. - 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#
. - 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"
). 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 thedocfx.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).author
,manager
,ms.author
: These values are optional and will default to per-directory settings in thedocfx.json
file. Set them only if the value is different from the default. Theauthor
field should contain the GitHub username of the author, not their alias. Themanager
andms.author
fields, on the other hand, should contain Microsoft aliases. We don't normally include thems.reviewer
value, but if present, it specifies the name of the PM/dev associated with the article or feature.ms.devlang
defines the technology. This value is optional and will default to per-directory settings in thedocfx.json
file. Set it only if the value is different from the default. Some of the supported values are:dotnet
,cpp
,csharp
,fsharp
,vb
andxml
.ms.assetid
: Don't set this value in new articles. It exists only as a historical link to archived versions of the document.
All basic and GitHub Flavored Markdown (GFM) is supported. For more information on Markdown, see:
Markdown uses special characters such as *, `, and # for formatting. If you wish to include one of these characters in your content, you must do one of two things:
- Put a backslash before the special character to "escape" it (for example,
\*
for a *) - Use the HTML entity code for the character (for example,
*
for a *). - 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.
You can use Visual Studio Code to edit Markdown documents. VS Code has many helpful Markdown extensions, such as:
- Docs Authoring Pack by Microsoft
- markdownlint
File names use the following rules:
- Contain only lowercase letters, numbers, and hyphens.
- No spaces or punctuation characters. Use hyphens to separate words and numbers in the file name.
- Use action verbs that are specific, such as "develop", "buy", "build", "troubleshoot". Don't use "-ing" words.
- No small words: Don't include "a", "and", "the", "in", "or", and so on.
- Must be in Markdown and use the
.md
file extension. - Keep file names reasonably short. They're part of the URL for your articles.
Use sentence-style capitalization. Always capitalize:
- The first word of a heading.
- The word following a colon in a title or heading (for example, "How to: Sort an array").
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.
There must be only one first-level heading (H1) in your article, which will be displayed as the on-page title.
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# #
.
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).
Second-level headings will generate the on-page TOC that appears in the "In this article" section underneath the on-page title.
### Third-level heading
#### Fourth-level heading
##### Fifth level heading
###### Sixth-level heading
Italics
*Italics*
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).
Bold
**Bold**
Use for UI elements.
Bold Code
**`Bold Code`**
Use for keywords, operators, and compiler and tool options.
Italic Code
*`Italic Code`*
Use for parameters.
Inline Code
`Inline Code`
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.
Blockquote
> Blockquote
Use blockquote for error and warning messages, syntax sections, and EBNF content.
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
).
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"
.
- Example: Chapter 1
To link to a Markdown file in the same repo, use relative links, including the ".md" at the end of the filename.
- Example: Readme file
- Example: Welcome to .NET
To link to a header in a Markdown file in the same repo, use relative linking + hashtag linking.
- Example: .NET Community
To link to a file in a different Docs repo, use the learn.microsoft.com
relative URL as the link. Don't include the .md suffix or the language/locale element.
To link to an external file, use the full URL as the link. Use HTTPS URL if applicable.
- Example: GitHub
If a URL appears in a Markdown file, it will be transformed into a clickable link.
- Example: https://www.github.com
The build system has some extensions that allow us to link to Managed APIs without having to use external links.
When linking to an API, you can use its unique identifier (UID) that is auto-generated from the source code.
You can use one of the following syntax forms:
- Markdown link:
[link_text](xref:UID)
- Auto link:
<xref:UID>
- Shorthand form:
@UID
- Example:
@System.String
- Example:
[String class](xref:System.String)
For more information about using this notation, see Using cross reference.
Right now, there is no easy way to find the UIDs. The best way to find the UID for an API is to search for it in this repository: docascode/coreapi. We're working on having a better system in the future.
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:
- Example:
@System.Threading.Tasks.Task\
1becomes
@System.Threading.Tasks.Task%601` - Example: @System.Exception.#ctor becomes
@System.Exception.%23ctor
Lists should be surrounded by blank lines.
- Example
- Of
- An
- Ordered
- List
- Here
- comes
- an
- embedded
- Scarlet
- Plum
- ordered
- list
- Example
- of
- a
- bulleted
- list
- Sometimes
- bulleted
- lists
- Chartreuse
- Lime
- contain
- other
- Magenta
- Fuchsia
- lists
Tables | Are | Cool |
---|---|---|
col 3 is | right-aligned | $1600 |
col 2 is | centered | $12 |
col 1 is default | left-aligned | $1 |
You can use a Markdown table generator tool to help creating them more easily. See also Markdown editing tools.
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.
The best way to include code is to include snippets from a working sample. Create your sample following the instructions in the contributing guide.
You can include the code using include syntax:
[!code-csharp[<title>](<pathToFile>#<RegionName)]
The example above shows C# syntax, but other languages are supported.
Use code-fsharp
for F# samples; use code-vbnet
for Visual Basic samples.
Other languages that are supported are:
- C++:
code-cpp
- HTML:
code-html
- JavaScript:
code-javascript
- PowerShell:
code-ps
- SQL:
code-sql
- XML:
code-xml
The text you place for <title>
shows up as a rollover on the text. The <pathToFile>
is the path to the source file. The <RegionName>
should be a region in your source
code that should be included. Use the #region
and #endregion
preprocessor syntax
to specify the region of code to include.
For cases where regions don't work, you can specify the start and end of a snippet using an XML element name in a single line comment. For example, you could write this sample region in C#:
// <CodeToInclude>
int j = 5;
int i ; 10;
int sum = i + j;
// </CodeToInclude>
In other languages, use the comment syntax for that language.
Finally, you can use line numbers: #L1-L10
would include lines 1 through 10. We discourage line numbers
because they're brittle.
Including snippets from full programs ensures that all code runs through our Continuous Integration (CI) system. However, if you need to show something that causes compile time or runtime errors, you can use inline code blocks.
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.
#include <iostream>
int main()
{
std::cout << "Hello World!\n";
}
#include <stdio.h>
int main()
{
printf("Hello World!\n");
}
using System;
namespace HelloWorld
{
class Hello
{
static void Main()
{
Console.WriteLine("Hello World!");
// Keep the console window open in debug mode.
Console.WriteLine("Press any key to exit.");
Console.ReadKey();
}
}
}
friends = ['john', 'pat', 'gary', 'michael']
for i, name in enumerate(friends):
print "iteration {iteration} is {name}".format(iteration=i, name=name)
Clear-Host
$Directory = "C:\Windows\"
$Files = Get-Childitem $Directory -recurse -Include *.log `
-ErrorAction SilentlyContinue
Use three backticks (```) for generic code block coding.
The recommended approach is to use code blocks with language identifiers as explained in the previous section to ensure the proper syntax highlighting in the documentation site. Use generic code blocks only when necessary.
function fancyAlert(arg) {
if(arg) {
$.docs({div:'#foo'})
}
}
Use backticks (`) for inline code
. Use inline code for command-line commands, database table and column names, and language expressions and function names.
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.
C++ A General Purpose Language and Library: (01) Getting Started.
On .NET 2/4/2016 - Scott Hunter.
docs.microsoft provides a few more extensions to GitHub Flavored Markdown.
It's important to use the following alert styles so they render with the proper style in the documentation site. However, the rendering engine on GitHub doesn't differentiate them.
Note
This is a NOTE
Warning
This is a WARNING
Tip
This is a TIP
Important
This is IMPORTANT
[!div class="button"] button links
You can see an example of buttons in action at the Intune docs.
[!div class="op_single_selector"]
You can see an example of selectors in action at the Intune docs.
You can see an example of step-by-steps in action at the Advanced Threat Analytics docs.