Ανάγνωση στα Αγγλικά

Κοινή χρήση μέσω


Χρήση συνδέσεων στην τεκμηρίωση

Αυτό το άρθρο περιγράφει τον τρόπο χρήσης υπερ-συνδέσεων από σελίδες που φιλοξενούνται στο Microsoft Learn. Μπορείτε να προσθέσετε εύκολα συνδέσεις στο Markdown χρησιμοποιώντας κάποιους κυμαινόμενους κανόνες. Οι συνδέσεις κατευθύνουν τους χρήστες σε περιεχόμενο στην ίδια σελίδα, σε άλλες παρακείμενες σελίδες ή σε εξωτερικές τοποθεσίες και διευθύνσεις URL.

Το παρασκήνιο του Microsoft Learn χρησιμοποιεί τις υπηρεσίες Open Publishing Services (OPS), οι οποίες υποστηρίζουν ανάλυση Markdown συμβατή με CommonMark μέσω του μηχανισμού ανάλυσης Markdig . Αυτός ο τύπος Markdown είναι κυρίως συμβατός με το GitHub Flavored Markdown (GFM), καθώς τα περισσότερα έγγραφα αποθηκεύονται στο GitHub και μπορείτε να τα επεξεργαστείτε εκεί. Επιπλέον λειτουργικότητα προστίθεται μέσω των επεκτάσεων Markdown.

Σημαντικό

Όλες οι συνδέσεις πρέπει να είναι ασφαλείς (https έναντι http) κάθε φορά που τις υποστηρίζει ο προορισμός.

Οι λέξεις που περιλαμβάνονται στο κείμενο σύνδεσης θα πρέπει να είναι φιλικές. Με άλλα λόγια, θα πρέπει να είναι κανονικές αγγλικές λέξεις ή ο τίτλος της σελίδας στην οποία συνδέεστε.

Σημαντικό

Μην χρησιμοποιείτε το "κλικ εδώ" ως κείμενο σύνδεσης. Δεν ενδείκνυται για τη βελτιστοποίηση μηχανισμού αναζήτησης και δεν περιγράφει επαρκώς τον προορισμό.

Σωστό:

  • For more information, see the [contributor guide index](https://github.com/Azure/azure-content/blob/master/contributor-guide/contributor-guide-index.md).

  • For more details, see the [SET TRANSACTION ISOLATION LEVEL](/sql/t-sql/statements/set-transaction-isolation-level-transact-sql) reference.

Λάθος:

  • For more details, see [https://msdn.microsoft.com/library/ms173763.aspx](https://msdn.microsoft.com/library/ms173763.aspx).

  • For more information, click [here](https://github.com/Azure/azure-content/blob/master/contributor-guide/contributor-guide-index.md).

Συνδέσεις από ένα άρθρο σε κάποιο άλλο

Υπάρχουν δύο τύποι υπερ-συνδέσεων που υποστηρίζονται από το σύστημα δημοσίευσης: οι διευθύνσεις URL και οι συνδέσεις αρχείων.

Μια σύνδεση διεύθυνσης URL μπορεί να είναι μια διαδρομή διεύθυνσης URL που είναι σχετική με τη ρίζα του https://learn.microsoft.comή μια απόλυτη διεύθυνση URL που περιλαμβάνει την πλήρη σύνταξη διεύθυνσης URL (για παράδειγμα, https://github.com/MicrosoftDocs/PowerShell-Docs).

  • Χρησιμοποιήστε τις συνδέσεις διεύθυνσης URL κατά τη σύνδεση σε περιεχόμενο εκτός του τρέχοντος συνόλου εγγράφων ή μεταξύ των αυτοματοποιημένων αναφορών και εννοιολογικών άρθρων εντός του συνόλου εγγράφων.
  • Ο απλούστερος τρόπος για να δημιουργήσετε μια σχετική σύνδεση είναι να αντιγράψετε τη διεύθυνση URL από το πρόγραμμα περιήγησής σας και, στη συνέχεια, να καταργήσετε το https://learn.microsoft.com/en-us από την τιμή που επικολλάτε στο Markdown.
  • Μην συμπεριλάβετε τοπικές ρυθμίσεις σε διευθύνσεις URL για ιδιότητες της Microsoft (για παράδειγμα, καταργήστε /en-us από τη διεύθυνση URL).

Μια σύνδεση αρχείου χρησιμοποιείται για τη σύνδεση από ένα άρθρο στο άλλο εντός του συνόλου εγγράφων.

  • Όλες οι διαδρομές αρχείων χρησιμοποιούν χαρακτήρες καθέτου (/) αντί για χαρακτήρες ανάστροφης καθέτου.

  • Ένα άρθρο συνδέεται σε άλλο άρθρο στον ίδιο κατάλογο:

    [link text](article-name.md)

  • Ένα άρθρο συνδέεται σε ένα άρθρο στον γονικό κατάλογο του τρέχοντος καταλόγου:

    [link text](../article-name.md)

  • Ένα άρθρο συνδέεται σε ένα άρθρο σε έναν υποκατάλογο του τρέχοντος καταλόγου:

    [link text](directory/article-name.md)

  • Ένα άρθρο συνδέεται σε ένα άρθρο σε έναν υποκατάλογο του γονικού καταλόγου του τρέχοντος καταλόγου:

    [link text](../directory/article-name.md)

  • Ορισμένα άρθρα αποτελούνται από ένα .yml αρχείο και .md , όπου το .yml αρχείο περιέχει μετα-δεδομένα και το .md περιέχει το περιεχόμενο. Σε αυτή την περίπτωση, σύνδεση προς το .yml αρχείο:

    [link text](../directory/article-name.yml) (όχι [link text](../directory/article-name-content.md))

Σημείωση

Κανένα από τα προηγούμενα παραδείγματα δεν χρησιμοποιεί το ~/ ως τμήμα της σύνδεσης. Για να συνδεθείτε σε μια απόλυτη διαδρομή που ξεκινά στη ρίζα του αποθετηρίου, ξεκινήστε τη σύνδεση με /. Η συμπερίληψη του ~/ δημιουργεί μη έγκυρες συνδέσεις κατά την περιήγηση σε αποθετήρια δεδομένων προέλευσης στο GitHub. Η διαδρομή που αρχίζει με το / επιλύεται σωστά.

Το περιεχόμενο που δημοσιεύεται στο Microsoft Learn έχει την ακόλουθη δομή διεύθυνσης URL:

https://learn.microsoft.com/<locale>/<product-service>/[<feature-service>]/[<subfolder>]/<topic>[?view=<view-name>]

Παραδείγματα:

https://learn.microsoft.com/azure/load-balancer/load-balancer-overview

https://learn.microsoft.com/powershell/azure/overview?view=azurermps-5.1.1
  • <locale> - προσδιορίζει τη γλώσσα του άρθρου (παράδειγμα: en-us ή de-de)
  • <product-service> - το όνομα του προϊόντος ή της υπηρεσίας (παράδειγμα: powershell, dotnet ή azure)
  • [<feature-service>] - (προαιρετικό) το όνομα της δυνατότητας ή της δευτερεύουσας υπηρεσίας του προϊόντος (παράδειγμα: csharp ή εξισορροπητής φορτίου)
  • [<subfolder>] - (προαιρετικό) το όνομα ενός υποφακέλου μέσα σε μια δυνατότητα
  • <topic> - το όνομα του αρχείου άρθρου για το θέμα (παράδειγμα: επισκόπηση-εξισορροπητή-φορτίου ή επισκόπηση)
  • [?view=\<view-name>] - (προαιρετικό) το όνομα προβολής που χρησιμοποιείται από τον επιλογέα έκδοσης για περιεχόμενο που διαθέτει πολλές διαθέσιμες εκδόσεις (παράδειγμα: azps-3.5.0)

Φιλοδώρημα

Στις περισσότερες περιπτώσεις, τα άρθρα στο ίδιο σύνολο εγγράφων έχουν το ίδιο τμήμα URL <product-service>. Για παράδειγμα:

  • Ίδιο σύνολο εγγράφων:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/dotnet/framework/install
  • Διαφορετικό σύνολο εγγράφων:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/visualstudio/whats-new

Για μια σύνδεση σελιδοδείκτη για μια επικεφαλίδα στο τρέχον άρθρο, χρησιμοποιήστε ένα σύμβολο δίεσης, ακολουθούμενο από τις λέξεις της κεφαλίδας με πεζά γράμματα. Καταργήστε τα σημεία στίξης από την κεφαλίδα και αντικαταστήστε τα κενά διαστήματα με παύλες:

[Managed Disks](#managed-disks)

Για να δημιουργήσετε μια σύνδεση επικεφαλίδας σελιδοδείκτη σε ένα άλλο άρθρο, χρησιμοποιήστε τη σύνδεση που σχετίζεται με αρχείο ή τη σύνδεση που σχετίζεται με τοποθεσία καθώς και ένα σύμβολο δίεσης, ακολουθούμενη από τις λέξεις της κεφαλίδας. Καταργήστε τα σημεία στίξης από την κεφαλίδα και αντικαταστήστε τα κενά διαστήματα με παύλες:

[Managed Disks](../../linux/overview.md#managed-disks)

Μπορείτε επίσης να αντιγράψετε τη σύνδεση σελιδοδείκτη από τη διεύθυνση URL. Για να βρείτε τη διεύθυνση URL, τοποθετήστε τον δείκτη του ποντικιού πάνω από τη γραμμή επικεφαλίδας στο Microsoft Learn. Θα πρέπει να δείτε να εμφανίζεται ένα εικονίδιο σύνδεσης:

Εικονίδιο σύνδεσης στην επικεφαλίδα του άρθρου

Κάντε κλικ στο εικονίδιο σύνδεσης και, στη συνέχεια, αντιγράψτε το κείμενο αγκύρωσης σελιδοδείκτη από τη διεύθυνση URL (δηλαδή, το τμήμα μετά τον κωδικό κατακερματισμού).

Σημείωση

Η επέκταση Learn Markdown διαθέτει επίσης εργαλεία για τη δημιουργία συνδέσεων.

Η προσθήκη ρητών συνδέσεων αγκύρωσης που χρησιμοποιούν την ετικέτα HTML <a> δεν απαιτούνται και δεν συνιστώνται εκτός από κεντρικές σελίδες και σελίδες προορισμού. Αντί για αυτό, χρησιμοποιήστε τους σελιδοδείκτες που δημιουργούνται αυτόματα, όπως περιγράφεται στις συνδέσεις σελιδοδεικτών. Για κεντρικές και αρχικές σελίδες, δηλώστε τις αγκυρώσεις ως εξής:

## <a id="anchortext" />Header text

ή

## <a name="anchortext" />Header text

Και τα παρακάτω για σύνδεση με την αγκύρωση:

To go to a section on the same page:
[text](#anchortext)

To go to a section on another page.
[text](filename.md#anchortext)

Σημείωση

Το κείμενο αγκύρωσης πρέπει να είναι πάντα με πεζούς χαρακτήρες και να μην περιέχει κενά διαστήματα.

Οι συνδέσεις XRef είναι ο προτεινόμενος τρόπος σύνδεσης με τα API, καθώς διευκολύνουν την προσαρμογή του κειμένου σύνδεσης. Επιπλέον, επικυρώνονται κατά τον χρόνο δόμησης και, εάν η διεύθυνση URL για την αναφορά API αλλάξει, η σύνδεση θα εξακολουθήσει να λειτουργεί. Για σύνδεση με σελίδες αναφοράς API που δημιουργούνται αυτόματα στο τρέχον σύνολο εγγράφων ή σε άλλα σύνολα εγγράφων, χρησιμοποιήστε συνδέσεις XRef με το μοναδικό αναγνωριστικό (UID) του τύπου του μέλους.

Φιλοδώρημα

Η επέκταση Βοηθητική εφαρμογή σύνδεσης αναφοράς API για κώδικα VS καθιστά εξαιρετικά εύκολη την εισαγωγή συνδέσεων Xref .NET API σε αρχεία Markdown και XML.

Ελέγξτε αν το API στο οποίο θέλετε να συνδεθείτε έχει δημοσιευτεί στο Microsoft Learn, πληκτρολογώντας όλο ή μέρος του πλήρους ονόματός του στο πρόγραμμα περιήγησης .NET API ή στο πλαίσιο αναζήτησης των Windows UWP. Εάν δεν βλέπετε να εμφανίζονται αποτελέσματα, ο τύπος δεν βρίσκεται ακόμα στο Microsoft Learn.

Μπορείτε να χρησιμοποιήσετε κάποιο από τα παρακάτω είδη σύνταξης:

  • Αυτόματες συνδέσεις:

    <xref:UID>
    <xref:UID?displayProperty=nameWithType>
    

    Από προεπιλογή, το κείμενο σύνδεσης εμφανίζει μόνο το όνομα μέλους ή τύπου. Η προαιρετική παράμετρος ερωτήματος displayProperty=nameWithType παράγει πλήρως προσδιορισμένο κείμενο σύνδεσης, δηλαδή, namespace.type για τύπους και type.member για τα μέλη τύπου, συμπεριλαμβανομένων των μελών τύπου απαρίθμησης.

  • Συνδέσεις στυλ Markdown:

    [link text](xref:UID)
    

    Χρησιμοποιήστε συνδέσεις στυλ Markdown για το XRef όταν θέλετε να προσαρμόσετε το κείμενο σύνδεσης που εμφανίζεται.

Παραδείγματα:

  • <xref:System.String> εμφανίζεται ως String

  • <xref:System.String?displayProperty=nameWithType> εμφανίζεται ως System.String

  • [Κλάση συμβολοσειράς] (xref:System.String) Το εμφανίζεται ως String class.

Η παράμετρος ερωτήματος displayProperty=fullName λειτουργεί με τον ίδιο τρόπο όπως το displayProperty=nameWithType για τις κλάσεις. Αυτό σημαίνει ότι το κείμενο σύνδεσης μετατρέπεται σε namespace.classname. Ωστόσο, για τα μέλη, το κείμενο σύνδεσης εμφανίζεται ως namespace.classname.membername, το οποίο μπορεί να είναι ανεπιθύμητο.

Σημείωση

Τα UID κάνουν διάκριση πεζών-κεφαλαίων. Για παράδειγμα, <xref:System.Object> το επιλύθηκε σωστά, αλλά <xref:system.object> το όχι.

Προσδιορισμός του UID

Το UID είναι συνήθως το πλήρως προσδιορισμένο όνομα κλάσης ή μέλους. Για να προσδιορίσετε το UID, κάντε δεξί κλικ στη σελίδα του Microsoft Learn για έναν τύπο ή μέλος, επιλέξτε Προβολή προέλευσης και, στη συνέχεια, αντιγράψτε την τιμή περιεχομένου για το ms.assetid.

ms.assetid στην προέλευση για την ιστοσελίδα

Κωδικοποίηση ποσοστού διευθύνσεων URL

Οι ειδικοί χαρακτήρες στο UID πρέπει να έχουν ποσοστιαία κωδικοποίηση ως εξής:

Χαρακτήρας Κωδικοποίηση HTML
* *

Παράδειγμα κωδικοποίησης:

  • Το System.Exception.#ctor κωδικοποιείται ως System.Exception.%23ctor

Γενικοί τύποι

Οι γενικοί τύποι είναι τύποι όπως το System.Collections.Generic.List<T>. Αν μεταβείτε σε αυτόν τον τύπο στο πρόγραμμα περιήγησης API του .NET και δείτε τη διεύθυνση URL του, θα δείτε ότι το <T> έχει γραφτεί ως -1 στη διεύθυνση URL, η οποία αντιπροσωπεύει στην πραγματικότητα το `1:

https://learn.microsoft.com/dotnet/api/system.collections.generic.list-1

Μέθοδοι

Για να δημιουργήσετε μια σύνδεση προς μια μέθοδο, μπορείτε είτε να συνδεθείτε στη σελίδα γενικής μεθόδου, προσθέτοντας έναν αστερίσκο (*) μετά το όνομα της μεθόδου, είτε σε μια συγκεκριμένη υπερφόρτωση. Για παράδειγμα, χρησιμοποιήστε τη γενική σελίδα όταν θέλετε να συνδεθείτε με τη μέθοδο <xref:System.Object.Equals*?displayProperty=nameWithType> χωρίς συγκεκριμένους τύπους παραμέτρων. Για παράδειγμα:

Συνδέσεις <xref:System.Object.Equals*?displayProperty=nameWithType> στο Object.Equals

Για να δημιουργήσετε μια σύνδεση σε μια συγκεκριμένη υπερφόρτωση, προσθέστε την παρένθεση μετά το όνομα της μεθόδου και συμπεριλάβετε το πλήρες όνομα του τύπου κάθε παραμέτρου. Μην τοποθετείτε χαρακτήρα διαστήματος μεταξύ των ονομάτων τύπων, διαφορετικά η σύνδεση δεν θα λειτουργήσει. Για παράδειγμα:

Συνδέσεις <xref:System.Object.Equals(System.Object,System.Object)?displayProperty=nameWithType> στο Object.Equals(Object, Object)

Επειδή τα αρχεία συμπερίληψης βρίσκονται σε άλλον κατάλογο, πρέπει να χρησιμοποιήσετε μεγαλύτερες σχετικές διαδρομές. Για σύνδεση προς ένα άρθρο από ένα αρχείο συμπερίληψης, χρησιμοποιήστε αυτήν τη μορφή:

[link text](../articles/folder/article-name.md)

Φιλοδώρημα

Η επέκταση Learn Authoring Pack για το Visual Studio Code σάς βοηθά να εισάγετε σωστά σχετικές συνδέσεις και σελιδοδείκτες χωρίς την ποσότητα της εξεύρεσης των διαδρομών.

Ο επιλογέας είναι ένα στοιχείο πλοήγησης που εμφανίζεται σε ένα άρθρο εγγράφων ως αναπτυσσόμενη λίστα. Όταν ο αναγνώστης επιλέγει μια τιμή στην αναπτυσσόμενη λίστα, το πρόγραμμα περιήγησης ανοίγει το επιλεγμένο άρθρο. Συνήθως, η λίστα του επιλογέα περιέχει συνδέσεις για τα πιο σχετικά άρθρα, όπως, για παράδειγμα, το ίδιο θεματικό πεδίο σε πολλές γλώσσες προγραμματισμού ή μια σειρά άρθρων που σχετίζονται περισσότερο.

Εάν έχετε επιλογείς που είναι ενσωματωμένοι σε μια συμπερίληψη, χρησιμοποιήστε την ακόλουθη δομή σύνδεσης:

> [AZURE.SELECTOR-LIST (Dropdown1 | Dropdown2 )]
- [(Text1 | Example1 )](../articles/folder/article-name1.md)
- [(Text1 | Example2 )](../articles/folder/article-name2.md)
- [(Text2 | Example3 )](../articles/folder/article-name3.md)
- [(Text2 | Example4 )](../articles/folder/article-name4.md)

Μπορείτε να χρησιμοποιήσετε συνδέσεις στυλ αναφοράς, για να κάνετε πιο ευανάγνωστο το περιεχόμενο προέλευσης που διαθέτετε. Οι συνδέσεις στυλ αναφοράς αντικαθιστούν τη σύνταξη ενσωματωμένης σύνδεσης με απλοποιημένη σύνταξη που σας επιτρέπει να μετακινήσετε τις μεγάλες διευθύνσεις URL στο τέλος του άρθρου. Ακολουθεί το παράδειγμα Daring Fireball:

Ενσωματωμένο κείμενο:

I get 10 times more traffic from [Google][1] than from [Yahoo][2] or [MSN][3].

Η σύνδεση αναφέρεται στο τέλος του άρθρου:

<!--Reference links in article-->
[1]: http://google.com/
[2]: http://search.yahoo.com/
[3]: http://search.msn.com/

Βεβαιωθείτε ότι έχετε συμπεριλάβει το διάστημα μετά την άνω και κάτω τελεία, πριν από τη σύνδεση. Όταν πραγματοποιείτε σύνδεση προς άλλα τεχνικά άρθρα, εάν ξεχάσετε να συμπεριλάβετε το διάστημα, η σύνδεση θα διακοπεί στο δημοσιευμένο άρθρο.

Για σύνδεση προς μια σελίδα σε άλλη ιδιότητα της Microsoft (όπως σελίδα τιμολόγησης, σελίδα SLA ή οτιδήποτε άλλο που δεν είναι άρθρο τεκμηρίωσης), χρησιμοποιήστε μια απόλυτη διεύθυνση URL, αλλά παραλείψτε τις τοπικές ρυθμίσεις. Ο στόχος στη συγκεκριμένη περίπτωση είναι οι συνδέσεις να λειτουργούν στο GitHub και στην τοποθεσία απόδοσης:

[link text](https://azure.microsoft.com/pricing/details/virtual-machines/)

Η βέλτιστη εμπειρία χρήστη ελαχιστοποιεί τη μετάβαση χρηστών σε άλλη τοποθεσία. Επομένως, τυχόν συνδέσεις προς τοποθεσίες τρίτων, τις οποίες μερικές φορές χρειαζόμαστε, θα βασίζονται σε αυτές τις πληροφορίες:

  • Υπευθυνότητα: Πραγματοποιήστε σύνδεση προς περιεχόμενο τρίτων, όταν πρόκειται να κοινοποιηθούν οι πληροφορίες τρίτων. Για παράδειγμα, δεν είναι αρμοδιότητα της Microsoft να ενημερώσει τους χρήστες πώς να χρησιμοποιούν τα εργαλεία για προγραμματιστές Android. Αυτό είναι ευθύνη της Google. Εάν χρειαστεί, μπορούμε να εξηγήσουμε τον τρόπο χρήσης των εργαλείων για προγραμματιστές Android με το Azure, αλλά η Google θα πρέπει να εξηγήσει πώς χρησιμοποιούνται τα εργαλεία της.
  • Έγκριση PM: Ζητήστε την έγκριση περιεχομένου τρίτων από τη Microsoft. Με τη σύνδεση σε αυτό το περιεχόμενο, λέμε κάτι σχετικά με το πόσο αξιόπιστο το θεωρούμε και τις υποχρεώσεις μας εφόσον οι χρήστες ακολουθούν τις οδηγίες.
  • Έλεγχοι ενημέρωσης: Βεβαιωθείτε ότι οι πληροφορίες τρίτων εξακολουθούν να είναι ενημερωμένες, σωστές και συναφείς, καθώς και ότι η σύνδεση δεν έχει αλλάξει.
  • Εκτός τοποθεσίας: Βεβαιωθείτε ότι οι χρήστες γνωρίζουν ότι μεταβαίνουν σε μια άλλη τοποθεσία. Εάν αυτό δεν γίνεται σαφές από το περιβάλλον, προσθέστε μια κατάλληλη φράση. Για παράδειγμα: "Στα προαπαιτούμενα περιλαμβάνονται τα Εργαλεία προγραμματισμού του Android, τα οποία μπορείτε να κατεβάσετε από την τοποθεσία του Android Studio."
  • Επόμενα βήματα: Μπορείτε, για παράδειγμα, να προσθέσετε μια σύνδεση προς ένα ιστολόγιο MVP σε μια ενότητα "Επόμενα βήματα". Και πάλι, απλώς βεβαιωθείτε ότι οι χρήστες κατανοούν ότι θα αποχωρήσουν από την τοποθεσία.
  • Νομικές πληροφορίες: Καλυπτόμαστε νομικά στην ενότητα Συνδέσεις προς τοποθεσίες τρίτων στο υποσέλιδα Όροι χρήσης κάθε microsoft.com σελίδα.