DevSite obsługuje kilka stylów powiadomień, które są wyświetlane jako pola z różnymi kolorami tła. Kolory tła są zdefiniowane wstępnie, a oprócz tego możesz tworzyć powiadomienia w języku HTML lub Markdown.
Dostępne typy powiadomień
Uwaga
HTML
<aside class="note">
<b>Note:</b> An ordinary note.
</aside>
Markdown
Note: An ordinary note.
Wskazówka
HTML
<aside class="tip">
<b>Tip:</b> An ordinary tip.
</aside>
Markdown
Tip: An ordinary tip.
Uwaga
HTML
<aside class="caution">
<b>Caution:</b> Suggests proceeding with caution.
</aside>
Markdown
Caution: Suggests proceeding with caution.
Ostrzeżenie
HTML
<aside class="warning">
<b>Warning:</b> Stronger than caution; it means "Don't do this."
</aside>
Markdown
Warning: Stronger than caution; it means "Don't do this."
Ważne
HTML
<aside class="special">
<b>Important:</b> Defines an important concept.
</aside>
Markdown
Important: Defines an important concept.
Ważny punkt
HTML
<aside class="key-point">
<b>Key Point:</b> Defines an important takeaway.
</aside>
Markdown
Key Point: Defines an important takeaway.
Kluczowy termin
HTML
<aside class="key-term">
<b>Key Term:</b> Defines important terminology.
</aside>
Markdown
Key Term: Defines important terminology.
Cel
HTML
<aside class="objective">
<b>Objective:</b> Defines the goal of a procedure.
</aside>
Markdown
Objective: Defines the goal of a procedure.
Sukces
HTML
<aside class="success">
<b>Success:</b> Describes a successful action or an error-free status.
Used only in interactive or dynamic content; don't use in ordinary
static pages.
</aside>
Markdown
Success: Describes a successful action or an error-free status. Used only
in interactive or dynamic content; don't use in ordinary static pages.
Beta
HTML
<aside class="beta">
<b>Beta:</b> A notice that describes a beta-release feature, which is
subject to change or removal in new minor versions of the product.
</aside>
Markdown
Beta: A notice that describes a beta-release feature, which is subject to
change or removal in new minor versions of the product.
Podgląd
HTML
<aside class="preview">
<b>Preview:</b> A note or tip for a feature preview.
</aside>
Markdown
Preview: A note or tip for a feature preview.
Dogfood
HTML
<aside class="dogfood">
<b>Dogfood:</b> A notice that applies only temporarily, during internal
dogfood testing. Remove all Dogfood notices before making a document
publicly visible.
</aside>
Markdown
Dogfood: A notice that applies only temporarily, during internal dogfood
testing. Remove all Dogfood notices before making a document publicly
visible.
Wycofano
HTML
<aside class="deprecated">
<b>Deprecated:</b> A note or tip for a deprecated feature, product, or
service.
</aside>
Markdown
Deprecated: A note or tip for a deprecated feature, product, or service.
Zastosowanie
Używanie kodu HTML
Zalecamy używanie tych klas z elementem HTML5 <aside>, ale możesz użyć innego elementu na poziomie bloku (np. <p>).
Klasy HTML określają kolor i ikonę powiadomienia, ale nie ustawiają automatycznie pogrubienia pierwszego słowa. Musisz je wpisać ręcznie, jak w przykładach. Teoretycznie możesz użyć innego słowa niż to, które odpowiada danej klasie, ale zalecamy używanie pierwszych słów wymienionych powyżej.
W starszych dokumentach zamiast class="note" możesz zobaczyć class="special" lub niestandardowe nazwy klas. Te nazwy klas generują powiadomienia wizualnie identyczne z powiadomieniem note, ale zalecamy używanie class="note" zamiast specjalnych lub niestandardowych nazw klas.
Korzystanie z Markdown
Style Markdown określają kolor i ikonę powiadomienia oraz automatycznie ustawiają pogrubione pierwsze słowo powiadomienia. Na przykład w Markdownzie notatka zawsze zaczyna się od słowa Uwaga: w czcionce pogrubionej.
W przypadku powiadomienia zawierającego więcej niż 1 akapit użyj kodu HTML <aside> (i <p>).
Zamiast Note: może być widoczna informacja Ważne: Ten styl Markdown powoduje, że powiadomienia są wizualnie identyczne z powiadomieniem Note:.
Sprawdzone metody
DevSite zaleca, aby podczas dodawania powiadomień do dokumentacji przestrzegać tych sprawdzonych metod:
Zalecane
- Bądź zwięzły (staraj się ograniczyć powiadomienia do 1 lub 2 zdań).
- Ogranicz liczbę powiadomień do 1 na stronę (lub 1 na sekcję, jeśli to konieczne).
- Upewnij się, że powiadomienia zawierają tylko ważne treści, które chcesz wyróżnić. Nie umieszczaj w powiadomieniu treści, których nie wiesz, jak wykorzystać.
- Używaj powiadomień, zanim użytkownik będzie potrzebować informacji, a nie później.
Nie zalecane
- Nie umieszczaj w powiadomieniach przykładów kodu, tabel ani obrazów.
- Unikaj nakładania powiadomień na siebie, nawet jeśli są one różnych typów.
- Staraj się nie wstawiać powiadomień bezpośrednio po nagłówkach.
- Nie używaj powiadomień, aby określić wymagania wstępne przed procedurą.
W większości przypadków te sprawdzone metody dotyczą powiadomień typu note, caution i warning, ale mogą też dotyczyć innych typów.
Dobre przykłady
Trzymaj się prostych rozwiązań:
Użyj cautions w przypadku potencjalnej utraty danych:
Użyj warning w przypadku potencjalnego urazu:
Używaj odpowiednich typów powiadomień o treściach, takich jak key-term lub success:
Złe przykłady
Ostrzeżenia nie powinny być zbyt długie ani zawierać informacji, które powinny znaleźć się w głównej treści:
Ostrzeżenia nie powinny zawierać wymagań wstępnych przed procedurą (zamiast tego użyj sekcji „Wymagania wstępne”):