Sdílet prostřednictvím

Learn Authoring Pack pro Visual Studio Code

  • Článek

Sada Learn Authoring Pack je kolekce rozšíření editoru Visual Studio Code, která vám pomůžou s vytvářením obsahu Jazyka Markdown pro obsah Microsoft Learn. Balíček je dostupný na VS Code Marketplace a obsahuje následující rozšíření:

  • Learn Markdown: Poskytuje pomoc při vytváření obsahu v Microsoft Learn v Markdownu, včetně podpory základní syntaxe Markdownu a také vlastní syntaxe Markdownu, jako jsou upozornění, fragmenty kódu a nelokalizovatelný text. Nově také obsahuje pomoc při vytváření YAML, například vkládání položek obsahu.
  • Markdownlint: Oblíbený linter Markdown od Davida Ansona, který pomáhá zajistit, aby byl Markdown platný.
  • Code Spell Checker: Kontrola pravopisu od firmy Street Side Software, která funguje plně offline.
  • Learn Preview: Používá šablony stylů CSS microsoft Learn k přesnějšímu náhledu Markdownu, včetně vlastního Markdownu.
  • Šablony článků naučte se: Umožňuje uživatelům vygenerovat moduly Learn a použít obsah kostry Markdownu na nové soubory.
  • Naučte se YAML: Poskytuje ověřování schématu YAML a automatické dokončování.
  • Obrázky naučte se: Poskytuje kompresi obrázků a změnu velikosti pro složky a jednotlivé soubory, které autorům obsahu Microsoft Learn pomůžou.

Požadavky a předpoklady

Pokud chcete vložit relativní odkazy, obrázky a další vložený obsah s rozšířením Learn Markdown, musíte mít pracovní prostor VS Code vymezený na kořen vašeho naklonovaného úložiště OPS (Open Publishing System). Pokud jste například naklonovali úložiště docs do C:\git\SomeDocsRepo\, otevřete tuto složku nebo podsložku v editoru VS Code: nabídka Otevřít složku souboru>nebo code C:\git\SomeDocsRepo\ z příkazového řádku.

Určité syntaxe podporované rozšířením, například výstrahy a fragmenty kódu, představují vlastní Markdown pro OPS. Ten se nebude správně vykreslovat, dokud ho nepublikujete přes OPS.

Jak používat rozšíření Learn Markdown

Pokud chcete získat přístup k nabídce Learn Markdown, zadejte Alt+M. Požadovaný příkaz vyberete kliknutím nebo pomocí šipek nahoru a dolů. Případně můžete zadáním textu spustit filtrování, a jakmile se v nabídce zvýrazní nabídka, kterou hledáte, stisknout klávesu Enter.

Aktuální seznam příkazů najdete v souboru Readme Learn Markdown.

Jak vygenerovat hlavní soubor přesměrování

Rozšíření Learn Markdown obsahuje skript pro vygenerování nebo aktualizaci hlavního souboru přesměrování pro úložiště na redirect_url základě metadat v jednotlivých souborech. Tento skript zkontroluje, zda každý soubor Markdownu v úložišti obsahuje redirect_url, přidá metadata přesměrování do hlavního souboru přesměrování (.openpublishing.redirection.json) úložiště a přesune přesměrované soubory do složky mimo úložiště. Spuštění skriptu:

  1. Výběrem klávesy F1 otevřete paletu příkazů nástroje VS Code.
  2. Začněte psát "Learn: Generate..." (Naučte se: Generovat...
  3. Vyberte příkaz Learn: Generate main redirection file.
  4. Po dokončení spuštění skriptu se výsledky přesměrování zobrazí v podokně výstupu VS Code a odebrané soubory Markdownu se přidají do složky Learn Authoring\redirects ve vaší výchozí cestě.
  5. Zkontrolujte výsledky. Pokud jste s nimi spokojeni, odešlete žádost o přijetí změn, aby se úložiště aktualizovalo.

Přiřazení klávesových zkratek

  1. Stisknutím kláves Ctrl+K a ctrl+S otevřete seznam klávesových zkratek.

  2. Vyhledejte příkaz, například formatBold, pro který si chcete vytvořit svoji klávesovou zkratku.

  3. Klikněte na znaménko plus, které se zobrazí vedle názvu příkazu, když na řádek najedete myší.

  4. Jakmile se zobrazí nové okno pro zadání, napište klávesovou zkratku, kterou chcete spojit s konkrétním příkazem. Pokud chcete například použít společnou klávesovou zkratku pro tučné písmo, zadejte Ctrl+B.

  5. Do klávesové zkratky je vhodné vložit klauzuli when, aby nebyla dostupná v jiných souborech než v Markdownu. To uděláte tak, že otevřete soubor keybindings.json a pod název příkazu vložíte následující řádek (mezi řádky nezapomeňte uvést čárku):

    "when": "editorTextFocus && editorLangId == 'markdown'"

    Dokončená vlastní klávesová zkratka by v souboru keybindings.json měla vypadat takto:

    [
    {
        "key": "ctrl+b",
        "command": "formatBold",
        "when": "editorTextFocus && editorLangId == 'markdown'"
    }
]

    Tip

    Umístěním klávesové zkratky do tohoto souboru přepíšete výchozí hodnoty.

  6. Soubor keybindings.json uložte.

Další informace o klávesových zkratkách najdete v dokumentaci k nástroji VS Code.

Zobrazení staršího panelu nástrojů Gauntlet

Bývalí uživatelé rozšíření s názvem "Gauntlet" si všimnou, že panel nástrojů pro tvorbu se už při instalaci rozšíření Learn Markdown nezobrazí v dolní části okna editoru VS Code. Důvodem je to, že panel nástrojů zabíral mnoho místa na stavovém řádku nástroje VS Code a neřídil se doporučenými postupy pro uživatelské prostředí rozšíření, a proto se v novém rozšíření už nepoužívá. Panel nástrojů si ale můžete volitelně zobrazit, když následujícím způsobem aktualizujete soubor settings.json v nástroji VS Code:

  1. Ve VS Code přejděte na Předvolby> souborů>Nastavení nebo vyberte Ctrl.+

  2. Pokud chcete změnit nastavení všech pracovních prostorů nástroje VS Code, vyberte Uživatelská nastavení. Pokud chcete změnit jen nastavení aktuálního pracovního prostoru, vyberte Nastavení pracovního prostoru.

  3. Vyberte Rozšíření>Learn Markdown Extension Configuration a pak vyberte Zobrazit starší panel nástrojů na dolním stavovém řádku.

    Show legacy toolbar setting in VS Code

Jakmile výběr dokončíte, VS Code aktualizuje soubor settings.json. Potom vás systém vyzve, ať znovu načtete okno, aby se mohly změny projevit.

Novější příkazy přidané do rozšíření nebudou na tomto panelu nástrojů k dispozici.

Jak používat šablony Learn

Rozšíření Šablony článků Learn umožňuje autorům ve VS Code stáhnout šablonu Markdownu z centralizovaného úložiště a použít ji na soubor. Šablony například pomáhají zajistit, aby články obsahovaly požadovaná metadata a aby se dodržovaly standardy týkající se obsahu. Šablony se spravují jako soubory Markdown ve veřejném úložišti GitHubu.

Použití šablony v nástroji VS Code

  1. Ujistěte se, že je nainstalované a povolené rozšíření Šablony článků learn.
  2. Pokud nemáte nainstalované rozšíření Learn Markdown, kliknutím na F1 otevřete paletu příkazů, začněte psát "šablona" a pak klikněte na Learn: Template. Pokud máte nainstalovaný Learn Markdown, můžete použít buď paletu příkazů, nebo kliknout na Alt+M a otevřít nabídku Learn Markdown QuickPick a pak vybrat Template ze seznamu.
  3. V zobrazeném seznamu vyberte požadovanou šablonu.

Přidání ID GitHubu a/nebo aliasu Microsoftu do nastavení nástroje VS Code

Rozšíření Templates podporuje tři dynamická pole metadat: author, ms.author a ms.date. To znamená, že když autor šablony tato pole použije v záhlaví metadat nějaké šablony Markdownu, při jejím použití se tato pole automaticky naplní ve vašem souboru následujícím způsobem:

Pole metadat Hodnota
author Váš alias na GitHubu, pokud je zadané v souboru nastavení nástroje VS Code
ms.author Váš alias Microsoftu, pokud je zadaný v souboru nastavení nástroje VS Code. Pokud nejste zaměstnancem Microsoftu, nechejte toto pole nezadané.
ms.date Aktuální datum v podporovaném formátu MM/DD/YYYY. Toto datum se při následné aktualizaci souboru neaktualizuje automaticky, takže je potřeba ho aktualizovat ručně. Slouží k označení aktuálnosti článků.

Nastavení polí author a/nebo ms.author

  1. Ve VS Code přejděte na Předvolby> souborů>Nastavení nebo vyberte Ctrl.+
  2. Pokud chcete změnit nastavení všech pracovních prostorů nástroje VS Code, vyberte uživatelská nastavení. Pokud chcete změnit jen nastavení aktuálního pracovního prostoru, vyberte nastavení pracovního prostoru.
  3. V podokně Výchozí Nastavení vlevo najděte konfiguraci rozšíření Šablony článků Learn, klikněte na ikonu tužky vedle požadovaného nastavení a potom klikněte na nahradit v Nastavení.
  4. Vedle se otevře podokno uživatelských nastavení s novou položkou v dolní části.
  5. Přidejte svoje ID GitHubu nebo e-mailový alias Microsoftu a uložte tento soubor.
  6. Možná budete muset nástroj VS Code zavřít a znovu spustit, aby se změny projevily.
  7. Když teď použijete šablonu využívající dynamická pole, naplní se v záhlaví metadat automaticky vaše ID GitHubu a/nebo alias Microsoftu.

Zpřístupnění nové šablony v nástroji VS Code

  1. Vytvořte koncept šablony jako soubor Markdownu.
  2. Odešlete žádost o přijetí změn do složky šablon úložiště MicrosoftDocs/content-templates.

Tým obsahu zkontroluje vaši šablonu a žádost o přijetí změn sloučí, pokud splňuje pokyny pro styl. Po sloučení bude šablona dostupná všem uživatelům rozšíření Šablony článků na platformě Learn.

Ukázka několika funkcí

Toto je krátké video, které ukazuje následující funkce sady Learn Authoring Pack:

  • Soubory YAML
    • Podpora pro Learn: Odkaz na soubor v úložišti
  • Soubory Markdownu
    • Možnost „Update "ms.date" Metadata Value“ v místní nabídce
    • Podpora automatického dokončování kódu pro identifikátory jazyka kódového plotu
    • Upozornění na nerozpoznané identifikátory jazyka kódového plotu / podpora automatických oprav
    • Sort selection ascending (A to Z)
    • Seřazení výběru sestupně (od Z do A)

Další kroky

Prozkoumejte různé funkce dostupné v balíčku Learn Authoring Pack, rozšíření Visual Studio Code.