Ghid de stil al documentației
We don’t have an official style guide yet, but the current OpenTelemetry documentation style is inspired by the following style guides:
Următoarele secțiuni conțin îndrumări specifice proiectului OpenTelemetry.
Multe cerințe ale ghidului nostru de stil pot fi aplicate prin rularea
automatizării: înainte de a trimite un pull request (PR), rulează
npm run fix:all pe mașina ta locală și confirmă modificările.
Dacă întâmpini erori sau verificări de PR eșuate, citește despre ghidul nostru de stil și află ce poți face pentru a remedia anumite probleme comune.
Listă de cuvinte OpenTelemetry.io
O listă de termeni și cuvinte specifice OpenTelemetry care trebuie utilizate în mod consecvent pe tot site-ul:
Pentru o listă completă a termenilor OpenTelemetry și definiția acestora, vezi Glosar.
Asigură-te că substantivele proprii, cum ar fi alte proiecte CNCF sau
instrumente terțe, sunt scrise corect și folosesc majusculele originale. De
exemplu, scrie „PostgreSQL” în loc de „postgre”. Pentru o listă completă,
verifică fișierul
.textlintrc.yml.
Markdown
Paginile site-ului sunt scrise în sintaxa Markdown acceptată de programul de randare Markdown Goldmark. Pentru lista completă a extensiilor Markdown acceptate, vezi Goldmark.
De asemenea, poți utiliza următoarele extensii Markdown:
Alerte
Poți scrie alerte folosind următoarea sintaxă extinsă:
- Markdown cu stil GitHub (GFM) alerts
- Sintaxa Obsidian callout pentru titluri de alerte personalizate
Iată un exemplu pentru fiecare:
> [!TIP]
>
> Dacă scrii conținut nou, în general, preferă folosirea acestei sintaxe de alertă cu citate bloc
> în loc de sintaxa Docsy
> [alert shortcode](https://www.docsy.dev/docs/content/shortcodes/#alert).
> [!WARNING] :warning: Este necesară o linie goală!
>
> Acest site folosește formatorul [Prettier] și necesită o linie goală care să separe eticheta/titlul alertei de corpul alertei.
Acestea se redau astfel:
Dacă scrii conținut nou, în general, preferă folosirea acestei sintaxe de alertă cu citate bloc în loc de sintaxa Docsy alert shortcode.
Acest site folosește formatorul Prettier și necesită o linie goală care să separe eticheta/titlul alertei de corpul alertei.
Pentru detalii despre sintaxa alertelor pentru citate bloc, consultă Alerts din documentația Docsy.
Referințe de link
Când utilizezi Markdown linkuri de referință, preferă forma restrânsă
[text][] în locul formei shortcut [text]. Deși ambele sunt valide
CommonMark, forma shortcut nu este recunoscută în mod constant de toate
instrumentele Markdown. În special, dacă scrii [exemplu] și uiți definiția,
linter-ul markdownlint nu te va avertiza1 – textul este redat
silențios ca literal [exemplu] în loc de link. Cu forma restrânsă
[exemplu][], linter-ul surprinde imediat definiția lipsă.
Acest lucru este impus de regula personalizată no-shortcut-ref-link. Rulează
npm run fix:markdown pentru a converti automat referințele la comenzi rapide.
Verificări Markdown
Pentru a aplica standarde și consecvență pentru fișierele Markdown, toate fișierele ar trebui să respecte anumite reguli, impuse de markdownlint. Pentru o listă completă, consultă fișierele .markdownlint.yaml și .markdownlint-cli2.yaml.
Când există excepții legitime de la o regulă, utilizează directiva
markdownlint-disable pentru a suprima avertismentele privind regula. Pentru
detalii, vezi
documentația markdownlint.
De asemenea, aplicăm Markdown format fișier și eliminăm spațiile albe de la sfârșit din fișiere. Acest lucru exclude sintaxa de sfârșit de linie de peste 2 spații; utilizează