Přispívání do dokumentace pro vývojáře hybridní reality

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

Dokumentace k hybridní realitě je teď hostovaná v Microsoft Learn, která používá Markdown s funkcemi Markdigu na GitHubu. Obsah, který v tomto úložišti upravujete, se naformátuje na stylizované stránky, které se zobrazují na /windows/mixed-realityadrese .

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ě

Než začnete

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

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

• Vytvořte pro svůj účet GitHub silné heslo.
• Povolte dvojúrovňové ověřování.
• Uložte kódy pro obnovení na bezpečném místě.
• Aktualizujte nastavení veřejného profilu.
  • Nastavte svoje jméno a zvažte nastavení vašeho veřejného e-mailu na možnost Nezobrazovat moji e-mailovou adresu.
  • Doporučujeme nahrát profilový obrázek, protože miniatura se zobrazuje na stránkách docs, do které přispíváte.
• Pokud plánujete používat příkazový řádek, zvažte nastavení Správce přihlašovacích údajů Gitu pro Windows. Tímto způsobem nebudete muset zadávat heslo pokaždé, když uděláte příspěvek.

Systém publikování je svázaný s GitHubem, takže tyto kroky jsou důležité. Každý článek bude uvedený jako autor nebo přispěvatel pomocí aliasu GitHubu.

Ú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. Přejděte do článku, který chcete upravit ve složce mixed-reality-docs.

2. Vyberte tlačítko pro úpravy (ikonu tužky) v pravém horním rohu, které automaticky rozvětvenou větev na jedno použití vypne z hlavní větve.

   

3. Upravte obsah článku podle "základů 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 není potřeba (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ý zvyšuje 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 vyhledávacího webu). Přidejte klíčová slova oddělená čárkou a mezerou, která jsou specifická pro váš článek, ale za poslední klíčové slovo v seznamu není interpunkce. 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, aby se vaše automaticky vytvořená větev sloučila 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í. Každý, kdo má odkaz na existující článek, tak skončí na správném místě. Přesměrování spravuje .openpublishing.redirection.json soubor v kořenovém adresáři úložiště.

Pokud chcete přidat přesměrování na .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
        },
    ...
    ]
}

• Jedná se source_path o relativní cestu k úložišti původního článku, který odebíráte. Ujistěte se, že cesta začíná mixed-reality-docs a končí na .md.
• Jedná se redirect_url o relativní veřejnou adresu URL ze starého článku na nový článek. Ujistěte se, že tato adresa URL neobsahuje mixed-reality-docs nebo .md, protože odkazuje na veřejnou adresu URL, a ne na cestu k úložišti. Propojení s oddílem v novém článku, který používá #section , je povolené. 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í hodnota 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í, budou přenesena do cílového článku. Tento postup proveďte, pokud je přesměrování primárně přejmenování, a ne ukazatel na jiný článek, který se zabývá pouze některými stejným obsahem.

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 vytvořte 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 MicrosoftDocs/mixed-reality master (pomocí tlačítka Fork v pravém horním rohu).

   

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

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

   

   Důležité

   Ujistěte se, že nový článek vytvoříte ze složky mixed-reality-docs. Můžete to ověřit tak, že v novém řádku názvu 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 části výše.

6. Napište obsah článku pomocí základů Markdownu.

7. ## See also V 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 Novou žádost o přijetí změn a sloučíte větev "master" vašeho 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 Markdownu
• Plakát s referenčními informacemi o Markdownu na první pohled
• Další zdroje informací o psaní Markdownu pro Microsoft Learn

Přidání tabulek

Vzhledem ke způsobu, jakým tabulky stylů technické dokumentace Microsoftu nemají ohraničení ani vlastní styly, i když zkusíte vložené šablony stylů CSS. Zdá se, že bude fungovat po krátkou dobu, ale nakonec platforma odstraní styling z tabulky. Takže 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ání obrázků

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

Zobrazení náhledu práce

Při úpravách na GitHubu ve webovém prohlížeči můžete před potvrzením zobrazit náhled práce výběrem karty Náhled v horní části stránky.

Zaměstnanci Microsoftu: Jakmile se vaše příspěvky sloučí do hlavní větve, můžete obsah zkontrolovat dříve, než bude veřejně přístupný na adrese /windows/mixed-reality?branch=main. Najděte 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ést rychlé změny, ale má několik nevýhod:

• Nemáte kontrolu pravopisu.
• Nemáte žádné inteligentní propojení s jinými články (musíte zadat název souboru článku ručně).
• Může to být obtěžka pro nahrání a odkaz na obrázky.

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

Používání Visual Studio Code

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

Nastavení

Pokud chcete nakonfigurovat Visual Studio Code tak, aby fungoval s tímto úložištěm, postupujte takto:

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 Zobrazení vyberte Paleta příkazů.
   2. Zadejte Git: Clone.
   3. Vložte zkopírovanou adresu URL.
   4. Zvolte, kam chcete klon uložit do počítače.
   5. V automaticky otevíraných oken vyberte Otevřít úložiště .

Dokumentace k úpravám

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

1. Ujistěte se, že je klonovaný fork aktuální s oficiálním úložištěm.

   1. Ve webovém prohlížeči vytvořte žádost o přijetí změn pro synchronizaci nedávných změn od ostatních přispěvatelů v MicrosoftDocs/mixed-reality master do forku (ujistěte se, že šipka ukazuje správným směrem).

      

   2. V editoru Visual Studio Code vyberte tlačítko synchronizace, abyste synchronizovali nově aktualizovaný fork s místním klonem.

      

2. Vytvářejte nebo upravujte články v naklonované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 obrázky).

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

      

   3. Potvrďte všechny změny ve správě zdrojového kódu (po zobrazení výzvy zapište zprávu 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 pro synchronizaci nových změn ve forku zpět do MicrosoftDocs/mixed-reality master (ujistěte se, že šipka ukazuje správným způsobem).

   

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 – Použití Alt+M k zobrazení nabídky možností vytváření dokumentů, jako jsou:
  • Můžete hledat a odkazovat na obrázky, které jste nahráli.
  • Přidejte formátování, jako jsou seznamy, tabulky a popisky specifické pro dokumenty, například >[!NOTE].
  • Vyhledávání a odkazování 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 najedete myší na chybu).
• Kontrola pravopisu kódu – chybně napsaná slova budou podtržená. Klikněte pravým tlačítkem myši na chybně napsané slovo a změňte ho nebo ho uložte do slovníku.