다음을 통해 공유

.NET 문서에 대한 메타데이터 및 Markdown 템플릿

이 dotnet/docs 템플릿에는 Markdown 구문의 예와 메타데이터 설정에 대한 지침이 포함되어 있습니다.

Markdown 파일을 만들 때 포함된 템플릿을 새 파일에 복사하고, 아래에 지정된 대로 메타데이터를 입력하고, 위의 H1 제목을 아티클 제목으로 설정합니다.

메타데이터

필요한 메타데이터 블록은 다음 샘플 메타데이터 블록에 있습니다.

---
title: [ARTICLE TITLE]
description: [usually a summary of your first paragraph. It gets displayed in search results, and can help drive the correct traffic if well written.]
author: [GITHUB USERNAME]
ms.date: [CREATION/UPDATE DATE - mm/dd/yyyy]
---
# The H1 should not be the same as the title, but should describe the article contents
  • 콜론(:)과 메타데이터 요소의 값 사이에 공백이 있어야 합니다 .
  • 값에 있는 콜론(예: 제목)이 메타데이터 파서를 중단시킵니다. 이 경우 제목을 큰따옴표(예: title: "Writing .NET Core console apps: An advanced step-by-step guide")로 묶습니다.
  • title: 검색 엔진 결과에 나타납니다. 제목은 H1 제목의 제목과 동일하지 않아야 하며 60자 이하를 포함해야 합니다.
  • description: 문서의 내용을 요약합니다. 일반적으로 검색 결과 페이지에 표시되지만 검색 순위에는 사용되지 않습니다. 길이는 공백을 포함하여 115-145자여야 합니다.
  • 작성자: 작성자 필드에는 작성자의 GitHub 사용자 이름이 포함되어야 합니다.
  • ms.date: 마지막 중요 업데이트 날짜입니다. 전체 문서를 검토하고 업데이트한 경우 기존 아티클에서 이를 업데이트합니다. 오타 또는 이와 유사한 작은 수정은 업데이트를 보증하지 않습니다.

다른 메타데이터는 각 아티클에 첨부되지만 일반적으로docfx.json지정된 폴더 수준에서 대부분의 메타데이터 값을 적용 합니다.

기본 Markdown, GFM 및 특수 문자

Markdown 참조 문서에서 Markdown, GitHub GFM(Flavored Markdown) 및 OPS 관련 확장의 기본 사항을 알아볼 수 있습니다.

Markdown은 서식 지정에 *, '및 #과 같은 특수 문자를 사용합니다. 콘텐츠에 이러한 문자 중 하나를 포함하려면 다음 두 가지 중 하나를 수행해야 합니다.

  • 특수 문자 앞에 백슬래시를 넣어 "이스케이프"합니다(예: \*는 *를 위해 사용합니다).
  • 문자에 HTML 엔터티 코드를 사용합니다(예 * : *).

파일 이름

파일 이름은 다음 규칙을 사용합니다.

  • 소문자, 숫자 및 하이픈만 포함합니다.
  • 공백이나 문장 부호 문자가 없습니다. 하이픈을 사용하여 파일 이름에 단어와 숫자를 구분합니다.
  • 개발, 구매, 빌드, 문제 해결과 같은 특정 작업 동사를 사용합니다. ~ing 형태의 단어가 없습니다.
  • 작은 단어 사용 금지 - a, 및, the, in, or 등을 포함하지 마세요.
  • Markdown에 있어야 하며 .md 파일 확장자를 사용해야 합니다.
  • 파일 이름을 비교적 짧게 유지합니다. 아티클에 대한 URL의 일부입니다.

제목

문장 스타일의 대문자 사용을 지키세요. 항상 제목의 첫 번째 단어를 대문자로 표시합니다.

텍스트 스타일 지정

Italics
파일, 폴더, 경로(긴 항목의 경우 별도의 줄로 분할) 및 새로운 용어에 사용하십시오.

굵게
UI 요소에 사용합니다.

Code
인라인 코드, 언어 키워드, NuGet 패키지 이름, 명령줄 명령, 데이터베이스 테이블 및 열 이름, 클릭할 수 없는 URL에 사용합니다.

앵커, 내부 링크, 다른 문서에 대한 링크, 코드 포함 및 외부 링크에 대한 자세한 내용은 링크 의 일반 문서를 참조하세요.

.NET 문서 팀은 다음 규칙을 사용합니다.

  • 대부분의 경우 우리는 상대 링크를 사용하고, 상대 링크가 GitHub에서 해결되기 때문에 링크에서 ~/의 사용을 지양합니다. 그러나 종속 리포지토리의 파일에 연결할 때마다 해당 문자를 사용하여 ~/ 경로를 제공합니다. 종속 리포지토리의 파일이 GitHub의 다른 위치에 있으므로 링크가 작성된 방법에 관계없이 상대 링크로 올바르게 확인되지 않습니다.
  • C# 언어 사양 및 Visual Basic 언어 사양은 언어 리포지토리의 원본을 포함하여 .NET 문서에 포함됩니다. markdown 원본은 csharplang 및 vblang 리포지토리에서 관리됩니다.

사양에 대한 링크는 해당 사양이 포함된 원본 디렉터리를 가리킵니다. C#의 경우 다음 예제와 같이 ~/_csharplang/spec 이며 VB의 경우 ~/_vblang/spec입니다.

[C# Query Expressions](~/_csharplang/spec/expressions.md#query-expressions)

빌드 시스템에는 외부 링크를 사용하지 않고도 .NET API에 연결할 수 있는 몇 가지 확장이 있습니다. 다음 구문 중 하나를 사용합니다.

  1. 자동 링크: <xref:UID> 또는 <xref:UID?displayProperty=nameWithType>

    쿼리 매개 변수는 displayProperty 정규화된 링크 텍스트를 생성합니다. 기본적으로 링크 텍스트는 멤버 또는 형식 이름만 표시합니다.

  2. Markdown 링크: [link text](xref:UID)

    표시되는 링크 텍스트를 사용자 지정하려는 경우에 사용합니다.

예제:

  • <xref:System.String>는 문자열로 렌더링됩니다.
  • <xref:System.String?displayProperty=nameWithType> System.String으로 렌더링
  • [String class](xref:System.String) string 클래스로 렌더링

이 표기법을 사용하는 방법에 대한 자세한 내용은 상호 참조 사용을 참조하세요.

일부 UID에는 특수 문자 ', # 또는 *가 포함되어 있으며 UID 값은 각각 HTML로 %60%23%2A 인코딩되어야 합니다. 괄호가 인코딩되는 경우도 있지만 요구 사항은 아닙니다.

예제:

  • System.Threading.Tasks.Task'1이 됩니다. System.Threading.Tasks.Task%601
  • System.Exception.#ctor가 System.Exception.%23ctor로 변환됩니다.
  • System.Lazy'1.#ctor(System.Threading.LazyThreadSafetyMode)가 됩니다. System.Lazy%601.%23ctor%28System.Threading.LazyThreadSafetyMode%29

UID 다음에 *(또는 %2A)를 추가하는 경우 링크는 특정 API가 아닌 오버로드 페이지를 나타냅니다. 예를 들어, List<T>.BinarySearch 메서드 페이지에 제네릭하게 연결하려는 경우, List<T>.BinarySearch(T, IComparer<T>)와 같은 특정 오버로드 대신 이를 사용할 수 있습니다. 멤버가 오버로드되지 않은 경우 *를 사용하여 멤버 페이지에 연결할 수도 있습니다. 이렇게 하면 UID에 매개 변수 목록을 포함할 필요가 없습니다.

특정 메서드 오버로드에 연결하려면 각 메서드 매개 변수의 정규화된 형식 이름을 포함해야 합니다. 예를 들어 <xref:System.DateTime.ToString>은 매개 변수가 없는 DateTime.ToString 메서드에 연결하고 <xref:System.DateTime.ToString(System.String,System.IFormatProvider)은 > 메서드에 연결됩니다.

System.Collections.Generic.List<T>와 같은 제네릭 형식에 연결하려면 '(%60) 문자 뒤에 제네릭 형식 매개 변수 수를 사용합니다. 예를 들어, <xref:System.Nullable%601>는 System.Nullable<T> 형식에 대한 링크를 생성하고, <xref:System.Func%602>는 System.Func<T,TResult> 대리자에 대한 링크를 생성합니다.

코드

코드를 포함하는 가장 좋은 방법은 작업 샘플의 코드 조각을 포함하는 것입니다. .NET에 기여하는 문서의 지침에 따라 샘플을 만듭니다. 전체 프로그램의 코드 조각을 포함하면 모든 코드가 CI(연속 통합) 시스템을 통해 실행됩니다. 그러나 컴파일 시간 또는 런타임 오류를 발생시키는 항목을 표시해야 하는 경우 인라인 코드 블록을 사용할 수 있습니다.

문서에 코드를 표시하기 위한 Markdown 구문에 대한 자세한 내용은 문서에 코드를 포함하는 방법을 참조하세요.

이미지

정적 이미지 또는 애니메이션 GIF

![this is the alt text](../images/Logo_DotNet.png)

연결된 이미지

[![alt text for linked image](../images/Logo_DotNet.png)](https://dot.net)

Videos

Markdown 파일에 YouTube 비디오를 포함할 수 있습니다. 비디오의 올바른 URL을 얻으려면 비디오를 마우스 오른쪽 단추로 클릭하고 Embed Code 복사를 선택한 다음 요소에서 URL을 복사합니다 <iframe> .

> [!VIDEO <youtube_video_link>]

다음은 그 예입니다.

> [!VIDEO https://www.youtube.com/embed/Q2mMbjw6cLA]

learn.microsoft 확장

learn.microsoft는 GitHub Flavored Markdown에 대한 몇 가지 추가 확장을 제공합니다.

확인된 목록

사용자 지정 스타일은 목록에 사용할 수 있습니다. 녹색 확인 표시를 사용하여 목록을 렌더링할 수 있습니다.

> [!div class="checklist"]
>
> - How to create a .NET Core app
> - How to add a reference to the Microsoft.XmlSerializer.Generator package
> - How to edit your MyApp.csproj to add dependencies
> - How to add a class and an XmlSerializer
> - How to build and run the application

다음과 같이 렌더링됩니다.

  • .NET Core 앱을 만드는 방법
  • Microsoft.XmlSerializer.Generator 패키지에 대한 참조를 추가하는 방법
  • MyApp.csproj를 편집하여 종속성을 추가하는 방법
  • 클래스 및 XmlSerializer를 추가하는 방법
  • 애플리케이션을 빌드하고 실행하는 방법

.NET Core 문서에서 작동 중인 확인된 목록의 예를 볼 수 있습니다.

Buttons

버튼 링크:

> [!div class="button"]
> [button links](dotnet-contribute.md)

다음과 같이 렌더링됩니다.

단추 링크

Visual Studio 문서에서 작동 중인 단추의 예를 볼 수 있습니다.

단계별

>[!div class="step-by-step"]
> [Pre](../docs/csharp/expression-trees-interpreting.md)
> [Next](../docs/csharp/expression-trees-translating.md)

C# 가이드에서 작동하는 단계별 예제를 볼 수 있습니다.

  • Last updated on