Mixed Reality 개발자 설명서에 기여

Mixed Reality 개발자 설명서에 대한 공개 리포지토리를 시작합니다. 이 리포지토리에서 만들거나 편집하는 모든 문서는 공개적으로 표시됩니다.

이제 Mixed Reality 문서는 Markdig 기능과 함께 GitHub 버전 Markdown을 사용하는 Microsoft Learn에서 호스트됩니다. 이 리포지토리에서 편집한 콘텐츠는 에 표시되는 /windows/mixed-reality스타일이 지정된 페이지로 서식이 지정됩니다.

이 문서는 자료를 공유하는 기본 절차와 MarkDown 기반의 링크를 안내합니다. 여러분의 공유에 감사드립니다!

사용 가능한 저장소

시작하기 전에

아직 계정이 없다면 GitHub 계정 생성 페이지에서 계정을 생성하세요.

GitHub 계정을 생성했으면 다음과 같은 보안 절차를 진행하시길 추천합니다.

• Github 계정에 대한 강력한 암호를 만듭니다.
• 2단계 인증을 사용하도록 설정합니다.
• 복구 코드를 안전한 장소에 저장합니다.
• 공개 프로필 설정을 업데이트합니다.
  • 이름을 설정하고 Public email을 Don't show my email address으로 설정하는 것이 좋습니다.
  • 여러분이 공유한 문서 페이지에 썸네일이 공개되므로 프로필 사진을 업데이트하길 추천합니다.
• 명령줄을 사용하려는 경우 Windows에 대해 Git 자격 증명 관리자를 설정하는 것이 좋습니다. 그러면 기여를 할 때마다 암호를 입력할 필요가 없습니다.

배포 시스템은 GitHub에 종속되기 때문에 중요한 절차들입니다. 여러분이 GitHub ID를 사용할 때 작성하는 게시물마다 저자 혹은 공유자로 등록될 것입니다.

기존 게시물 편집하기

다음 워크플로를 사용하여 웹 브라우저에서 GitHub를 통해 기존 문서를 업데이트합니다.

1. "mixed-reality-docs" 폴더에서 편집하려는 문서로 이동합니다.

2. 오른쪽 위에 있는 편집 단추(연필 아이콘)를 선택하면 '마스터' 분기에서 삭제 가능한 분기가 자동으로 분기됩니다.

   

3. "Markdown 기본 사항"에 따라 문서의 내용을 편집합니다.

4. 각 문서의 맨 위에 있는 메타데이터를 업데이트합니다.

   • title: 페이지 제목으로 게시물을 열람하면 브라우저 탭에 표시됩니다. 페이지 제목은 SEO와 검색에 사용되므로 필요한 경우가 아니라면 변경하지 않는 것이 좋습니다(공개되기 전에 변경하는 것이 좋습니다.).
   • description: SEO 및 발견이 쉽게 될 수 있도록 게시물 내용을 간단하게 설명합니다.
   • author: 여러분이 페이지의 최고 소유자라면 여기에 GitHub ID를 입력하세요.
   • ms.author: 여러분이 페이지의 최고 소유자라면 여기에 Microsoft 별칭(@microsoft.com이(가) 아닌 별칭)을 입력하세요.
   • ms.date: 페이지에 주요 콘텐츠를 추가한다면 날짜를 입력하세요. 해설, 형식 변경, 문법 및 맞춤법 수정 등의 작업에는 필요 없습니다.
   • keywords: SEO(검색 엔진 최적화) 용 키워드를 입력합니다. 내 문서와 관련된 키워드를 쉼표와 공백으로 구분하여 추가하되 목록의 마지막 키워드 뒤에는 문장 부호가 없어야 합니다. 모든 게시물에 적용되는 전역 키워드는 추가하지 않아도 좋습니다. 다른 곳에서 적용될 것입니다.

5. 문서 편집이 완료되면 아래로 스크롤하여 Propose file change(파일 변경 제안)을 선택합니다.

6. 다음 페이지에서 끌어오기 요청 만들기를 선택하여 자동으로 생성된 분기를 'master'에 병합합니다.

7. 다음 게시물을 편집하려면 위 내용을 반복하세요.

기존 게시물 제목 변경 및 삭제

만약 게시물의 제목을 변경하거나 게시물을 삭제한다면 반드시 재연결하세요. 그러면 존재하는 게시물의 링크를 가진 이용자라면 잘 찾아올 수 있을 것입니다. 재연결은 저장소 루트의 .openpublishing.redirection.json 파일에서 관리할 수 있습니다.

.openpublishing.redirection.json 파일에 재연결을 추가하려면 redirections 배열에 항목을 추가합니다.

{
    "redirections": [
        {
            "source_path": "mixed-reality-docs/old-article.md",
            "redirect_url": "new-article#section-about-old-topic",
            "redirect_document_id": false
        },
    ...
    ]
}

• source_path는 여러분이 삭제한 이전 게시물의 상대적인 저장소 경로입니다. 경로의 시작이 mixed-reality-docs이며 .md로 끝나는지 반드시 확인하세요.
• redirect_url은 이전 게시물에서 새 게시물로 연결되는 상대적인 공개 URL입니다. mixed-reality-docs 혹은 .md는 저장소 경로가 아니라 공개 URL을 의미하기 때문에 재연결 URL에는 포함되지 않아야 합니다. #section을 사용하여 새 문서 내의 섹션에 연결할 수 있습니다. 필요한 경우 여기에 다른 사이트에 대한 절대 경로를 사용할 수도 있습니다.
• redirect_document_id은(는) 기존 파일의 문서 ID를 저장하는지 여부를 나타냅니다. 기본값은 false입니다. 리디렉션된 문서에서 ms.documentid 특성 값을 유지하려면 true를 사용합니다. 문서 ID, 데이터, 조회수, 랭킹 등을 보존하면 대상 게시물로 전이됩니다. 같은 콘텐츠의 다른 게시물을 연결하는 용도가 아니라 게시물의 제목을 변경해서 재연결을 설정할 때 사용하세요.

재연결을 추가하면 이전 파일은 삭제해야 합니다.

새로운 게시물 생성

다음 워크플로를 사용하여 웹 브라우저에서 GitHub를 통해 설명서 리포지토리에 새 문서를 만듭니다.

1. MicrosoftDocs/mixed-reality 'master' 분기에서 포크를 만듭니다(오른쪽 위에 있는 포크 단추를 사용).

   

2. "mixed-reality-docs" 폴더의 오른쪽 위에서 새 파일 만들기를 선택합니다.

3. 게시물의 제목(공백 대신 하이픈을 사용하고 쉼표, 마침표, 따옴표는 사용 불가)을 정하고 끝에 '.md'를 붙입니다.

   

   Important

   "mixed-reality-docs" 폴더 내에서 새 문서를 만들어야 합니다. 새 파일 이름 줄에서 "/mixed-reality-docs/"를 확인하여 이를 확인할 수 있습니다.

4. 새 페이지 상단에 다음과 같은 메타데이터 블록을 추가하세요.

   ---
   title:
   description:
   author:
   ms.author:
   ms.date:
   ms.topic: article
   keywords:
   ---
   

5. 위 섹션의 지침에 따라 관련 메타데이터 필드를 입력합니다.

6. Markdown 기본 사항을 사용하여 문서 콘텐츠를 작성합니다.

7. 게시물 아래에 ## See also 섹션을 추가하고 관련된 게시물의 링크를 작성합니다.

8. 완료되면 Commit new file(새 파일 커밋)을 선택합니다.

9. 새 끌어오기 요청을 선택하고 포크의 'master' 분기를 MicrosoftDocs/mixed-reality 'master'에 병합합니다(화살표가 올바른 방법을 가리키는지 확인).

   

MarkDown 기본

다음 자료로 MarkDown 언어로 문서를 편집하는 방법을 알아보겠습니다.

• MarkDown 기본
• MarkDown 살펴보기 참고 포스터
• Microsoft Learn용 Markdown을 작성하기 위한 추가 리소스

표 추가하기

Microsoft 기술 문서 스타일 테이블의 방식 때문에 인라인 CSS를 사용해도 테두리 또는 사용자 지정 스타일이 없습니다. 시간을 조금 들이면 변경할 수 있지만 결국 플랫폼이 표에 추가한 형식을 제거할 것입니다. 그러니 나중을 생각해 표를 간단하게 작성하세요. Markdown 테이블을 쉽게 만드는 사이트는 다음과 같습니다.

Visual Studio Code용 Docs Markdown 확장에서도 Visual Studio Code(아래 참조)를 사용하여 문서를 편집하는 경우 테이블을 쉽게 생성할 수 있습니다.

이미지 추가하기

리포지토리의 "mixed-reality-docs/images" 폴더에 이미지를 업로드한 다음 문서에서 적절하게 참조해야 합니다. 이미지는 자동으로 전체 크기로 표시됩니다. 따라서 큰 이미지는 게시물의 가로를 가득 채울 수 있습니다. 따라서 업로드하기 전에 미리 크기를 조정하는 것이 좋습니다. 권장되는 너비는 600픽셀에서 700픽셀 사이이지만, 밀도가 높은 스크린샷이거나 스크린샷의 일부인 경우에는 크기를 늘리거나 줄여야 합니다.

작업 내용 미리보기

웹 브라우저를 통해 GitHub에서 편집하는 동안 페이지 위쪽의 미리 보기 탭을 선택하면 커밋하기 전에 작업을 미리 볼 수 있습니다.

Microsoft 직원: 기여가 'main' 분기에 병합되면 /windows/mixed-reality?branch=main에서 공개되기 전에 콘텐츠를 검토할 수 있습니다. 왼쪽 메뉴의 콘텐츠의 표에서 여러분의 게시물을 찾으세요.

브라우저에서 편집 및 데스크톱 클라이언트로 편집

웹 브라우저는 가장 간단하고 빠르게 편집을 할 수 있지만 단점도 있습니다.

• 맞춤법 검사를 할 수 없습니다.
• 다른 게시물과 스마트 링크를 쓸 수 없습니다(게시물의 파일 이름을 직접 입력해야 합니다.).
• 이미지를 업로드하고 첨부하는 방법이 복잡합니다.

이러한 문제를 겪지 않으려면 몇 가지 유용한 확장이 포함된 Visual Studio Code와 같은 데스크톱 클라이언트를 사용하여 기여하세요.

Visual Studio Code 사용하기

위에 나열된 이유 때문에 웹 브라우저 대신 데스크톱 클라이언트를 사용하여 문서를 편집하는 것을 선호할 수 있습니다. Visual Studio Code를 사용하는 것이 좋습니다.

설정

Visual Studio Code로 저장소에서 작업을 하려면 다음을 따라하세요.

1. 웹 브라우저에서:
   1. PC용 Git을 설치합니다.
   2. Visual Studio Code를 설치합니다.
   3. 아직 없는 경우 MicrosoftDocs/mixed-reality 를 포크합니다.
   4. 포크에서 복제 또는 다운로드를 선택하고 URL을 복사합니다.
2. Visual Studio Code에서 포크의 로컬 복제본을 만듭니다.
   1. 보기 메뉴에서 명령 팔레트를 선택합니다.
   2. 'Git: Clone'을 입력합니다.
   3. 복사한 URL을 붙여넣습니다.
   4. PC에 클론을 저장할 공간을 선택합니다.
   5. 팝업에서 리포지토리 열기를 선택합니다.

문서 편집하기

다음을 절차를 참고하여 Visual Studio Code에서 문서를 편집합니다.

1. 여러분의 클론 분류가 반드시 공식 저장소와 버전이 같아야 합니다.

   1. 웹 브라우저에서 끌어오기 요청을 만들어 MicrosoftDocs/mixed-reality 'master'의 다른 기여자에서 포크로 최근 변경 내용을 동기화합니다(화살표가 올바른 방법을 가리키는지 확인).

      

   2. Visual Studio Code에서 sync 버튼을 선택해 로컬 클론에 최신 업데이트된 분류를 동기화합니다.

      

2. Visual Studio Code로 클론 저장소에서 게시물을 작성하거나 편집합니다.

   1. 하나 이상의 문서를 편집합니다(필요한 경우 "images" 폴더에 이미지 추가).

   2. Explorer에서 변경 사항을 저장합니다.

      

   3. 소스 제어의 변경 내용을 모두 커밋합니다(메시지가 표시되면 커밋 메시지 작성).

      

   4. 동기화 단추를 선택하여 변경 내용을 원본으로 다시 동기화합니다(GitHub의 포크).

      

3. 웹 브라우저에서 포크의 새 변경 내용을 MicrosoftDocs/mixed-reality 'master'에 다시 동기화하는 끌어오기 요청을 만듭니다(화살표가 올바른 방법을 가리키는지 확인).

   

유용한 확장 프로그램

다음 Visual Studio Code 확장 프로그램은 문서를 편집할 때 유용하게 사용할 수 있습니다.

• Visual Studio Code용 Docs Markdown 확장 - Alt+M을 사용하여 다음과 같은 문서 작성 옵션 메뉴를 표시합니다.
  • 업로드한 이미지를 검색해서 첨부합니다.
  • 목록, 테이블과 같은 서식을 추가하고 >[!NOTE]와 같은 문서별 콜아웃을 추가합니다.
  • 인터넷 링크 및 즐겨찾기(페이지의 특정한 섹션을 지정하는 링크)를 검색해서 첨부합니다.
  • 오류를 강조 표시합니다(마우스 포인터를 오류 위로 올리면 자세한 사항을 볼 수 있습니다).
• 코드 맞춤법 검사기 - 철자가 틀린 단어에는 밑줄이 그어집니다. 철자가 틀린 단어를 마우스 오른쪽 단추로 클릭하면 변경하거나 사전에 저장할 수 있습니다.