텍스트 서식 지정 지침

아티클
08/10/2023

텍스트 요소에 대해 굵게, 기울임꼴 및 코드 스타일을 일관되고 적절하게 사용하면 가독성이 향상되고 잘못 이해하지 않도록 방지할 수 있습니다.

굵게

메뉴 선택, 대화 상자 이름 및 입력 필드 이름과 같은 UI 요소에 굵게를 사용합니다.

예제

적용됨: 솔루션 탐색기에서 프로젝트 노드를 마우스 오른쪽 단추로 클릭하고 추가 > 새 항목을 차례로 선택합니다.
적용되지 않음: 솔루션 탐색기에서 프로젝트 노드를 마우스 오른쪽 단추로 클릭하고 추가 > 새 항목을 차례로 선택합니다.
적용되지 않음: 솔루션 탐색기에서 프로젝트 노드를 마우스 오른쪽 단추로 클릭하고 추가> 새 항목을 차례로 선택합니다.

기울임꼴

기울임꼴을 사용하는 항목은 다음과 같습니다.

정의 또는 설명과 함께 소개하는 새 용어
파일 이름, 폴더 이름, 경로
사용자 입력

예제

적용됨: App Service에서는 앱이 ‘App Service 계획’에서 실행됩니다. App Service 계획은 웹앱이 실행될 컴퓨팅 리소스 집합을 정의합니다.
적용되지 않음: App Service에서 앱은 “App Service 요금제”로 실행됩니다. App Service 요금제는 실행할 웹앱의 컴퓨팅 리소스 집합을 정의합니다.
적용됨: HttpTriggerCSharp.cs의 코드를 다음 코드로 바꿉니다.
적용되지 않음: HttpTriggerCSharp.cs의 코드를 다음 코드로 바꿉니다.
적용됨: 이름에 ContosoUniversity를 입력하고 추가를 선택합니다.
적용되지 않음: 이름에 “ContosoUniversity”를 입력하고 추가를 선택합니다.

코드 스타일

코드 스타일을 사용하는 항목은 다음과 같습니다.

메서드 이름, 속성 이름 및 언어 키워드와 같은 코드 요소
SQL 명령
NuGet 패키지 이름
명령줄 명령*
데이터베이스 테이블 및 열 이름
지역화되지 않아야 하는 리소스 이름(예: 가상 머신 이름)
클릭할 수 없게 하려는 URL

그 이유는 이전 스타일 가이드에서는 이러한 텍스트 요소 중 다수에 대해 굵게를 지정합니다. 하지만 대부분의 문서는 지역화되며, 코드 스타일은 텍스트의 해당 부분을 번역하지 않도록 번역기에 지시합니다.

코드 스타일은 여러 줄로 되어 있는 인라인 코드 블록(`로 묶임)이거나 펜싱된 코드 블록(```로 묶임)일 수 있습니다. 긴 코드 조각과 경로는 펜스를 친 코드 블록에 넣습니다.

* 명령줄 명령 내에 모든 플랫폼에서 지원되는 경우 파일 경로에 전달 슬래시를 사용합니다. 백슬래시만 지원되는 경우 Windows에 실행되는 명령을 보여 주려면 백슬래시를 사용합니다. 예를 들어 전달 슬래시는 모든 플랫폼의 .NET CLI에서 작동하므로 dotnet build foldername\filename.csproj 대신 dotnet build foldername/filename.csproj을 사용합니다.

인라인 스타일을 사용하는 예제

적용됨: 기본적으로 Entity Framework에서 Id 또는 ClassnameID라는 속성을 기본 키로 해석합니다.
적용되지 않음: 기본적으로 Entity Framework에서 Id 또는 ClassnameID라는 속성을 기본 키로 해석합니다.
적용됨: Microsoft.EntityFrameworkCore 패키지는 EF Core에 대한 런타임 지원을 제공합니다.
적용되지 않음: Microsoft.EntityFrameworkCore 패키지는 EF Core에 대한 런타임 지원을 제공합니다.

펜스를 친 코드 블록의 예

적용됨: 다음 코드와 같이 IQueryable만 변경하는 명령문으로는 어떤 명령도 데이터베이스로 보낼 수 없습니다.
```
    ```csharp
    var students = context.Students.Where(s => s.LastName == "Davolio")
    ```
```
적용되지 않음: var students = context.Students.Where(s => s.LastName == "Davolio")와 같이 IQueryable만 변경하는 명령문으로는 어떤 명령도 데이터베이스로 보낼 수 없습니다.
적용됨: 예를 들어 C:\Scripts 디렉터리에서 Get-ServiceLog.ps1 스크립트를 실행하려면 다음과 같이 입력합니다.
```
    ```powershell
    C:\Scripts\Get-ServiceLog.ps1
    ```
```
적용되지 않음: 예를 들어 C:\Scripts 디렉터리에서 Get-ServiceLog.ps1 스크립트를 실행하려면 “C:\Scripts\Get-ServiceLog.ps1”을 입력합니다.
펜싱된 코드 블록 모두에 승인된 언어 태그가 있어야 합니다. 지원 언어 태그 목록은 문서에 코드를 포함하는 방법을 참조하세요.

자리 표시자

사용자가 입력 문자열의 일부를 고유한 값으로 바꾸도록 하려면 꺾쇠 괄호(보다 작음 < 및 보다 큼 > 문자)로 표시된 자리 표시자 텍스트를 사용합니다.

옵션 1: 코드 스타일 지정을 사용하여 자리 표시자 단어나 포함하는 구를 둘러쌉니다. 예를 들어 단일 구의 인라인 코드 서식 지정에 단일 백틱(`)을 사용하거나 코드 펜싱된 서식 지정에 백틱 세 개(```)를 사용할 수 있습니다.

`az group delete -n <ResourceGroupName>`

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

az group delete -n <ResourceGroupName>

또는

옵션 2:\< 및 \>처럼 백슬래시 문자 \를 사용하여 Markdown에서 꺾쇠 괄호 문자를 이스케이프합니다. 왼쪽 꺾쇠 괄호의 첫 번째 이스케이프 \<만 필요하지만, 일관성을 위해 닫는 괄호 이스케이프 \>도 사용합니다. 렌더링된 HTML은 독자에게 이스케이프 문자를 표시하지 않습니다.

az group delete -n \<ResourceGroupName\>

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

az group delete -n <ResourceGroupName>

독자에게 자리 표시자에 대한 정보 제공: 자리 표시자 예제처럼 이전 텍스트에서는 독자에게 괄호 안의 텍스트를 제거하고 실제 값으로 대체해야 함을 설명합니다. 사용자 입력에는 기울일꼴을 사용하는 것이 좋습니다. 꺾쇠 괄호 인라인 코드 내에 기울임꼴 서식을 지정할 수 있습니다.

다음 예제에서 <ResourceGroupName> 텍스트를 고유한 리소스 그룹 이름으로 바꿉니다.

주의

Microsoft Learn 사이트는 대괄호가 제대로 이스케이프되지 않거나 텍스트가 코드 형식이 아닌 경우 꺾쇠 괄호를 사용하는 자리 표시자> 텍스트를 렌더링<하지 않습니다. Microsoft Learn 빌드 프로세스는 자리 표시자 구를 판독기> 브라우저에 위험할 수 있는 HTML 태그로 해석<하고 허용되지 않는 html 태그로 플래그를 지정합니다. 빌드 보고서에 제안이 표시되고 자리 표시자 단어가 Microsoft Learn 페이지 출력에 렌더링되지 않습니다.

자리 표시자에 있는 콘텐츠의 손실을 방지하려면 앞에서 설명한 것처럼 code 서식 지정이나 이스케이프 문자(\<\>)를 사용하세요.

중괄호 { }는 구문 자리 표시자로 사용하지 않는 것이 좋습니다. 독자가 다음에 사용된 동일한 표기법과 중괄호 자리 표시자를 혼동할 수 있습니다.

대체 가능한 텍스트
형식 문자열
문자열 보간
텍스트 템플릿
유사한 프로그래밍 구문

대/소문자 표기 및 간격: 하이픈(“kebab case”) 또는 밑줄을 사용하여 자리 표시자 이름을 구분하거나 파스칼식 대/소문자를 사용하여 자리 표시자 이름을 구분할 수 있습니다. Kebab case는 구문 오류를 생성할 수 있으며, 밑줄은 밑줄 표시(underlining)와 충돌할 수 있습니다. 모두 대문자는 자리 표시자 이름에 주의를 끌 수도 있지만 여러 언어에서 명명된 상수와 충돌할 수 있습니다.

<Resource-Group-Name> 또는 <ResourceGroupName>

제목 및 링크 텍스트

제목이나 하이퍼링크 텍스트에는 기울임꼴, 굵은 글꼴과 같은 인라인 스타일을 적용하지 않습니다.

적용 근거

사용자는 표준 하이퍼링크 텍스트를 사용하여 텍스트 요소를 클릭 가능한 링크로 식별합니다. 예를 들어 링크를 기울임꼴로 스타일 지정하면 텍스트가 링크임을 이해하기 어렵게 만들 수 있습니다. 제목에는 자체의 스타일이 있으며, 다른 스타일과 혼합되면 보기에 좋지 않습니다.

제목 및 링크 텍스트의 예

적용됨: function.json 파일이 Microsoft.NET.Sdk.Functions NuGet 패키지에서 생성됩니다.
적용되지 않음: function.json 파일이 Microsoft.NET.Sdk.Functions NuGet 패키지에서 생성됩니다.

적용됨:

### The Microsoft.NET.Sdk.Functions package

적용되지 않음:

### The *Microsoft.NET.Sdk.Functions* package

키 및 바로 가기 키

키 또는 키 조합을 나타내는 경우 다음 규칙을 따릅니다.

키 이름의 첫 글자는 대문자로 표시합니다.
키 이름을 <kbd> 및 </kbd> HTML 태그로 묶습니다.
사용자가 동시에 선택하는 키를 조인하려면 "+"를 사용합니다.

키 및 바로 가기 키 예시

적용됨: Alt+Ctrl+S를 선택합니다.
적용되지 않음: Alt+Ctrl+S를 누릅니다.
적용되지 않음: ALT+CTRL+S를 누릅니다.

예외

스타일 지침은 엄격한 규칙이 아닙니다. 지침을 따르면 가독성이 손상되는 컨텍스트에서는 다른 방식으로 작업을 수행하세요. 예를 들어 대부분 코드 요소로 채워진 HTML 테이블에는 어디서나 코드 스타일이 아주 많이 적용될 수 있습니다. 해당 컨텍스트에서는 굵게 스타일 지정을 선택할 수 있습니다.

일반적으로 코드가 호출되는 다른 텍스트 스타일을 선택하는 경우 문서의 지역화된 버전으로 텍스트를 번역할 수 있는지 확인합니다. 코드는 번역을 자동으로 방지하는 유일한 스타일입니다. 코드 스타일을 사용하지 않고도 지역화를 방지하려는 시나리오의 경우 지역화되지 않은 문자열을 참조하세요.