Mixed Reality 개발자 설명서에 기여

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

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

이 페이지에서는 Markdown 기본 사항에 대한 링크 및 기여를 위한 기본 단계와 지침을 설명합니다. 기여해 주셔서 감사합니다.

사용 가능한 리포지토리

리포지토리 이름 URL
Azure Object Anchors MicrosoftDocs/azure-docs/articles/object-anchors
Azure Remote Rendering MicrosoftDocs/azure-docs/articles/remote-rendering
Azure Spatial Anchors MicrosoftDocs/azure-docs/articles/spatial-anchors
HoloLens MicrosoftDocs/HoloLens
Mixed Reality MicrosoftDocs/mixed-reality
VR Enthusiasts Guide MicrosoftDocs/mixed-reality/enthusiast-guide

시작하기 전에

아직 GitHub 계정이 없으면 GitHub 계정을 만들어야 합니다.

참고

Microsoft 직원인 경우 GitHub 계정을 Microsoft 오픈 소스 포털의 Microsoft 별칭에 연결하세요. "Microsoft""MicrosoftDocs" 조직에 가입하세요.

GitHub 계정을 설정할 때 다음과 같은 보안 예방 조치를 권장합니다.

게시 시스템이 GitHub와 연결되어 있으므로 이러한 단계가 중요합니다. GitHub 별칭을 사용하여 각 문서의 작성자 또는 기여자로 나열됩니다.

기존 문서 편집

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

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

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

    문서 편집.

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

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

    • title: 문서를 볼 때 브라우저 탭에 표시되는 페이지 제목입니다. 페이지 제목은 SEO 및 인덱싱에 사용되므로 필요한 경우가 아니면 제목을 변경하지 마십시오(단, 문서가 공개되기 전에는 덜 중요함).
    • description: SEO 및 검색 가능성을 높이는 문서 내용에 대한 간략한 설명을 작성합니다.
    • author: 페이지의 기본 소유자인 경우 여기에 GitHub 별칭을 추가합니다.
    • 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입니다. 리포지토리 경로가 아닌 공용 URL을 참조하므로 이 URL에 또는 .md가 포함되어 mixed-reality-docs있지 않은지 확인합니다. #section을 사용하여 새 문서 내의 섹션에 연결할 수 있습니다. 필요한 경우 여기에 다른 사이트에 대한 절대 경로를 사용할 수도 있습니다.
  • redirect_document_id는 이전 파일의 문서 ID를 유지할지 여부를 나타냅니다. 기본값은 false입니다. 리디렉션된 문서에서 ms.documentid 특성 값을 유지하려면 true를 사용합니다. 문서 ID를 유지하면 페이지 조회수, 순위 등의 데이터가 대상 문서로 이전됩니다. 리디렉션이 동일한 콘텐츠의 일부만 포함하는 다른 문서에 대한 포인터가 아니라 주로 이름 바꾸기인 경우 이 작업을 수행하세요.

리디렉션을 추가하면 이전 파일도 삭제해야 합니다.

새 문서 만들기

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

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

    포크 만들기.

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

  3. 문서의 페이지 이름을 만들고(공백 대신 하이픈을 사용하고 구두점이나 아포스트로피를 사용하지 않음) ".md"를 추가합니다.

    새 페이지의 이름을 지정합니다.

    중요

    "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'에 병합합니다(화살표가 올바른 방법을 가리키는지 확인).

    포크에서 MicrosoftDocs/mixed-reality로 끌어오기 요청 만들기

Markdown 기본 사항

다음 리소스는 Markdown 언어를 사용하여 문서를 편집하는 방법을 배우는 데 유용합니다.

테이블 추가

Microsoft 기술 설명서에서 테이블을 스타일 지정하는 방식 때문에 인라인 CSS를 사용해도 테두리 또는 사용자 지정 스타일이 없습니다. 짧은 시간 동안 작동하는 것처럼 보이지만 결국 플랫폼이 테이블에서 스타일을 제거합니다. 따라서 미리 계획하고 테이블을 단순하게 유지하세요. Markdown 테이블을 쉽게 만드는 사이트는 다음과 같습니다.

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

이미지 추가

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

중요

병합하기 전에 분기된 리포지토리에만 이미지를 업로드할 수 있습니다. 따라서 문서에 이미지를 추가하려는 경우 Visual Studio Code를 사용하여 먼저 포크의 "images" 폴더에 이미지를 추가하거나 웹 브라우저에서 다음을 수행했는지 확인해야 합니다.

  1. MicrosoftDocs/mixed-reality 리포지토리를 포크했습니다.
  2. 포크에서 문서를 편집했습니다.
  3. 문서에서 참조하는 이미지를 포크의 "mixed-reality-docs/images" 폴더에 업로드했습니다.
  4. 포크를 MicrosoftDocs/mixed-reality 'master' 분기에 병합하는 끌어오기 요청을 만들었습니다.

분기된 리포지토리를 설정하는 방법을 알아보려면 새 문서 생성 지침을 따르세요.

작업 미리 보기

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

참고

준비된 변경 내용을 미리 보는 것은 Microsoft 직원만 사용할 수 있습니다.

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를 사용하여 설명서를 변경합니다.

참고

위에서 언급한 Markdown 편집의 기본 사항 및 문서 편집생성에 대한 모든 지침은 Visual Studio Code를 사용할 때도 적용됩니다.

  1. 복제된 포크가 공식 리포지토리와 함께 최신인지 확인합니다.

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

      MicrosoftDocs/mixed-reality에서 포크로 변경 내용 동기화

    2. Visual Studio Code에서 동기화 단추를 선택하여 새로 업데이트된 포크를 로컬 클론에 동기화합니다.

      동기화 단추 이미지 클릭

  2. Visual Studio Code를 사용하여 복제된 리포지토리에서 문서를 만들거나 편집합니다.

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

    2. 탐색기에서 변경 사항을 저장합니다.

      탐색기에서

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

      소스 제어에서

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

      동기화 단추를 클릭합니다.

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

    포크에서 MicrosoftDocs/mixed-reality로 끌어오기 요청 만들기

유용한 확장

다음 Visual Studio Code 확장은 문서를 편집할 때 유용합니다.

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