Přispívání do Mixed Reality vývojářské dokumentace

Vítejte ve veřejném úložišti pro Mixed Reality dokumentaci pro vývojáře! Všechny články, které vytvoříte nebo upravíte v tomto úložišti, budou viditelné pro veřejnost.

Dokumenty Mixed Reality jsou teď hostované na Webu Microsoft Learn, který používá Markdown s funkcemi Markdigu s příchutí GitHubu. Obsah, který upravíte v tomto úložišti, se formátuje na stylizované stránky, které se zobrazí na adrese /windows/mixed-reality.

Tato stránka popisuje základní kroky a pokyny pro přispívání a odkazy na základy Markdownu. Děkujeme za váš příspěvek.

Dostupná úložiště

Název úložiště	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
Hybridní realita	Microsoft Docs/mixed-reality
Průvodce nadšenci pro virtuální realitu	MicrosoftDocs/mixed-reality/enthusiast-guide

Než začnete

Pokud ho ještě nemáte, budete si muset vytvořit účet GitHubu.

Poznámka

Pokud jste zaměstnancem Microsoftu, propojte svůj účet GitHub s aliasem Microsoftu na portálu Microsoft Open Source. Připojte se k organizacím Microsoft a MicrosoftDocs .

Při nastavování účtu GitHub doporučujeme také tato bezpečnostní opatření:

• Vytvořte si silné heslo pro účet GitHub.
• Povolte dvojúrovňové ověřování.
• Kódy pro obnovení uložte na bezpečné místo.
• Aktualizujte nastavení veřejného profilu.
  • Nastavte své jméno a zvažte nastavení veřejného e-mailu na Nezozorovat moji e-mailovou adresu.
  • Doporučujeme nahrát profilový obrázek, protože na stránkách dokumentace, na které přispíváte, se zobrazuje miniatura.
• Pokud plánujete používat příkazový řádek, zvažte nastavení Správce přihlašovacích údajů Gitu pro Windows. Díky tomu nebudete muset heslo zadávat pokaždé, když přispíváte.

Systém publikování je spojený s GitHubem, takže tyto kroky jsou důležité. Pomocí svého aliasu GitHubu budete uvedeni jako autor nebo přispěvatel každého článku.

Úprava existujícího článku

Pomocí následujícího pracovního postupu proveďte aktualizace existujícího článku prostřednictvím GitHubu ve webovém prohlížeči:

1. Ve složce mixed-reality-docs přejděte na článek, který chcete upravit.

2. V pravém horním rohu vyberte tlačítko pro úpravy (ikona tužky), které automaticky rozvětvuje jednorázovou větev mimo větev master.

   

3. Upravte obsah článku podle "Základy Markdownu".

4. Aktualizujte metadata v horní části každého článku:

   • title: Název stránky, který se zobrazí na kartě prohlížeče při prohlížení článku. Názvy stránek se používají pro SEO a indexování, takže název neměňte, pokud to není nutné (i když je to méně důležité před zveřejněním dokumentace).
   • description: Napište stručný popis obsahu článku, který podporuje SEO a zjišťování.
   • autor: Pokud jste primárním vlastníkem stránky, přidejte sem svůj alias GitHubu.
   • ms.author: Pokud jste primárním vlastníkem stránky, přidejte sem svůj alias Microsoftu (nepotřebujete @microsoft.com, jenom alias).
   • ms.date: Aktualizujte datum, pokud na stránku přidáváte hlavní obsah, ale ne pro opravy, jako je objasnění, formátování, gramatika nebo pravopis.
   • klíčová slova: Pomoc s klíčovými slovy v SEO (optimalizace pro vyhledávače). Přidejte klíčová slova oddělená čárkou a mezerou, která jsou specifická pro váš článek, ale bez interpunkce za poslední klíčové slovo v seznamu. Nemusíte přidávat globální klíčová slova, která platí pro všechny články, protože se spravují jinde.

5. Po dokončení úprav článku se posuňte dolů a vyberte Navrhnout změnu souboru.

6. Na další stránce vyberte Vytvořit žádost o přijetí změn a sloučíte automaticky vytvořenou větev do hlavní větve.

7. Opakujte výše uvedené kroky pro další článek, který chcete upravit.

Přejmenování nebo odstranění existujícího článku

Pokud vaše změna přejmenuje nebo odstraní existující článek, nezapomeňte přidat přesměrování. Díky tomu bude každý, kdo má odkaz na existující článek, stále na správném místě. Přesměrování spravuje soubor .openpublishing.redirection.json v kořenovém adresáři úložiště.

Pokud chcete přidat přesměrování do souboru .openpublishing.redirection.json, přidejte do redirections pole položku:

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

• Je source_path relativní cesta k původnímu článku, který odebíráte. Ujistěte se, že cesta začíná mixed-reality-docs na a končí na .md.
• Je redirect_url relativní veřejná adresa URL ze starého článku na nový článek. Ujistěte se, že tato adresa URL neobsahujemixed-reality-docs nebo , .mdprotože odkazuje na veřejnou adresu URL, a ne na cestu k úložišti. Propojení s oddílem v novém článku pomocí #section je povoleno. V případě potřeby můžete také použít absolutní cestu k jinému webu.
• redirect_document_id určuje, jestli chcete zachovat ID dokumentu z předchozího souboru. Výchozí formát je false. Použijte true , pokud chcete zachovat hodnotu atributu ms.documentid z přesměrovaného článku. Pokud zachováte ID dokumentu, data, jako jsou zobrazení stránek a hodnocení, se přenesou do cílového článku. To udělejte, pokud je přesměrování primárně přejmenováním, a ne ukazatelem na jiný článek, který pokrývá jenom část stejného obsahu.

Pokud přidáte přesměrování, nezapomeňte odstranit i starý soubor.

Vytvoření nového článku

Pomocí následujícího pracovního postupu můžete vytvořit nové články v úložišti dokumentace prostřednictvím GitHubu ve webovém prohlížeči:

1. Vytvořte fork z větve Master MicrosoftDocs/mixed-reality (pomocí tlačítka Fork v pravém horním rohu).

   

2. Ve složce "mixed-reality-docs" vyberte Vytvořit nový soubor v pravém horním rohu.

3. Vytvořte název stránky pro článek (místo mezer používejte spojovníky a nepoužívejte interpunkci ani apostrofy) a připojte ".md".

   

   Důležité

   Ujistěte se, že jste nový článek vytvořili ve složce "mixed-reality-docs". To můžete potvrdit tak, že v novém řádku s názvem souboru vyhledáte /mixed-reality-docs/.

4. V horní části nové stránky přidejte následující blok metadat:

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

5. Vyplňte příslušná pole metadat podle pokynů v předchozí části.

6. Napište obsah článku pomocí základních informací o Markdownu.

7. ## See also Do dolní části článku přidejte oddíl s odkazy na další relevantní články.

8. Po dokončení vyberte Potvrdit nový soubor.

9. Vyberte Nová žádost o přijetí změn a sloučte větev hlavní větve forku do MicrosoftDocs/mixed-reality master (ujistěte se, že šipka ukazuje správným směrem).

   

Základy formátu Markdown

Následující zdroje informací vám pomůžou naučit se upravovat dokumentaci pomocí jazyka Markdown:

• Základy formátu Markdown
• Plakát s referenčními informacemi o Markdownu
• Další zdroje informací o psaní Markdownu pro Microsoft Learn

Přidávání tabulek

Vzhledem ke způsobu, jakým jsou tabulky stylů technické dokumentace Microsoftu, nebudou mít ohraničení ani vlastní styly, a to ani v případě, že vyzkoušíte vložené šablony stylů CSS. Bude se zdát, že funguje po krátkou dobu, ale nakonec platforma odstraní styl z tabulky. Proto plánujte dopředu a udržujte tabulky jednoduché. Tady je web, který usnadňuje tabulky Markdownu.

Rozšíření Docs Markdown pro Visual Studio Code také usnadňuje generování tabulek, pokud k úpravě dokumentace používáte Visual Studio Code (viz níže).

Přidávání obrázků

Obrázky budete muset nahrát do složky "mixed-reality-docs/images" v úložišti a pak na ně v článku odpovídajícím způsobem odkazovat. Obrázky se automaticky zobrazí v plné velikosti, což znamená, že velké obrázky zaplní celou šířku článku. Před nahráním obrázků doporučujeme předem nastavit velikost. Doporučená šířka je mezi 600 a 700 pixely, ale velikost byste měli zvětšit nebo snížit, pokud se jedná o hustý snímek obrazovky nebo zlomek snímku obrazovky.

Důležité

Obrázky můžete do rozvětženého úložiště nahrát jenom před sloučením. Pokud tedy máte v úmyslu přidat obrázky do článku, budete je muset nejdřív přidat do složky "images" vašeho forku pomocí editoru Visual Studio Code nebo se ujistit, že jste ve webovém prohlížeči provedli následující kroky:

1. Vytvoření forku úložiště MicrosoftDocs/mixed-reality
2. Upravili jsme článek ve forku.
3. Nahrajte obrázky, na které odkazujete ve svém článku, do složky "mixed-reality-docs/images" ve vašem forku.
4. Vytvořili jste žádost o přijetí změn , která sloučí váš fork do větve Master MicrosoftDocs/mixed-reality.

Pokud chcete zjistit, jak nastavit vlastní fork úložiště, postupujte podle pokynů k vytvoření nového článku.

Náhled práce

Při úpravách na GitHubu prostřednictvím webového prohlížeče můžete vybrat kartu Náhled v horní části stránky a zobrazit náhled práce před potvrzením.

Poznámka

Náhled fázovaných změn je k dispozici jenom zaměstnancům Microsoftu.

Zaměstnanci Microsoftu: Jakmile se vaše příspěvky sloučí do větve main, můžete si obsah před zveřejněním prohlédnout na adrese /windows/mixed-reality?branch=main. Vyhledejte svůj článek pomocí obsahu v levém sloupci.

Úpravy v prohlížeči vs. úpravy pomocí desktopového klienta

Úpravy v prohlížeči představují nejjednodušší způsob, jak provádět rychlé změny, má ale několik nevýhod:

• Nedostanete kontrolu pravopisu.
• Nezískáte žádné inteligentní odkazy na jiné články (musíte ručně zadat název souboru článku).
• Nahrávání obrázků a odkaz na obrázky může být obtěžovat.

Pokud nechcete tyto problémy řešit, použijte při přispívání desktopového klienta, jako je Visual Studio Code , s několika užitečnými rozšířeními .

Používání nástroje Visual Studio Code

Z výše uvedených důvodů můžete k úpravě dokumentace raději použít desktopového klienta než webový prohlížeč. Doporučujeme použít Visual Studio Code.

Nastavení

Postupujte podle těchto kroků a nakonfigurujte Visual Studio Code tak, aby fungoval s tímto úložištěm:

1. Ve webovém prohlížeči:
   1. Nainstalujte Git pro svůj počítač.
   2. Nainstalujte Visual Studio Code.
   3. Fork MicrosoftDocs/mixed-reality , pokud jste to ještě neudělali.
   4. Ve forku vyberte Klonovat nebo stáhnout a zkopírujte adresu URL.
2. Vytvořte místní klon forku v editoru Visual Studio Code:
   1. V nabídce View (Zobrazení ) vyberte Command Palette (Paleta příkazů).
   2. Zadejte Git: Clone.
   3. Vložte adresu URL, kterou jste zkopírovali.
   4. Zvolte, kam chcete klon uložit na počítači.
   5. V automaticky otevírané nabídce vyberte Otevřít úložiště .

Úpravy dokumentace

Pomocí následujícího pracovního postupu proveďte změny v dokumentaci pomocí editoru Visual Studio Code:

Poznámka

Všechny doprovodné materiály k úpravám a vytváření článků a základy úprav Markdownu výše platí i pro použití editoru Visual Studio Code.

1. Ujistěte se, že váš naklonovaný fork je aktuální v oficiálním úložišti.

   1. Ve webovém prohlížeči vytvořte žádost o přijetí změn, aby se synchronizovaly nedávné změny od jiných přispěvatelů v MicrosoftDocs/master hybridní reality s vaším forkem (ujistěte se, že šipka ukazuje správnou cestou).

      

   2. V editoru Visual Studio Code výběrem tlačítka synchronizace synchronizujte nově aktualizovaný fork s místním klonem.

      

2. Vytvářejte nebo upravujte články v klonovaném úložišti pomocí editoru Visual Studio Code.

   1. Upravte jeden nebo více článků (v případě potřeby přidejte obrázky do složky "images").

   2. Uložte změny v Průzkumníkovi.

      

   3. Potvrďte všechny změny ve správě zdrojového kódu (po zobrazení výzvy zapište zprávu o potvrzení).

      

   4. Výběrem tlačítka synchronizace synchronizujte změny zpět do zdroje (váš fork na GitHubu).

      

3. Ve webovém prohlížeči vytvořte žádost o přijetí změn, aby se synchronizovaly nové změny ve forku zpět do MicrosoftDocs/mixed-reality master (ujistěte se, že šipka ukazuje správným směrem).

   

Užitečná rozšíření

Při úpravách dokumentace jsou užitečná následující rozšíření editoru Visual Studio Code:

• Rozšíření Docs Markdown pro Visual Studio Code – Pomocí Alt+M zobrazíte nabídku možností vytváření dokumentů, jako jsou:
  • Vyhledejte obrázky, které jste nahráli, a odkazy na tyto obrázky.
  • Přidejte formátování, jako jsou seznamy, tabulky a popisky specifické pro dokumenty, například >[!NOTE].
  • Vyhledávání a odkaz na interní odkazy a záložky (odkazy na konkrétní oddíly na stránce)
  • Chyby formátování jsou zvýrazněné (další informace získáte tak, že na tuto chybu najedete myší).
• Kontrola pravopisu kódu – chybně napsaná slova budou podtržená; Klikněte pravým tlačítkem na chybně napsané slovo a změňte ho nebo ho uložte do slovníku.