Cosa viene conservato
Per convertire un export di Confluence in Markdown viene letto ogni file .html dello .zip prodotto dall’export HTML di uno spazio. Per impostazione predefinita lo spazio diventa una cartella di pagine: un documento Markdown per pagina, una sottocartella per sezione e, al suo interno, la pagina della sezione stessa al primo posto. L’opzione Un solo documento riunisce invece tutte le pagine in un unico file.
| Nell’export | Nel Markdown |
|---|---|
Il titolo, scritto Spazio : Pagina |
# Pagina, senza il nome dello spazio |
| Il percorso di navigazione | La cartella in cui la pagina viene archiviata |
| Titoli, elenchi, grassetto, corsivo | Lo stesso, in Markdown |
| Una tabella | Una tabella Markdown, con la prima riga come intestazione |
| La macro Indice, un link a un titolo | Un link allo slug del titolo, nello stile di GitHub |
| Un link a un’altra pagina | Un link a quella pagina, in una cartella di pagine |
Un’immagine in attachments/ |
Incorporata nella pagina; quelle più pesanti prima ridotte a non più di 1.600 pixel sul lato lungo |
| Un link a un indirizzo web | Resta un link |
Cosa si perde
- Le macro in quanto macro. Nessuna ha una regola propria: ognuna arriva come l’HTML che l’export ne ha ricavato, per cui un pannello informativo diventa i suoi paragrafi, senza il pannello.
- Le celle unite. Il testo finisce nella prima cella coperta e, sotto una cella unita verso il basso, la riga scorre a sinistra. Una cella con più paragrafi o con un elenco viene appiattita su una sola riga.
- Gli allegati che non sono immagini. Un PDF non viene portato con sé, quindi in una cartella di pagine il suo link diventa il suo nome, come i link alle schermate proprie di Confluence.
- Le immagini oltre il margine. In una cartella di pagine ogni pagina può portare quasi 4 MB di immagini, nessuna oltre 1 MB una volta codificata; quella che non ci sta diventa il suo testo alternativo o il nome del file in corsivo. Un solo documento si divide 2 MB, e un’immagine che li supera conserva il suo percorso
attachments/.
Un esempio
Un export di spazio in cui la pagina «Deploy checklist», sotto «Runbooks», contiene una macro Indice, un titolo, una tabella, un link alla pagina «Rollback», un runbook.pdf collegato e uno screenshot. Come cartella di pagine, scaricata in .zip, diventa Engineering/Runbooks/Deploy checklist.md (dati dell’immagine accorciati, cornice della pagina omessa):
# Deploy checklist
- [Before you deploy](#before-you-deploy)
## Before you deploy
| Step | Owner |
| --- | --- |
| Tag the release | Ops |
| Announce the freeze | Release lead |
If it fails, follow [Rollback](Rollback.md). The full runbook is runbook.pdf.
La voce dell’indice puntava all’identificativo di Confluence Deploychecklist-Beforeyoudeploy e ora porta al titolo tramite lo slug. Come documento unico, la pagina sarebbe una sezione sotto un elenco # Contents con i titoli delle pagine.
Limiti
Lo .zip può arrivare a 250 MB; vengono decompresse solo le pagine e le immagini, e uno .zip senza file .html viene rifiutato. La conversione avviene nel browser: senza accesso non viene caricato nulla, e con l’accesso nulla arriva nell’account finché non si salva. Una pagina salvata può pesare fino a 4 MB.
Le pagine sono ordinate per nome di file, con index.html per primo, e non secondo l’albero delle pagine di Confluence. Nulla isola il contenuto principale: a parte il percorso di navigazione, la cornice della pagina arriva come testo, per esempio un titolo che ripete il nome dello spazio, una riga con l’autore o una riga «Document generated by Confluence». Conviene controllare i blocchi di codice: un blocco di codice delimitato compare solo dove l’HTML ha <code> dentro <pre>, mentre un <pre> da solo arriva come semplici righe. Le spunte vengono lette solo da caselle di controllo HTML, senza una regola per gli elenchi di attività di Confluence.
Altro sulle macro in convertire una pagina Confluence in Markdown, e sullo .zip in come aprire uno .zip di export.
Domande
È un’app o un plugin di Confluence?
No. In Confluence non si installa nulla e niente si collega a Confluence: si esporta lo spazio in HTML e si trascina qui lo .zip. Le opzioni gratuite a confronto esamina anche le app del Marketplace.
Funziona con gli export di Confluence Cloud e Data Center?
Nessuno dei due ha un percorso a parte: il convertitore legge le stesse cose da qualsiasi export HTML, cioè il <title> di ogni pagina, il percorso di navigazione, gli identificativi dei titoli e il nome del file. In ogni caso, questa pagina accetta lo .zip dell’export HTML e nessun altro file.
Si può convertire una singola pagina Confluence in Markdown?
Sì, purché arrivi in HTML dentro uno .zip. Viene letto ogni file .html dell’archivio, quindi una pagina si converte esattamente come seicento.
Si può ottenere HTML invece di Markdown?
Basta scegliere Un solo documento: il menu di download del risultato offre HTML, Word e testo semplice accanto al Markdown. Una cartella di pagine si scarica solo in Markdown.
I link tra le pagine continuano a funzionare?
In una cartella di pagine sì: ognuno punta al documento salvato nell’account o al file della pagina collegata nello .zip scaricato. In un solo documento conservano i nomi di file dell’export, che fuori da esso non portano da nessuna parte.