Convertor Markdown în Confluence

Echipele de inginerie, arhitecții, managerii de produs și autorii tehnici se bazează pe Markdown pentru documentație tehnică, înregistrări de decizie arhitecturală (ADR), design de sistem și README-uri. Markdown este ușor, lizibil, versionat în Git și portabil. Totuși, echipele enterprise folosesc adesea Atlassian Confluence ca bază de cunoștințe și wiki intern. Podul dintre fișierele Markdown din Git și paginile Confluence a fost, istoric, dureros și fragmentat.

De ce conversia este dificilă

Confluence nu randează nativ textul Markdown brut lipit în editorul web. Confluence Cloud modern folosește Atlassian Document Format (ADF) și Confluence Storage Format (schemă XML bazată pe XHTML), iar instanțele mai vechi Confluence Server și Data Center se bazează pe Confluence Wiki Markup. Când lipești Markdown standard în editorul vizual, elementele se rup:

• Blocurile de cod pierd evidențierea: gardurile cu trei backtick-uri (```python) revin la paragrafe neformatate sau casete preformatate generice, fără culoare de sintaxă și fără limbaj.
• Tabelele se dezintegrează: tabelele cu delimitatori pipe (|) nu devin tabele HTML Confluence structurate; anteturile, rândurile și coloanele trebuie recreate manual.
• Callout-urile și citatele se dezaliniază: blockquote-urile pierd formatarea și cer restructurare manuală.
• Ierarhia de titluri și ancorele se desincronizează: structurile (# H1, ## H2) pierd maparea cuprinsului și rup ancorele din articolele lungi.

Riscul de securitate al convertoarelor pe server

Multe utilitare online procesează textul prin HTTP POST către endpoint-uri externe. Când convertești documentație internă, diagrame de infrastructură, chei API, scheme de baze de date sau algoritmi proprietari cu convertoare găzduite în cloud, riști să transmiți date enterprise pe infrastructură terță.

Politicile de securitate, SOC 2, ISO 27001 și HIPAA interzic încărcarea documentației interne de cod pe servicii web neverificate. Utiliome execută parsarea Markdown și traducerea în marcaj wiki Confluence local, în browser. Prin API-uri web JavaScript și logică pe client, textul nu părăsește DOM-ul browserului. Nu pleacă apeluri API, nicio bază jurnalizează interogările și proprietatea intelectuală nu ajunge pe servere din afară.

Ieșirea Confluence Wiki Markup

La migrarea documentației, conversia în Confluence Wiki Markup oferă o sintaxă portabilă, care funcționează cu dialogul Insert Markup (Confluence Cloud și Server/Data Center):

• Blocuri de cod îngrădite: traduse în macro-uri {code} sau {code:lang}, cu conținutul de cod neatins.
• Titluri și formatare: titlurile trec de la # la h1. până la h6., îngroșatul la *bold*, cursivul la _italic_ și textul tăiat la -strike-.
• Tabele: tabelele pipe devin tabele wiki native, cu celule de antet || și celule de corp |.
• Linkuri și liste: linkurile devin [text|url], iar listele cu buline și numerotate folosesc notația Confluence * și #.

Flux pentru sincronizarea documentației

Integrarea conversiei în fluxul zilnic durează sub 30 de secunde:

1. Pregătește sursa Markdown: redactează specificația, notele de lansare sau post-mortem-ul în VS Code, Obsidian, GitHub sau orice editor de text.
2. Deschide convertorul gratuit Utiliome: pagina funcționează în Chrome, Firefox, Safari și Edge.
3. Lipește sau lasă fișierul: introdu textul. Marcajul wiki se actualizează în timp real.
4. Copiază sau descarcă: apasă „Copiază” sau descarcă confluence.txt.
5. Lipește în Confluence: deschide pagina țintă în editare, alege Insert > Markup (sau Ctrl+Shift+D / Cmd+Shift+D), selectează Confluence Wiki, lipește marcajul și apasă Insert.

Pentru o fișă de sintaxă și un flux pandoc, vezi fișa de sintaxă Markdown în marcaj wiki Confluence.

Ca să livreze documentație curată pentru Confluence, Utiliome face conversie de sintaxă pe linii, sigură pentru cod. Mai jos, maparea elementelor în primitive wiki Confluence:

1. Garduri de cod și evidențiere

În Markdown standard, gardurile folosesc trei backtick-uri și, opțional, un identificator de limbaj:

```typescript
interface UserProfile {
  id: string;
  email: string;
  role: 'admin' | 'user';
}
```

Utiliome transformă blocul într-un macro Code Confluence:

{code:typescript}
interface UserProfile {
  id: string;
  email: string;
  role: 'admin' | 'user';
}
{code}

Inserat în Confluence, codul păstrează evidențierea și structura, iar caracterele interne rămân neatinse.

2. Citate

Blockquote-urile Markdown (> quote) se convertesc linie cu linie în sintaxa de citat pe o linie (bq. quote):

> Production database maintenance will occur on Sunday at 02:00 UTC.

Devine automat:

bq. Production database maintenance will occur on Sunday at 02:00 UTC.

3. Tabele structurate

Utiliome parsează tabelele pipe în tabele wiki Confluence, cu antet || și corp |:

Marcaj wiki convertit:

||Nume serviciu||Port||Endpoint de health check||Stare||
|Auth Service|8080|/healthz|Active|
|Payment Gateway|8081|/status|Active|

4. Liste și formatare inline

Elementele neordonate (-, *, +) devin linii cu buline Confluence (*, ), iar listele ordonate (1., 1)) folosesc notația numerotată (#, ##). Formatarea inline precum bold**, *italic*, ~~strikethrough~~ și `inline code` se mapează la echivalentele wiki (*bold*, _italic_, -strikethrough- și {{inline code}}).

Bune practici între Git și Confluence

Ca să păstrezi o singură sursă de adevăr între repository-uri Git și spațiile Confluence:

• Păstrează sursele în Git: documentele de arhitectură stau ca fișiere .md lângă cod.
• Folosește Utiliome pentru conversie: la note de lansare sau specificații pentru stakeholderi, treci Markdown prin convertorul privat.
• Evită editarea manuală în Confluence: tratează Confluence ca destinație publicată, doar citire, pentru documentele gestionate în Git, ca să eviți driftul.
• Standardizează sintaxa: bazează-te pe elemente GFM — titluri, tabele pipe și garduri de cod — ca conversia automată să rămână lină.

Echipele redactează adesea documentația în Markdown, în repository-uri Git, înainte de publicarea în spațiile Atlassian Confluence ale companiei. Utiliome traduce automat gardurile de cod în macro-uri de bloc de cod Confluence și convertește tabelele pipe în marcaj nativ de tabel Confluence.

Mai jos este specificația tehnică a convertorului de sintaxă Confluence, pe client:

Convertoare de sintaxă înrudite: Markdown în Jira • Markdown în Notion • Markdown în Slack • Editor Markdown.