HoloLens ドキュメントへの投稿

2024-06-27

HoloLens ドキュメントへようこそ。このリポジトリで作成または編集した記事 は、一般に公開されます。

HoloLens ドキュメントは、GitHub フレーバーの Markdown と Markdig 機能を使用する Microsoft Learn に公開されています。このリポジトリで編集したコンテンツは、/hololensに表示されるスタイル設定されたページに書式設定されます。

このページでは、投稿の基本的な手順とガイドライン、および Markdown の基本へのリンクについて説明します。あなたの貢献に感謝!

使用可能なリポジトリ

リポジトリ名	URL
HoloLens	MicrosoftDocs/HoloLens
Mixed Reality	MicrosoftDocs/Mixed-Reality
VR 愛好家ガイド	MicrosoftDocs/mixed-reality/enthusiast-guide

開始する前に

まだお持ちでない場合は、GitHub アカウント作成する必要があります。

手記

Microsoft の従業員の場合は、Microsoft オープンソースポータルで GitHub アカウントを Microsoft エイリアスにリンクします。 "Microsoft" に参加し、組織 "MicrosoftDocs" をします。

GitHub アカウントを設定する場合は、次のセキュリティ対策もお勧めします。

GitHub アカウントの強力なパスワードを作成します。
2 要素認証を有効にします。
安全な場所に回復コードを保存します。
のパブリックプロファイル設定を更新します。
- 自分の名前を設定し、パブリックメール を メールアドレス表示しないように設定することを検討してください。
- 投稿先の Microsoft Learn 記事にサムネイルが表示されるため、プロファイル画像をアップロードすることをお勧めします。
コマンドラインを使用する場合は、Windows用の Git Credential Manager 設定することを検討してください。そうすれば、投稿するたびにパスワードを入力する必要はありません。

発行システムは GitHub に関連付けられているため、これらの手順は重要です。 GitHub エイリアスを使用して、各記事の作成者または共同作成者として一覧表示されます。

既存の記事の編集

次のワークフローを使用して、Web ブラウザーで GitHub 経由で既存の記事をするための更新を行います。

"hololens" フォルダーで編集する記事に移動します。
右上にある編集ボタン (鉛筆アイコン) を選択します。

これにより、メインの、使い捨て可能なブランチが自動的に既定のブランチからフォークされます。
Markdown の基本に従って記事の内容を編集します。
各記事の上部にあるメタデータを更新します。
- タイトル: 記事を表示しているときにブラウザータブに表示されるページタイトル。ページタイトルは SEO とインデックス作成に使用されるため、必要な場合を除き、タイトルを変更しないでください (ただし、ドキュメントが公開される前の重要度は低くなります)。
- 説明:記事の内容の簡単な説明を書きます。これはSEOと発見を促進します。
- を作成 : ページの主な所有者である場合は、ここに GitHub エイリアスを追加します。
- ms.author: ページの主な所有者である場合は、ここに Microsoft エイリアスを追加します (は必要ありません。エイリアスのみ)。
- ms.date: ページに主要なコンテンツを追加する場合は日付を更新しますが、明確化、書式設定、文法、スペルチェックなどの修正には適用されません。
- キーワード:キーワードはSEO(検索エンジンの最適化)に役立ちます。記事に固有のキーワードをコンマとスペースで区切って追加しますが、リスト内の最後のキーワードの後に句読点は追加しません。他の場所で管理されるため、すべての記事に適用されるグローバルキーワードを追加する必要はありません。
記事の編集が完了したら、下にスクロールし、[ファイルの変更提案] を選択します。
次のページ [pull request の作成] を選択して、自動的に作成されたブランチをメイン既定のブランチにマージします。
編集する次の記事について、上記の手順を繰り返します。

既存のアーティクルの名前変更または削除

変更によって既存の記事の名前が変更または削除される場合は、必ずリダイレクトを追加してください。そうすることで、既存の記事へのリンクを持つすべてのユーザーは、引き続き適切な場所に表示されます。リダイレクトは、リポジトリのルートにある .openpublishing.redirection.json ファイルによって管理されます。

.openpublishing.redirection.jsonへのリダイレクトを追加するには、redirections 配列にエントリを追加します。

{
    "redirections": [
        {
            "source_path": "hololens/old-article",
            "redirect_url": "/base-url/new-article#section-about-old-topic",
            "redirect_document_id": false
        },

source_path は、削除する古いアーティクルへの相対リポジトリパスです。パスがドキュメントセット (この場合は hololens) で始まり、.md ファイル拡張子が含まれていることを確認してください。
redirect_url は、古い記事から新しい記事への相対パブリック URL です。この URL には .md 含まれていないことを確認し、リポジトリパスではなくパブリック URL を参照するため、/で始まります。 #section を使用して、新しい記事内のセクションへのリンクを許可します。必要に応じて、別のサイトへの絶対パスを使用することもできます。
redirect_document_id は、前のファイルのドキュメント ID を保持するかどうかを示します。既定値は falseです。リダイレクトされた記事の ms.documentid 属性値を保持する場合は、true を使用します。ドキュメント ID を保持すると、ページビューやランキングなどのデータがターゲットアーティクルに転送されます。リダイレクトが主に名前変更であり、同じコンテンツの一部のみをカバーする別の記事へのポインターではない場合は、これを行います。

リダイレクトを追加する場合は、必ず古いファイルも削除してください。

新しい記事の作成

次のワークフローを使用して、Web ブラウザーの GitHub を使用してドキュメントリポジトリに新しい記事を作成します。

右上にある Fork ボタンを使用して、MicrosoftDocs/hololens の既定のブランチ (メイン) からフォークを作成します。
[hololens] フォルダーで、右上 [新しいファイル の作成] を選択します。
記事のページ名を作成し (スペースの代わりにハイフンを使用し、句読点やアポストロフィを使用しない)、".md" を追加します。

大事な

"hololens" フォルダー内から新しい記事を作成してください。これを確認するには、新しいファイル名の行で "/hololens/" を確認します。
新しいページの上部に、次のメタデータブロックを追加します。
```
---
title:
description:
author:
ms.author:
ms.date:
ms.topic: article
keywords:
---
```
既存の記事を編集するで前述したように、関連するメタデータフィールド入力します。
Markdown の基本使用して記事のコンテンツを記述します。
記事の下部に ## See also セクションを追加し、関連するその他の記事へのリンクを追加します。
完了したら、[新しいファイル コミット]を選択します。
[新しい pull request 選択し、フォークのメインブランチを MicrosoftDocs/hololens メインにマージします (矢印が正しい宛先を指していることを確認してください)。

Markdown の基本

Markdown 言語を使用してドキュメントを編集する方法については、次のリソースを参照してください。

Markdown の基本
[ 用の Markdown を記述するためのその他のリソース

テーブルの追加

Microsoft Learn でテーブルのスタイルを設定する方法により、インライン CSS を試しても、罫線やカスタムスタイルはありません。短時間は機能するように見えますが、最終的にはプラットフォームによって、テーブルからスタイルが削除されます。そのため、事前に計画を立て、テーブルをシンプルに保ちます。 Markdown テーブルを簡単にするサイトを次に示します。[Tables Generator]](https://www.tablesgenerator.com/markdown_tables)。

Docs Markdown Extension for Visual Studio Code を使用すると、ドキュメントを編集 Visual Studio Code (下記参照) を使用している場合でも、テーブルの生成が簡単になります。

イメージの追加

リポジトリの "hololens/images" フォルダーに画像をアップロードし、記事で適切に参照する必要があります。画像は自動的にフルサイズで表示されます。つまり、大きな画像は記事の幅全体を埋めます。画像をアップロードする前に、事前にサイズを設定することをお勧めします。推奨される幅は 600 ~ 700 ピクセルですが、それぞれ高密度のスクリーンショットまたはスクリーンショットの一部である場合は、サイズを上下に設定する必要があります。

大事な

マージする前に、フォークしたリポジトリにのみイメージをアップロードできます。そのため、記事に画像を追加する予定がある場合は、まず Visual Studio Code を使用して、フォークの "images" フォルダーに画像を追加するか、Web ブラウザーで次の作業を行っていることを確認必要があります。

MicrosoftDocs/hololens リポジトリをフォークしました。
フォーク内の記事を編集しました。
記事で参照している画像をフォーク内の "hololens/images" フォルダーにアップロードしました。
フォークをメインブランチ MicrosoftDocs/hololens にマージする pull request を作成しました。

独自のフォークされたリポジトリを設定する方法については、新しい記事を作成手順に従ってください。

作業内容のプレビュー

Web ブラウザーを使用して GitHub で編集しているときに、ページの上部付近にある [プレビュー] タブを選択して、コミットする前に作業をプレビューできます。

手記

Microsoft Learn での変更のプレビューは、Microsoft の従業員のみが利用できます。

Microsoft の従業員: 投稿が既定のブランチ (メイン) にマージされたら、コンテンツを確認してから、/hololens?branch=mainで公開できます。左側の列にある目次を使用して、記事を検索します。

ブラウザーでの編集とデスクトップクライアントでの編集

ブラウザーでの編集は、簡単な変更を行う最も簡単な方法ですが、いくつかの欠点があります。

スペルチェックは行われません。
他の記事へのスマートリンクは取得されません (記事のファイル名を手動で入力する必要があります)。
画像をアップロードして参照するのは面倒な場合があります。

これらの問題に対処しない場合は、Visual Studio Code などのデスクトップクライアントを使用し、投稿時に役立つ拡張機能をいくつか使用します。

Visual Studio Code の使用

上記の理由から、Web ブラウザーの代わりにデスクトップクライアントを使用してドキュメントを編集することをお勧めします。 Visual Studio Codeを使用することをお勧めします。

セットアップ

このリポジトリを操作するように Visual Studio Code を構成するには、次の手順に従います。

Web ブラウザーで次の手順を実行します。
1. PC用 Git をインストールします。
2. Visual Studio Codeインストールします。
3. まだしていない場合は、Fork MicrosoftDocs/hololens を使用します。
4. フォークで[複製]選択するか、 をダウンロードして URL をコピーします。
Visual Studio Code でフォークのローカルクローンを作成します。
1. [表示] メニューから、[コマンドパレット]選択します。
2. 「Git: Clone」と入力します。
3. コピーした URL を貼り付けます。
4. 複製を PC に保存する場所を選択します。
5. ポップアップ [リポジトリ を開く] を選択します。

ドキュメントの編集

Visual Studio Code でドキュメントを変更するには、次のワークフローを使用します。

手記

記事の編集との作成に関するすべてのガイダンスと、上記の Markdownの編集のの基本は、Visual Studio Code を使用する場合にも適用されます。

複製したフォークが公式リポジトリで最新であることを確認します。
1. Web ブラウザーで、メインMicrosoftDocs/hololens の既定のブランチにある他の共同作成者からの最近の変更をフォークに同期するプル要求を作成します (矢印が正しい宛先を指していることを確認します)。
2. Visual Studio Code で、同期ボタンを選択して、更新されたフォークをローカル複製に同期します。
Visual Studio Code を使用して、複製したリポジトリで記事を作成または編集します。
1. 1 つ以上の記事を編集します (必要に応じて、画像を "images" フォルダーに追加します)。
2. エクスプローラーでの変更保存します。
  
  エクスプローラーで [すべて保存] を選択
3. ソース管理でのすべての変更コミットします (メッセージが表示されたらコミットメッセージを書き込みます)。
  
  で [すべてコミット] を選択します
4. [同期] ボタンを選択して、変更内容を元の元 (GitHub のフォーク) に同期します。
Web ブラウザーで、フォークの新しい変更を MicrosoftDocs/hololens メイン に同期するプル要求を作成します (矢印が正しい宛先を指していることを確認してください)。

便利な拡張機能

次の Visual Studio Code 拡張機能は、ドキュメントを編集するときに役立ちます。

Docs Markdown Extension for Visual Studio Code - Alt + M を使用して、次のような Microsoft Learn オーサリングオプションのメニューを表示します。
- アップロードした画像を検索して参照します。
- リスト、テーブル、>[!NOTE]などのコールアウトなどの書式設定を追加します。
- 内部リンクとブックマーク (ページ内の特定のセクションへのリンク) を検索して参照します。
- 書式設定エラーが強調表示されます (エラーの上にマウスポインターを置くと詳細が表示されます)。
コードスペルチェッカー - スペルミスの単語に下線が引きます。スペルミスのある単語を右クリックして変更するか、辞書に保存します。