NTFSSecurity/Docs/Contributing/04-Markdown-Specifics.md

Markdown and platyPS specifics

This page lists the Markdown rules for the NTFSSecurity documentation and the additional rules for the cmdlet reference pages, which platyPS processes.

Markdown

• Use ATX headings (#), one level 1 heading per page, and don't skip heading levels.
• Use - for bulleted lists and 1. for numbered lists.
• Surround headings, lists, tables, and code blocks with blank lines.
• Give every fenced code block a language, for example powershell.
• Don't use hard tabs or trailing spaces.
• Link to other pages with relative links to the .md file, for example [Concepts](Concepts.md) or [Get-NTFSAccess](Cmdlets/Get-NTFSAccess.md). GitHub renders them as links to the pages.
• Link to a section with the anchor that GitHub generates from its heading: lowercase, with spaces replaced by hyphens and punctuation removed, for example [Privileges](Concepts.md#privileges).
• End every file with a single newline.

Cmdlet reference pages

platyPS converts the pages in Docs/Cmdlets to the help file that Get-Help shows and updates the pages from the module. Keep the structure that platyPS expects:

• Keep the front matter. external help file, Module Name, and schema must stay as they are. online version is the address of the page on GitHub, which Get-Help -Online opens.
• Keep the level 2 headings in capital letters and in this order: SYNOPSIS, SYNTAX, DESCRIPTION, EXAMPLES, PARAMETERS, INPUTS, OUTPUTS, NOTES, RELATED LINKS. Don't add other level 2 headings.
• Don't edit the SYNTAX blocks or the YAML block of a parameter by hand. platyPS regenerates them from the module. The only exception is Default value, which platyPS keeps.
• Write each paragraph on a single line. platyPS carries line breaks into the text that Get-Help shows.
• Put a link at the end of a sentence. In the text that Get-Help shows, platyPS writes a link as text (address) and drops the space after it.
• Start each example with a level 3 heading such as ### Example 1: Get the permissions of a folder, followed by a code block with the language PowerShell whose first line starts with PS C:\>.
• Under INPUTS and OUTPUTS, keep the level 3 headings with the type names and add a sentence below each one.
• In RELATED LINKS, write each link on its own line and separate the links with blank lines.