Contribuire con GitHub Codespaces

GitHub include una funzionalità denominata Codespaces che è possibile usare per contribuire alla documentazione di PowerShell senza dover installare o configurare software in locale. Quando si usa uno spazio di codice, si ottengono gli stessi strumenti di creazione usati dal team per la scrittura e la modifica.

È possibile utilizzare uno spazio di codice nel browser, contribuendo in VS Code ospitato su Internet. Se Visual Studio Code è installato in locale, è anche possibile connettersi allo spazio di codice.

Strumenti disponibili

Quando si usa uno spazio di codice per contribuire alla documentazione di PowerShell, l'editor include questi strumenti già disponibili:

  • Markdownlint per verificare la sintassi markdown.
  • cSpell per controllare l'ortografia.
  • Vale per controllare il tuo testo.
  • Learn Authoring Pack per l'inserimento di sintassi specifica della piattaforma, l'anteprima del contributo e altro ancora.
  • Estensione Reflow Markdown per riformattare il tuo Markdown secondo le necessità, rendendo più facile la lettura e la modifica.
  • L'estensione Formattatore di Tabelle per rendere le tue tabelle più leggibili senza dover allineare manualmente le colonne.
  • Estensione change-case per convertire il maiuscolo e minuscolo delle intestazioni e della prosa.
  • Estensione GitLens per la revisione delle modifiche cronologiche dei file.
  • L'estensione PowerShell per l'interazione e la creazione di esempi in PowerShell.
  • Il tracker Gremlins per Visual Studio Code per trovare i caratteri problematici nel Markdown.

Costo

GitHub Codespaces può essere usato gratuitamente fino a 120 ore di core al mese. L'utilizzo mensile viene calcolato in tutti i repository, non solo nella documentazione.

Per altre informazioni sui prezzi, vedere Informazioni sulla fatturazione per GitHub Codespaces.

Suggerimento

Se si ha familiarità con i contenitori e Docker, è possibile ottenere la stessa esperienza usando il devcontainer definito per i repository di documentazione di PowerShell. Non sono previsti costi associati all'uso di devcontainers. Per maggiori informazioni, consulta l'esercitazione sui contenitori di sviluppo.

Creazione di GitHub Codespace

Per creare GitHub Codespace per contribuire alla documentazione di PowerShell, seguire questa procedura:

  1. Aprire https://github.com/codespaces nel browser.
  2. Selezionare il pulsante "Nuovo spazio di codice" in alto a destra nella pagina.
  3. Nella pagina "Crea un nuovo spazio di codice" selezionare il pulsante "Seleziona un repository" e digitare il nome del repository a cui si vuole contribuire, ad esempio MicrosoftDocs/PowerShell-Docs.
  4. Lasciare predefinite tutte le altre impostazioni.
  5. Selezionare il pulsante "Crea spazio di codice".

Dopo aver seguito questi passaggi, GitHub crea un nuovo spazio di codice per tale repository e lo configura automaticamente. Quando lo spazio di codice è pronto, la pagina viene aggiornata e viene visualizzata l'interfaccia utente dell'editor Web per lo spazio di codice. L'interfaccia utente è basata su VS Code e funziona allo stesso modo.

Apertura del tuo GitHub Codespace

Per aprire GitHub Codespace nel browser, seguire questa procedura:

  1. Aprire https://github.com/codespaces nel browser.
  2. La pagina elenca i tuoi spazi di codice. Trovare lo spazio di codice creato per il repository a cui si vuole contribuire e selezionarlo.

Dopo aver selezionato lo spazio di codice, GitHub lo apre nella stessa finestra. Da qui si è pronti per contribuire.

Per aprire GitHub Codespace in VS Code, seguire la procedura descritta in Uso di GitHub Codespaces in Visual Studio Code.

Creazione di contenuti nel tuo GitHub Codespace

Dopo aver aperto GitHub Codespace nel browser o vs Code, contribuire alla documentazione segue lo stesso processo.

Nella parte restante di questo articolo viene descritta una selezione di attività che è possibile eseguire in GitHub Codespace durante la scrittura o la modifica del contributo.

Quando si vuole trasformare un collegamento inline, ad esempio [some text](destination.md), in un collegamento di riferimento come [some text][01], selezionare la destinazione del collegamento nell'editor. È quindi possibile:

  1. Fare clic con il pulsante destro del mouse sulla destinazione del collegamento e scegliere "Refactoring..." nel menu di scelta rapida.
  2. Premere Ctrl+Shift+R.

Entrambe le azioni generano il menu contestuale di refactoring. Per sostituire (destination.md) nel collegamento con [def], selezionare Estrai per definizione del collegamento nel menu di scelta rapida. È possibile rinominare la definizione digitando un nome in .

Per la documentazione di PowerShell, vengono usate definizioni di collegamento di riferimento numerico a due cifre, ad esempio [01] o [31]. Usare solo definizioni di collegamento di riferimento negli articoli e nella documentazione concettuale. Non usare definizioni di collegamento di riferimento nella documentazione di riferimento sui cmdlet.

Correggere le violazioni dello stile di prosa

Quando si esamina un articolo nello spazio di codice, Vale controlla automaticamente l'articolo quando viene aperto per la prima volta e ogni volta che lo si salva. Se Vale rileva violazioni dello stile, le evidenzia nel documento con linee ondulate colorate.

Passare il puntatore del mouse su una violazione per visualizzare altre informazioni su di esso.

Per aprire una pagina Web che spiega la regola, selezionare il nome della regola nelle informazioni al passaggio del mouse. Per aprire la regola ed esaminarne l'implementazione, selezionare il nome file della regola (che termina con .yml).

Se la regola supporta una correzione rapida, è possibile selezionare "Correzione rapida..." nelle informazioni al passaggio del mouse per la violazione e applicare una delle correzioni suggerite selezionandola dal menu di scelta rapida. È anche possibile premere CTRL+. Quando il cursore si trova su un problema evidenziato per applicare una correzione rapida se la regola lo supporta.

Se la regola non supporta correzioni rapide, leggere il messaggio della regola e correggerlo, se possibile. Se non si è certi di come risolverlo, gli editor possono farti un suggerimento durante la revisione del PR.

Risolvere i problemi di sintassi

Quando si esamina un articolo nello spazio di codice, Markdownlint controlla automaticamente l'articolo quando viene aperto e durante la digitazione. Se Markdownlint rileva eventuali problemi di sintassi, li evidenzia nel documento con squiggle colorate.

Passare il puntatore del mouse su una violazione per visualizzare altre informazioni su di esso. Per aprire una pagina Web che spiega la regola, selezionare l'ID della regola nelle informazioni al passaggio del mouse.

Se la regola supporta una correzione rapida, è possibile selezionare "Correzione rapida..." nelle informazioni al passaggio del mouse per la violazione e applicare una delle correzioni suggerite selezionandola dal menu di scelta rapida. È anche possibile premere CTRL+. Quando il cursore si trova su un problema evidenziato per applicare una correzione rapida se la regola lo supporta.

Se la regola non supporta correzioni rapide, leggere il messaggio della regola e correggerlo, se possibile. Se non si è certi di come risolverlo, gli editor possono farti un suggerimento durante la revisione del PR.

È anche possibile applicare correzioni a tutte le violazioni della sintassi in un articolo. A tale scopo, aprire il riquadro comandi e digitare Fix all supported markdownlint violations in the document. Durante la digitazione, il riquadro comandi filtra i comandi disponibili. Selezionare il comando "Correzione di tutte le violazioni markdownlint supportate nel documento". Quando si esegue questa operazione, Markdownlint aggiorna il documento per risolvere eventuali violazioni per cui ha una correzione rapida.

Formattare una tabella

Per formattare una tabella Markdown, posizionare il cursore all'interno o sulla tabella nel Markdown. Aprire il riquadro comandi e cercare il Table: Format Current comando . Quando si seleziona tale comando, aggiorna il Markdown per la tabella, allineandola e riempiendola per migliorare la leggibilità.

Converte una tabella definita come segue:

| foo | bar | baz |
|:--:|:--|-:|
| a | b | c |

In questo modo:

|  foo  | bar  | baz  |
| :---: | :--- | ---: |
|   a   | b    |    c |

Inserire un avviso

La documentazione usa avvisi per rendere le informazioni più rilevanti per un lettore.

Per inserire un avviso, è possibile aprire il riquadro comandi e cercare il Learn: Alert comando. Quando si seleziona tale comando, viene aperto un menu di scelta rapida. Selezionare il tipo di avviso da aggiungere. Quando esegui questa operazione, il comando inserisce il Markdown dell'avviso dove si trova il cursore nel documento.

Usare la combinazione di maiuscole e minuscole di un titolo

Per convertire il formato di un titolo, selezionare il testo dell'intestazione, eccetto i simboli iniziali # , che impostano il livello di intestazione. Quando il testo è evidenziato, aprire il riquadro comandi e cercare il Change case sentence comando. Quando selezioni quel comando, converte il formato delle lettere del testo evidenziato.

È anche possibile usare i comandi per modificare l'uso di maiuscole e minuscole per qualsiasi testo nel documento.

Apri la Palette dei comandi

È possibile usare il riquadro comandi di VS Code per eseguire molti comandi utili.

Per aprire il riquadro comandi nell'interfaccia utente, selezionare "Visualizza" nella barra dei menu in alto. Selezionare quindi "Riquadro comandi..." nel menu di scelta rapida.

Per aprire il riquadro comandi con la tastiera, premere la combinazione di tasti per il sistema operativo:

  • Windows e Linux: CTRL+MAIUSC+P
  • macOS: CMD+SHIFT+P

Visualizzare in anteprima il contributo

Per visualizzare in anteprima il contributo, aprire il riquadro comandi e cercare il Markdown: Open Preview comando . Quando si seleziona tale comando, VS Code apre un'anteprima del documento attivo. Lo stile dell'anteprima corrisponde alla piattaforma Learn.

Annotazioni

I collegamenti relativi al sito e tra riferimenti non funzionano nell'anteprima.

Riarrangiare il contenuto

Per limitare le lunghezze di riga per un paragrafo in un documento, posizionare il cursore sul paragrafo. Aprire quindi il riquadro comandi e cercare il Reflow Markdown comando . Quando si seleziona il comando, aggiorna le lunghezze della riga del paragrafo corrente alla lunghezza configurata. Per i repository, tale lunghezza è di 99 caratteri.

Quando si usa questo comando per i blocchi di citazione, assicurarsi che il paragrafo nel blocco di citazione di cui si sta rifacendo il flusso sia racchiuso tra righe vuote. In caso contrario, il comando riorganizza tutti i paragrafi insieme.

Attenzione

Non usare questo comando quando si modificano gli articoli. Le righe di tali documenti non devono contenere più di 80 caratteri. Attualmente non esiste alcun modo per configurare in un repository lunghezze di riga diverse in base a cartella o nome del file, quindi il reflow non funziona per i documenti degli articoli.

Esaminare tutti i problemi in un documento

Per esaminare tutte le violazioni della sintassi e della regola di stile in un documento, aprire la visualizzazione Problemi.

Per aprire La visualizzazione dei problemi nell'interfaccia utente, selezionare "Visualizza" nella barra dei menu in alto. Selezionare quindi "Problemi" nel menu di scelta rapida.

Per aprire la visualizzazione Dei problemi con la tastiera, premere la combinazione di tasti per il sistema operativo:

  • Windows e Linux: CTRL+MAIUSC+M
  • macOS: Cmd+Shift+M

Nella visualizzazione Problemi vengono visualizzati tutti gli errori, gli avvisi e i suggerimenti per il documento aperto. Selezionare un problema per scorrere verso di esso nel documento.

È possibile filtrare i problemi in base al tipo o alla corrispondenza di testo.

Aggiornamento dei metadati ms.date

Per aggiornare i ms.date metadati per un articolo, aprire il riquadro comandi e cercare il Learn: Update "ms.date" Metadata Value comando. Quando si seleziona il comando, aggiorna i metadati alla data corrente.

Risorse aggiuntive

Le attività e i comandi descritti in questo articolo non riguardano tutte le operazioni che è possibile eseguire con VS Code o le estensioni installate.

Per altre informazioni sull'uso di VS Code, vedere gli articoli seguenti:

Per altre informazioni sulle estensioni installate, vedere la relativa documentazione:

  • Last updated on