Markdown 모범 사례

2025-04-29

이 문서에서는 설명서에서 Markdown을 사용하기 위한 구체적인 지침을 제공합니다. Markdown에 대한 자습서가 아닙니다. Markdown에 대한 자습서가 필요한 경우 이 Markdown 치트시트를 참조하세요.

설명서를 빌드하는 빌드 파이프라인은 markdig 를 사용하여 Markdown 문서를 처리합니다. Markdig는 최신 CommonMark 사양의 규칙에 따라 문서를 구문 분석합니다. OPS는 CommonMark 사양을 따르고 테이블 및 경고와 같은 플랫폼별 기능에 대한 일부 확장을 추가합니다.

CommonMark 사양은 일부 Markdown 요소의 생성에 대해 더 엄격합니다. 이 문서에 제공된 세부 정보에 주의하세요.

VS Code의 markdownlint 확장을 사용하여 스타일 및 서식 규칙을 적용합니다. 이 확장은 Learn Authoring Pack의 일부로 설치됩니다.

빈 줄, 공백 및 탭

또한 빈 줄은 Markdown에서 블록의 끝을 신호로 표시합니다.

다른 형식의 Markdown 블록 사이에 공백을 하나만 넣습니다. 예를 들어 단락과 목록 또는 머리글 사이에 있습니다.
빈 줄을 두 개 이상 사용하지 마세요. 여러 개의 빈 줄이 HTML에서 하나의 빈 줄로 렌더링되므로 빈 줄이 추가로 필요하지 않습니다.
여러 개의 연속된 빈 줄을 코드 블록에 배치하지 마세요. 연속된 빈 줄은 코드 블록을 중단합니다.

Markdown에서는 간격이 중요합니다.

줄 끝에 있는 추가 공백을 제거합니다. 후행 공백은 Markdown이 렌더링하는 방식을 변경할 수 있습니다.
항상 탭(하드 탭) 대신 공백을 사용합니다.

제목 및 소제목

ATX 머리글만 사용하고, # 스타일(= 또는 - 스타일과는 달리)을 사용하지 마세요.

문장 대/소문자 사용 - 적절한 명사만 사용하고 제목 또는 머리글의 첫 글자만 대문자로 표시해야 합니다.
제목의 첫 글자와 첫 글자 사이에 # 공백을 하나 포함합니다.
제목을 빈 줄로 묶습니다.
문서당 둘 이상의 H1을 사용하지 마세요.
- 첫 번째 헤더여야 합니다.
- 문서의 제목과 일치해야 합니다.
헤더 수준을 하나씩 증가 - 수준을 건너뛰지 마세요.
깊이를 H3 또는 H4로 제한
머리글에 굵게 또는 다른 태그를 사용하지 않도록 합니다.

줄 길이를 100자로 제한

개념 문서 및 cmdlet 참조의 경우 줄을 100자로 제한합니다. 아티클의 경우 about_ 줄 길이를 79자로 제한합니다. 선 길이를 제한하면 git의 차이점 및 기록의 가독성이 향상됩니다. 또한 다른 작가가 더 쉽게 기여할 수 있습니다.

VS Code의 Reflow Markdown 확장을 사용하여 지정된 줄 길이에 맞게 단락을 재배치합니다.

일부 콘텐츠 형식은 쉽게 재배치할 수 없습니다. 예를 들어 코드 블록 내의 코드는 콘텐츠 및 코드 언어에 따라 다시 흐름하기 어려울 수도 있습니다. 테이블을 재배치할 수 없습니다. 이러한 경우 최상의 판단을 사용하여 콘텐츠를 가능한 한 100자 제한에 가깝게 유지합니다.

강조

강조하기 위해 Markdown은 굵게와 기울기 기호를 지원합니다. Markdown을 사용하면 * 또는 _을 사용하여 강조할 수 있습니다. 그러나 일관성을 유지하고 의도를 표시하려면 다음을 수행합니다.

**를 사용하여 굵게 표시하세요.
이탤릭체에 _ 사용

이 패턴을 따르면 문서에 굵게와 기울기 기호가 혼합되어 있을 때 다른 사용자가 태그의 의도를 더 쉽게 이해할 수 있습니다.

목록에 문장이나 단락이 여러 개 있는 경우 목록 대신 구문 머리글을 사용하는 것이 좋습니다.

목록을 빈 줄로 묶습니다.

순서가 지정되지 않은 목록

여러 문장이 포함되지 않는 한 목록 항목을 마침표로 종료하지 마세요.
목록 항목 글머리 기호에 하이픈 문자()를 사용하여 별표(-*)를 사용하는 강조 태그와 혼동하지 않도록 합니다.
글머리 기호 항목 아래에 단락이나 다른 요소를 포함하려면 줄 바꿈을 삽입하고, 글머리 기호 다음 첫 번째 문자에 맞춰 들여쓰기를 조정하십시오.

다음은 그 예입니다.

This is a list that contains child elements under a bullet item.

- First bullet item

  Sentence explaining the first bullet.

  - Child bullet item

    Sentence explaining the child bullet.

- Second bullet item
- Third bullet item

글머리 기호 항목 아래에 자식 요소가 들어 있는 목록입니다.

첫 번째 항목

첫 번째 항목을 설명하는 문장입니다.
- 자식 글머리 기호 항목
  
  자식 글머리 기호를 설명하는 문장입니다.
두 번째 글머리 기호 항목
세 번째 글머리 기호 항목

순서가 지정된 목록

번호 매기기 목록의 모든 항목은 각 항목을 증가시키는 대신 숫자를 1. 사용해야 합니다.
- Markdown 렌더링은 값을 자동으로 증가합니다.
- 이렇게 하면 항목의 순서를 더 쉽게 지정하고 하위 콘텐츠의 들여쓰기를 표준화할 수 있습니다.
번호가 매겨진 항목 아래에 단락 또는 기타 요소를 포함하려면 번호 항목 뒤의 첫 번째 문자에 들여쓰기를 맞춥니다.

다음은 그 예입니다.

1. For the first element, insert a single space after the `1`. Long sentences should be wrapped to
   the next line and must line up with the first character after the numbered list marker.

   To include a second element, insert a line break after the first and align indentations. The
   indentation of the second element must line up with the first character after the numbered list
   marker.

1. The next numbered item starts here.

결과 Markdown은 다음과 같이 렌더링됩니다.

첫 번째 요소의 경우 뒤에 공백을 하나 삽입합니다 1. 긴 문장은 다음 줄로 래핑되어야 하며 번호가 매겨진 목록 표식 뒤의 첫 번째 문자와 줄 바꿈해야 합니다.

두 번째 요소를 포함하려면 첫 번째 요소 뒤에 줄 바꿈을 추가한 후 들여쓰기를 정렬합니다. 두 번째 요소의 들여쓰기를 번호 매기기 목록 표식 뒤의 첫 번째 문자와 일치해야 합니다.
다음 번호 매기기 항목은 여기에서 시작합니다.

이미지

이미지를 포함할 구문은 다음과 같습니다.

![[alt text]](<folderPath>)

Example:
![Introduction](./media/overview/Introduction.png)

alt text는 이미지에 대한 간략한 설명이고, <folderPath>는 이미지의 상대 경로입니다.

시각 장애인의 화면 읽기 프로그램을 지원하려면 대체 텍스트가 필요합니다.
이미지는 아티클이 media/<article-name> 포함된 폴더 내의 폴더에 저장해야 합니다.
- media 폴더 아래에 아티클의 파일 이름과 일치하는 폴더를 만듭니다. 해당 문서의 이미지를 새 폴더에 복사합니다.
문서 간에 이미지를 공유하지 마세요.
- 여러 아티클에서 이미지를 사용하는 경우 각 폴더에는 해당 이미지의 복사본이 있어야 합니다.
- 이렇게 하면 한 아티클의 이미지 변경이 다른 아티클에 영향을 주지 않습니다.

지원*.png되는 이미지 파일 형식은 다음과 *.gif*.jpeg*.jpg같습니다.*.svg

Markdown 확장 - 경고 상자

학습 제작 팩에는 게시 시스템에 고유한 기능을 지원하는 도구가 포함되어 있습니다. 경고는 콘텐츠의 중요성을 강조 표시하는 색 및 아이콘으로 렌더링되는 블록 인용을 만드는 Markdown 확장입니다. 지원되는 경고 유형은 다음과 같습니다.

> [!NOTE]
> Information the user should notice even if skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Essential information required for user success.

> [!CAUTION]
> Negative potential consequences of an action.

> [!WARNING]
> Dangerous certain consequences of an action.

이러한 경고는 Microsoft Learn에서 다음과 같습니다.

메모 블록

비고

스키밍하는 경우에도 사용자가 알 수 있는 정보입니다.

팁 블록

팁 (조언)

사용자가 더 성공하는 데 도움이 되는 선택적 정보입니다.

중요 블록

중요합니다

사용자 성공에 필요한 필수 정보입니다.

주의 블록

주의

작업의 부정적인 잠재적 결과입니다.

경고 블록

경고

행동의 위험한 특정 결과.

Markdown 확장 기능 - 테이블

테이블은 행과 열이 다음으로 구성된 데이터 정렬입니다.

단일 헤더 행
데이터에서 헤더를 분리하는 구분 기호 행
데이터 행이 없거나 더 많음

각 행은 파이프(|)로 구분된 임의의 텍스트를 포함하는 셀로 구성됩니다. 선도 및 후행 파이프도 명확성을 위해 권장됩니다. 파이프와 셀 내용 사이의 공백이 제거됩니다. 블록 수준 요소는 테이블에 삽입할 수 없습니다. 행의 모든 콘텐츠는 한 줄에 있어야 합니다.

구분 행은 하이픈(-)만 포함된 셀로 구성되며, 선택적으로 왼쪽, 오른쪽 또는 중앙 정렬을 나타내기 위해 앞이나 뒤에, 또는 양쪽에 콜론(:)이 붙을 수 있습니다.

작은 테이블의 경우 대신 목록을 사용하는 것이 좋습니다. 목록은 다음과 같습니다.

유지 관리 및 읽기가 더 쉽습니다.
100자 줄 제한 내에 맞게 재배치할 수 있습니다.
시각적 지원을 위해 화면 읽기 프로그램을 사용하는 사용자가 더 쉽게 액세스할 수 있음

자세한 내용은 Microsoft Learn에 대한 Markdown 참조의 테이블 섹션을 참조하세요.

하이퍼링크

하이퍼링크는 Markdown 구문을 [friendlyname](url-or-path)사용해야 합니다.
게시 시스템은 다음 세 가지 유형의 링크를 지원합니다.
- URL 링크
- 파일 링크
- 상호 참조 링크
대상 사이트에 유효하지 않은 경우 외부 웹 사이트에 대한 모든 URL은 HTTPS를 사용해야 합니다.
링크는 일반적으로 연결된 문서의 제목인 친숙한 이름이 있어야 합니다.
하이퍼링크의 대괄호 안에 백틱, 굵게 또는 기타 태그를 사용하는 것을 피하십시오.

특정 URI를 문서화할 때 베어 URL을 사용할 수 있지만 백틱으로 묶어야 합니다. 다음은 그 예입니다.

By default, if you don't specify this parameter, the DMTF standard resource URI
`http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/` is used and the class name is appended to it.

허용되는 경우 링크 참조를 사용합니다. 단락 내의 링크 참조를 사용하면 단락을 더 쉽게 읽을 수 있습니다.

링크 참조는 Markdown 링크를 다음 두 부분으로 나눕니다.
- 링크 참조 - [friendlyname][id]
- 링크 정의 - [id]: url-or-path

URL 형식 링크

다른 문서에 대한 URL 링크는 learn.microsoft.com 사이트 상대 경로를 사용해야 합니다. 사이트 상대 링크를 만드는 가장 간단한 방법은 브라우저에서 URL을 복사한 다음 markdown에 붙여넣은 값에서 제거하는 https://learn.microsoft.com/en-us 것입니다.
Microsoft 속성의 URL이나 Wikipedia 링크에 로캘을 포함하지 말고, /en-us를 URL에서 제거하세요.
URL에서 불필요한 쿼리 매개 변수를 제거합니다. 제거해야 하는 예:
- ?view=powershell-5.1 - 특정 버전의 PowerShell에 연결하는 데 사용됨
- ?redirectedfrom=MSDN - 이전 아티클에서 새 위치로 리디렉션될 때 URL에 추가됨
특정 버전의 문서에 연결해야 하는 경우 쿼리 문자열에 &preserve-view=true 매개 변수를 추가해야 합니다. 예: ?view=powershell-5.1&preserve-view=true
Microsoft 사이트에서 URL 링크에는 파일 확장명(예: 아니요 .md)이 포함되지 않습니다.

파일 형식 링크

파일 링크는 한 참조 아티클에서 다른 문서로 연결하거나, 한 개념적 문서에서 동일한 문서 세트의 다른 문서로 연결하는 데 사용됩니다.
- 개념 문서에서 참조 문서로 연결해야 하는 경우 URL 링크를 사용해야 합니다.
- 다른 문서 세트 또는 리포지토리의 문서에 연결해야 하는 경우 URL 링크를 사용해야 합니다.
상대 파일 경로 사용(예: ../folder/file.md)
모든 파일 경로는 슬래시(/) 문자를 사용합니다.
파일 확장명 포함(예: .md)

상호 참조 링크

상호 참조 링크는 게시 시스템에서 지원하는 특별한 기능입니다. 개념 문서에서 상호 참조 링크를 사용하여 .NET API 또는 cmdlet 참조에 연결할 수 있습니다.

.NET API 참조에 대한 링크는 중앙 기여자 가이드 의 설명서에서 링크 사용을 참조하세요.
cmdlet 참조에 대한 링크 형식은 다음과 같습니다 xref:<module-name>.<cmdlet-name>. 예를 들어 Get-ContentMicrosoft.PowerShell.Management 모듈의 cmdlet에 연결하려면.

[Get-Content](xref:Microsoft.PowerShell.Management.Get-Content)

딥 링크

URL 및 파일 링크 모두에서 딥 링크가 허용됩니다.

앵커 텍스트는 소문자여야 합니다.
대상 경로의 끝에 앵커를 추가합니다. 예를 들어:
- [about_Splatting](about_Splatting.md#splatting-with-arrays)
- [custom key bindings](https://code.visualstudio.com/docs/getstarted/keybindings#_custom-keybindings-for-refactorings)

자세한 내용은 설명서의 링크 사용을 참조하세요.

코드 범위

코드 범위는 단락 내의 인라인 코드 조각에 사용됩니다. 단일 백틱(역따옴표)을 사용하여 코드 범위를 나타냅니다. 다음은 그 예입니다.

PowerShell cmdlet names use the `Verb-Noun` naming convention.

이 예제에서는 다음과 같이 렌더링합니다.

PowerShell cmdlet 이름은 명명 규칙을 사용합니다 Verb-Noun .

코드 블록

코드 블록은 명령 예제, 여러 줄 코드 샘플, 쿼리 언어 및 출력에 사용됩니다. 아티클 파일의 텍스트 섹션을 코드 블록으로 나타내는 두 가지 방법이 있습니다. 즉, 삼중 백틱(```)으로 펜싱하거나 들여쓰기합니다.

절대 들여쓰기를 사용하지 마세요. 다른 작성자가 귀하의 기사를 편집해야 할 때 의도를 이해하기 어려울 수 있습니다.

펜스 코드 블록은 블록에 포함된 언어 구문을 나타내는 선택적 태그를 포함할 수 있습니다. 게시 플랫폼은 언어 태그 목록을 지원합니다. 언어 태그는 문서가 웹 페이지에서 렌더링될 때 구문 강조 표시를 제공하는 데 사용됩니다. 언어 태그는 대/소문자를 구분하지 않지만 몇 가지 특수한 경우를 제외하고 소문자를 사용해야 합니다.

태그가 없는 코드 펜스는 구문 블록 또는 구문 강조 표시가 필요하지 않은 다른 형식의 콘텐츠에 사용할 수 있습니다.
명령의 출력을 표시할 때 언어 태그 Output와 함께 태그가 지정된 코드 펜스를 사용합니다. 렌더링된 상자는 출력 으로 레이블이 지정되며 구문 강조 표시가 없습니다.
출력이 지원되는 특정 언어에 있는 경우 적절한 언어 태그를 사용합니다. 예를 들어 많은 명령이 JSON을 출력하므로 태그를 json 사용합니다.
지원되지 않는 언어 태그를 사용하는 경우 코드 블록은 구문 강조 표시 없이 렌더링됩니다. 언어 태그는 웹 페이지에서 렌더링된 코드 상자의 레이블이 됩니다. 레이블이 웹 페이지에서 대문자로 표시되도록 태그를 대문자로 표시합니다.

다음 단계

PowerShell 스타일 가이드