Delen via

Meer informatie over ontwerppakket voor Visual Studio Code

  • Artikel

Het Learn Authoring Pack is een verzameling Visual Studio Code-extensies die u kunt helpen bij het ontwerpen van Markdown voor Microsoft Learn-inhoud. Het pakket is verkrijgbaar via de VS Code Marketplace en bevat de volgende extensies:

  • Learn Markdown: biedt hulp bij het ontwerpen van Markdown voor inhoud in Microsoft Learn, waaronder ondersteuning voor de basissyntaxis van Markdown en aangepaste Markdown-syntaxis, zoals waarschuwingen, codefragmenten en niet-lokaliseerbare tekst. Bevat nu ook enkele basisondersteuning voor het aanpassen van YAML, zoals het invoegen van vermeldingen in de inhoudsopgave.
  • markdownlint: Een populaire Markdown linter van David Anson om ervoor te zorgen dat uw Markdown geldig is.
  • Code Spell Checker: een spellingcontrole van Street Side Software die volledig offline is.
  • Learn Preview: maakt gebruik van de Microsoft Learn CSS voor een nauwkeurigere Markdown-preview, waaronder aangepaste Markdown.
  • Learn-artikelsjablonen: hiermee kunnen gebruikers Learn-modules opzetten en Markdown-skeletinhoud toepassen op nieuwe bestanden.
  • Learn YAML: biedt YAML-schemavalidatie en automatisch aanvullen.
  • Learn-afbeeldingen: biedt compressie van afbeeldingen en het formaat van mappen en afzonderlijke bestanden om auteurs van Microsoft Learn-inhoud te helpen.

Vereisten en aannames

Als u relatieve koppelingen, afbeeldingen en andere ingesloten inhoud wilt invoegen met de Learn Markdown-extensie, moet uw VS Code-werkruimte zijn afgestemd op de hoofdmap van de gekloonde OPS-opslagplaats (Open Publishing System). Als u bijvoorbeeld de docs-opslagplaats hebt gekloond naarC:\git\SomeDocsRepo\, opent u die map of een submap in VS Code: menu Map> openen bestand of code C:\git\SomeDocsRepo\ vanaf de opdrachtregel.

Sommige syntaxissen die door de extensie worden ondersteund, zoals waarschuwingen en codefragmenten, bestaan uit aangepaste Markdown voor OPS. Aangepaste Markdown wordt niet goed weergegeven, tenzij u deze via OPS publiceert.

De Learn Markdown-extensie gebruiken

Als u het menu Learn Markdown wilt openen, typt u Alt+M. U kunt klikken of de pijl-omhoog en pijl-omlaag gebruiken om de gewenste opdracht te selecteren. U kunt ook typen om te beginnen met filteren en vervolgens op ENTER drukken wanneer de gewenste functie in het menu is gemarkeerd.

Zie de leesmij voor Learn Markdown voor een actuele lijst met opdrachten.

Een hoofdomleidingsbestand genereren

De Learn Markdown-extensie bevat een script voor het genereren of bijwerken van een hoofdomleidingsbestand voor een opslagplaats, op basis van de redirect_url metagegevens in afzonderlijke bestanden. Met dit script wordt elk Markdown-bestand in de opslagplaats gecontroleerd redirect_url, worden de metagegevens van de omleiding toegevoegd aan het hoofdomleidingsbestand (.openpublishing.redirection.json) voor de opslagplaats en worden de omgeleide bestanden verplaatst naar een map buiten de opslagplaats. Het script uitvoeren:

  1. Druk op F1 om het opdrachtenpalet van VS Code te openen.
  2. Begin met het typen van 'Learn: Generate...'
  3. Selecteer de opdracht Learn: Generate main redirection file.
  4. Wanneer het script is uitgevoerd, worden de omleidingsresultaten weergegeven in het uitvoervenster van VS Code en worden de verwijderde Markdown-bestanden toegevoegd aan de map Learn Authoring\redirects onder uw standaardpad.
  5. Controleer de resultaten. Als de resultaten naar verwachting zijn, verzendt u een pull-aanvraag om de opslagplaats bij te werken.

Sneltoetsen toewijzen

  1. Typ Ctrl+K en vervolgens Ctrl+S om de lijst met sneltoetsen te openen.

  2. Zoek de opdracht, zoals formatBold, waarvoor u een aangepaste toetsencombinatie wilt maken.

  3. Klik op het plusteken dat naast de naam van de opdracht verschijnt wanneer u met de cursor over de regel beweegt.

  4. Zodra een nieuw invoervak zichtbaar is, typt u de sneltoets die u aan die specifieke opdracht wilt koppelen. Als u bijvoorbeeld de veelgebruikte snelkoppeling voor vet wilt gebruiken, typt u Ctrl+B.

  5. Het kan handig zijn om een when-component in uw toetsencombinatie in te voegen, zodat deze alleen voor Markdown beschikbaar is en niet voor andere bestanden. Open hiervoor keybindings.json en voeg de volgende regel in onder de opdrachtnaam (vergeet geen komma tussen regels toe te voegen):

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

    Uw voltooide aangepaste toetsencombinatie zou er uit moeten zien zoals in deze keybindings.json:

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

    Tip

    Plaats uw toetscombinaties in dit bestand om de standaardcombinaties te overschrijven

  6. Sla keybindings.json op.

Zie VS Code-documenten voor meer informatie over toetscombinaties.

De verouderde werkbalk Gauntlet weergeven

Voormalige gebruikers van de extensiecode met de naam 'Gauntlet' merken dat de ontwerpwerkbalk niet meer onder aan het VS Code-venster wordt weergegeven wanneer de Learn Markdown-extensie is geïnstalleerd. De reden hiervoor is dat de werkbalk veel ruimte op de VS Code-statusbalk innam en niet voldeed aan de best practices voor extensie-UX. We hebben de werkbalk daarom afgeschaft in de nieuwe extensie. U kunt er echter wel voor kiezen om de werkbalk weer te geven. Werk hiervoor uw VS Code-bestand settings.json als volgt bij:

  1. Ga in VS Code naar Bestandsvoorkeuren>> Instellingen of selecteer Ctrl.+

  2. Selecteer Gebruikersinstellingen om de instellingen voor alle VS Code-werkruimten te wijzigen, of selecteer Instellingen voor werkruimte om alleen de instellingen voor de huidige werkruimte te wijzigen.

  3. Selecteer Extensions>Learn Markdown Extension Configuration en selecteer vervolgens De verouderde werkbalk weergeven op de onderste statusbalk.

    Show legacy toolbar setting in VS Code

Wanneer u de selectie hebt gemaakt, wordt het settings.json-bestand door VS Code bijgewerkt. Vervolgens wordt u gevraagd het venster opnieuw te laden zodat de wijzigingen van kracht worden.

Nieuwe opdrachten die worden toegevoegd aan de extensie, zijn niet beschikbaar op de werkbalk.

Learn-sjablonen gebruiken

Met de extensie Learn Article Templates kunnen schrijvers in VS Code een Markdown-sjabloon ophalen uit een gecentraliseerd archief en deze toepassen op een bestand. Sjablonen helpen ervoor te zorgen dat de vereiste metagegevens worden opgenomen in artikelen, dat inhoudsnormen worden opgevolgd, enzovoort. Sjablonen worden beheerd als Markdown-bestanden in een openbare GitHub-opslagplaats.

Een sjabloon toepassen in VS Code

  1. Zorg ervoor dat de extensie Learn Article Templates is geïnstalleerd en ingeschakeld.
  2. Als u de Learn Markdown-extensie niet hebt geïnstalleerd, klikt u op F1 om het opdrachtenpalet te openen, begint u 'sjabloon' te typen om te filteren en klikt u op Learn: Template. Als u Learn Markdown wel hebt geïnstalleerd, kunt u het opdrachtenpalet gebruiken of op Alt+M klikken om het snelkeuzemenu Learn Markdown weer te geven en vervolgens in de lijst te selecteren.Template
  3. Selecteer de gewenste sjabloon in de lijst die wordt weergegeven.

Uw GitHub-id en/of Microsoft-alias toevoegen aan de VS Code-instellingen

De Templates-extensie biedt ondersteuning voor drie velden met dynamische metagegevens: author, ms.author en ms.date. Dit betekent dat, wanneer de maker van een sjabloon deze velden gebruikt in de metagegevenskoptekst van een Markdown-sjabloon, ze als volgt automatisch worden ingevuld in uw bestand wanneer u de sjabloon toepast:

Metagegevensveld Weergegeven als
author Uw GitHub-alias, indien opgegeven in het bestand met VS Code-instellingen.
ms.author Uw Microsoft-alias, indien opgegeven in het bestand met VS Code-instellingen. Als u geen werknemer van Microsoft bent, laat u dit veld niet-gespecificeerd.
ms.date De huidige datum in de ondersteunde indeling. MM/DD/YYYY De datum wordt niet automatisch bijgewerkt als u het bestand vervolgens wijzigt. U moet de datum handmatig bijwerken. Dit veld geeft aan wanneer het artikel voor het laatst is vernieuwd.

Auteur en/of ms.author instellen

  1. Ga in VS Code naar Bestandsvoorkeuren>> Instellingen of selecteer Ctrl.+
  2. Selecteer Gebruikersinstellingen om de instellingen voor alle VS Code-werkruimten te wijzigen, of selecteer Instellingen voor werkruimte om alleen de instellingen voor de huidige werkruimte te wijzigen.
  3. Zoek in het deelvenster Standaard Instellingen aan de linkerkant de extensieconfiguratie van Learn-artikelsjablonen, klik op het potloodpictogram naast de gewenste instelling en klik vervolgens op Vervangen in Instellingen.
  4. Het Deelvenster Gebruikersinstellingen wordt geopend in een naastgelegen venster met onderaan een nieuwe vermelding.
  5. Voeg de GitHub-id of Microsoft-e-mailalias toe en sla het bestand op.
  6. Mogelijk moet u VS Code sluiten en opnieuw starten om de wijzigingen door te voeren.
  7. Wanneer u nu een sjabloon toepast die gebruikmaakt van dynamische velden, worden de GitHub-id en/of Microsoft-alias automatisch ingevuld in de koptekst van de metagegevens.

Een nieuwe sjabloon beschikbaar maken in VS Code

  1. Ontwerp uw sjabloon als een Markdown-bestand.
  2. Verzend een pull-aanvraag naar de map Sjablonen van de opslagplaats MicrosoftDocs/content-templates.

Het inhoudsteam beoordeelt uw sjabloon en voegt de pull-aanvraag samen als deze voldoet aan de stijlrichtlijnen. Zodra de sjabloon is samengevoegd, is deze beschikbaar voor alle gebruikers van de extensie Learn Article Templates.

Demo van verschillende functies

Hier volgt een korte video met de volgende functies van het Learn Authoring Pack:

  • YAML-bestanden
    • Ondersteuning voor 'Learn: Koppelen aan bestand in opslagplaats'
  • Markdown-bestanden
    • Contextmenuoptie om de metagegevenswaarde ms.date bij te werken
    • Ondersteuning voor het automatisch voltooien van code voor de taal-id's binnen een afscheiding
    • Waarschuwingen voor niet-herkende taal-id's binnen een afscheiding/ondersteuning voor automatische correctie
    • Selectie oplopend sorteren (A tot Z)
    • Selectie aflopend sorteren (Z tot A)

Volgende stappen

Verken de verschillende functies die beschikbaar zijn in de Visual Studio Code-extensie Learn Authoring Pack.