Chi revisiona dovrebbe leggere il documento che una pull request modifica, non un diff di asterischi. Questa action pubblica ogni file Markdown modificato come pagina resa e ne commenta i link sulla pull request.
Leggi la configurazione nella documentazione
Senza un elenco di file, l’action chiede a git quali file Markdown la pull request ha toccato, pubblica ciascuno come pagina di sola lettura e commenta una tabella con nomi dei file, numero di parole e link. I file che il branch ha eliminato vengono saltati, quindi rimuovere un documento non fa fallire l’esecuzione.
È un’action composita, `action.yml` alla radice del repository pubblico, e quello che esegue è il client da riga di comando dello stesso repository: nessun container da scaricare, nessuna dipendenza da installare, e la stessa resa che danno il sito e l’API.
Il commento ha il titolo Markdown preview. Chi revisiona apre ogni link in un browser come qualsiasi altra pagina, senza app e, per un link, senza account — così anche chi non apre mai il diff può rivedere i testi.
Un diff è la vista giusta per il codice e quella sbagliata per la prosa. Mostra quali parole sono cambiate e nasconde se la sezione si legge ancora, se una tabella torna o se un elenco numerato ricomincia da uno a metà. La pagina resa risponde a colpo d’occhio, e chi non scrive Markdown può finalmente leggerla.
Un workflow completo da copiare si trova in `examples/publish-markdown.yml`. Gira su `pull_request` con un filtro `paths` per `**.md`, così una pull request che non tocca Markdown non avvia alcun runner. Il checkout ha bisogno di `fetch-depth: 0`, perché i file modificati si calcolano rispetto al commit di base della pull request, e il job ha bisogno di `pull-requests: write` per pubblicare il commento.
Il passo in sé è `uses: raudarlabs/transformpipe@main` con un solo input, `api-key: ${{ secrets.TP_API_KEY }}`. La chiave è una chiave API di TransformPipe conservata come secret del repository, e l’action la passa al client in una variabile d’ambiente invece che come argomento, quindi non fa parte del comando scritto nel log.
`files` accetta percorsi separati da spazi al posto dell’elenco dei file modificati; è così che l’action pubblica a un push su un branch invece che per una pull request. `share` vale `link` per impostazione predefinita, `people` solo per lettori indicati, o `none` per tenere privati i documenti. `merge: true` concatena i file in un solo documento, con il nome dato da `name`.
`replaces` registra un singolo documento come nuova versione di uno precedente, `comment: false` salta il commento, e `host` punta a un’altra installazione.
Per i passi successivi tornano due output: `urls`, i link pubblicati uno per riga, e `documents`, la risposta dell’API per ogni documento, in JSON. Senza nulla da pubblicare, l’action lo dice, lascia `urls` vuoto e `documents` come elenco vuoto, e termina con successo, così un passo successivo si può condizionare a `urls` invece di fallire.
Ogni esecuzione pubblica documenti nuovi invece di sovrascrivere quelli precedenti, così il link di un commento più vecchio continua a mostrare quello che diceva quel commit. Il prezzo è un documento per file e per esecuzione nell’account, che contiene 5.000 documenti e 250 MB; le anteprime vecchie si possono eliminare dalla cronologia.
Pubblicare un link pubblico richiede un indirizzo email confermato sull’account, e finché non lo è il passo fallisce con quella frase. Una pull request che arriva da un fork gira senza i secret del repository, quindi lì il passo non ha una chiave; saltalo con `if: github.event.pull_request.head.repo.fork == false`.