Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Questo documento illustra il processo per contribuire agli articoli e agli esempi di codice ospitati nel sito della documentazione di IIS. I contributi possono essere correzioni tipografiche o complesse come nuovi articoli.
Come effettuare una semplice correzione o suggerimento
Gli articoli vengono archiviati nel repository come file Markdown. È possibile apportare piccole modifiche al contenuto di un file Markdown nel browser selezionando il collegamento Modifica nell'angolo superiore destro della finestra del browser. Nelle finestre del browser strette sarà necessario espandere la barra delle opzioni per visualizzare il collegamento Modifica . Seguire le istruzioni per creare una richiesta pull.Follow the directions to create a pull request (PR). La richiesta pull verrà esaminata e accettata o verranno suggerite modifiche.
Come effettuare un invio più complesso
È necessaria una conoscenza di base di Git e GitHub.com.
- Aprire un problema che descrive le operazioni da eseguire, ad esempio modificare un articolo esistente o crearne uno nuovo. Attendere l'approvazione del team prima di investire molto tempo.
- Forkare il repository iis-docs e creare un branch per le tue modifiche.
- Inviare una richiesta pull al master con le modifiche.
- Se alla tua richiesta pull è stata assegnata l'etichetta "cla-required", completa l'accordo di licenza dei contributi (CLA)
- Rispondere al feedback delle PR.
Per un esempio in cui questo processo ha portato alla pubblicazione di un nuovo articolo, vedere il problema 67 e la richiesta pull 798 nel repository .NET. Il nuovo articolo è Documentare il tuo codice.
Sintassi Markdown
Gli articoli sono scritti in DocFx-flavored Markdown, che è un superset di GitHub-flavored Markdown (GFM). Per esempi di sintassi DFM per le funzionalità dell'interfaccia utente comunemente usate nella documentazione, vedere Metadati e modello Markdown nella guida di stile del repository .NET.
Convenzioni della struttura delle cartelle
Per ogni file Markdown potrebbe essere presente una cartella per le immagini e una cartella per il codice di esempio. Ad esempio, se l'articolo è /extensions/advanced-logging-module/advanced-logging-for-iis-client-logging.md, le immagini si trovano in extensions/advanced-logging-module/advanced-logging-for-iis-client-loggin/_static e i file di progetto dell'applicazione di esempio si trovano in extensions/advanced-logging-module/advanced-logging-for-iis-client-loggin/samples. Il rendering di un'immagine nel file /advanced-logging-for-iis-client-logging.md viene eseguito dal markdown seguente.
Tutte le immagini devono avere testo alternativo.
I nomi di file markdown e i nomi dei file di immagine devono essere tutti minuscoli.
Frammenti di codice
Gli articoli contengono spesso frammenti di codice per illustrare i punti. DFM consente di copiare il codice nel file Markdown o di fare riferimento a un file di codice separato. È preferibile usare file di codice separati quando possibile, per ridurre al minimo la probabilità di errori nel codice. I file di codice devono essere archiviati nel repository usando la struttura di cartelle descritta in precedenza per i progetti di esempio.
Ecco alcuni esempi di sintassi del frammento di codice DFM che verrebbe usato in un file configuration.md .
Per eseguire il rendering di un intero file di codice come frammento di codice:
[!code-csharp[Main](configuration/sample/Program.cs)]
Per eseguire il rendering di una parte di un file come frammento di codice usando i numeri di riga:
[!code-csharp[Main](configuration/sample/Program.cs?range=1-10,20,30,40-50]
[!code-html[Main](configuration/sample/Views/Home/Index.cshtml?range=1-10,20,30,40-50]
Per i frammenti di codice C#, è possibile fare riferimento a un'area C#. Quando possibile, usare aree anziché numeri di riga, perché i numeri di riga in un file di codice tendono a cambiare e uscire dalla sincronizzazione con i riferimenti al numero di riga in Markdown. Le regioni C# possono essere annidate e, se si fa riferimento alla regione esterna, le direttive interne #region e #endregion non vengono renderizzate in un frammento di codice.
Per eseguire il rendering di un'area C# denominata "snippet_Example":
[!code-csharp[Main](configuration/sample/Program.cs?name=snippet_Example)]
Per evidenziare le righe selezionate in un frammento di codice sottoposto a rendering (in genere viene eseguito il rendering come colore di sfondo giallo):
[!code-csharp[Main](configuration/sample/Program.cs?name=snippet_Example&highlight=1-3,10,20-25)]
[!code-csharp[Main](configuration/sample/Program.cs?range=10-20&highlight=1-3]
[!code-html[Main](configuration/sample/Views/Home/Index.cshtml?range=10-20&highlight=1-3]
[!code-javascript[Main](configuration/sample/Project.json?range=10-20&highlight=1-3]
Testare le modifiche con DocFX
Testare le modifiche con lo strumento da riga di comando DocFX, che crea una versione ospitata localmente del sito. DocFX non visualizza stili o estensioni di sito creati per learn.microsoft.com.
DocFX richiede .NET Framework in Windows o Mono per Linux o macOS.
Istruzioni di Windows
Scaricare e decomprimere docfx.zip dalle versioni di DocFX.
Aggiungere DocFX al percorso.
In una finestra della riga di comando passare alla cartella appropriata contenente il file docfx.json (iis-docs/iis) ed eseguire il comando seguente:
docfx -t default --serveIn un browser, naviga verso
http://localhost:8080.
Istruzioni Mono
Installare Mono tramite Homebrew -
brew install mono.Scaricare la versione più recente di DocFX.
Estrarre in
\bin\docfx.Creare un alias per docfx:
function docfx { mono $HOME/bin/docfx/docfx.exe } function docfx-serve { mono $HOME/bin/docfx/docfx.exe serve _site }Eseguire docfx nella
iis-docs\iisdirectory per compilare il sito e docfx-serve per visualizzare il sito all'indirizzohttp://localhost:8080.
Voce e tono
L'obiettivo è scrivere documentazione facilmente comprensibile per il pubblico più ampio possibile. A tale scopo, abbiamo stabilito linee guida per lo stile di scrittura che chiediamo ai nostri collaboratori di seguire. Per altre informazioni, vedere Linee guida per la voce e il tono nel repository .NET.
Reindirizzamenti
Se si elimina un articolo, si modifica il nome del file o lo si sposta in una cartella diversa, creare un reindirizzamento in modo che gli utenti che hanno aggiunto un segnalibro all'articolo non ottengano 404. Aggiungere reindirizzamenti al file di reindirizzamento principale.