Yt2md Converter YouTube to Markdown
Nel corso dello sviluppo di vari progetti open source, mi sono spesso trovato nella necessità di integrare video tutorial nei file README e nella documentazione tecnica. Il processo manuale di creazione dei link Markdown con thumbnail cliccabili richiedeva tempo e attenzione ai dettagli. Per risolvere questo problema in modo efficiente, ho sviluppato Yt2md Converter (YouTube to Markdown Converter), una suite completa di strumenti in bash che automatizza la conversione di link YouTube in codice Markdown formattato, pronto per l’inserimento in README di GitHub, documentazione tecnica e blog.
Problema e Soluzione
Il Problema
L’integrazione di video YouTube nella documentazione richiede tipicamente:
1. Estrazione del Video ID dall’URL
2. Costruzione dell’URL della thumbnail
3. Scrittura manuale della sintassi Markdown
4. Verifica della correttezza del codice generato
Questo processo, ripetuto per ogni video, diventa rapidamente tedioso e soggetto ad errori.
La Soluzione
Yt2md automatizza completamente questo workflow, offrendo:
– Conversione istantanea da Video ID a Markdown
– Supporto per multipli formati di output
– Interfaccia CLI per automazione
– Interfaccia GUI per utenti non tecnici
– Modalità batch per conversioni multiple
– Zero dipendenze per le versioni CLI base
Installazione Base
Clone repository
git clone https://github.com/fconidi/Yt2md-Converter cd yt2md bash yt2md.sh --help
Installazione Sistema (Opzionale)
Copia in /usr/local/bin
sudo cp yt2md.sh /usr/local/bin/yt2md sudo chmod +x /usr/local/bin/yt2md
Dipendenze GUI
Ubuntu/Debian
sudo apt install zenity xclip
Architettura del Progetto
Il progetto è strutturato in quattro componenti principali:
1. yt2md.sh – CLI Semplificato
La versione consigliata per uso quotidiano. Sintassi minimalista:
bash yt2md.sh VIDEO_ID "TITOLO" "AUTORE"
**Caratteristiche tecniche:**
– Parsing robusto degli ID video da URL multipli formati
– Costruzione dinamica degli URL thumbnail
– Nessuna dipendenza esterna
– Output su stdout o file
– Supporto per 4 formati di output
**Esempio di utilizzo:**
bash yt2md.sh dQw4w9WgXcQ "Tutorial Linux Base" "TechChannel"
**Output generato:**
[](https://www.youtube.com/watch?v=dQw4w9WgXcQ)
2. yt2md-gui.sh – Interfaccia Grafica (Consigliato)
Implementazione basata su Zenity per utenti che preferiscono un’interfaccia visuale.
**Funzionalità:**
– Dialog guidati step-by-step
– Validazione input in tempo reale
– Progress bar per feedback visuale
– Integrazione clipboard (xclip)
– Conversione batch con formato strutturato
– Menu help integrato
**Dipendenze:**
– zenity
– xclip (opzionale, per clipboard)
**Workflow conversione singola:**
1. Input Video ID o URL completo
2. Input titolo (validato, obbligatorio)
3. Input autore (opzionale, default fornito)
4. Selezione formato output
5. Selezione qualità thumbnail
6. Opzioni risultato: clipboard, file, visualizzazione
**Conversione batch:**
Formato input strutturato:
VIDEO_ID | TITOLO | AUTORE
Supporta:
– Parsing automatico con rimozione spazi
– Commenti (linee che iniziano con )
– Progress bar per ogni elemento
– Report errori e successi
3. yt2md-offline.sh – CLI con Opzioni
Versione con sintassi più tradizionale per utenti abituati agli strumenti Unix standard.
bash yt2md-offline.sh -t "TITOLO" -a "AUTORE" VIDEO_ID
4. yt2md-cli.sh – CLI Avanzato
Versione completa con tutte le opzioni disponibili:
bash yt2md-cli.sh --offline --title "TITOLO" --author "AUTORE" VIDEO_ID
Supporta:
– Modalità offline esplicita
– Opzioni estese
– Help dettagliato
– Gestione errori avanzata
Formati Output Supportati
Standard Format
Il formato predefinito, ottimale per README di GitHub:
[](VIDEO_URL)
Simple Format
Link testuale senza thumbnail:
[TITOLO](VIDEO_URL)
Table Format
Per liste strutturate:
| [](URL) | AUTORE |
Embed Format
Codice HTML completo con iframe:
<a href="VIDEO_URL"> <img src="THUMBNAIL" alt="TITOLO" width="480"> </a> <iframe width="560" height="315" src="EMBED_URL"></iframe>
Il sistema supporta multipli formati di URL YouTube:
Supporta:
– URL standard: `youtube.com/watch?v=ID`
– URL brevi: `youtu.be/ID`
– Shorts: `youtube.com/shorts/ID`
– ID diretti: `ID` (11 caratteri)
Costruzione URL Thumbnail
YouTube fornisce thumbnail a diverse risoluzioni:
case "$size" in
default) thumb="https://img.youtube.com/vi/${id}/default.jpg" 120x90
medium) thumb="https://img.youtube.com/vi/${id}/mqdefault.jpg" 320x180
high) thumb="https://img.youtube.com/vi/${id}/hqdefault.jpg" 480x360
maxres) thumb="https://img.youtube.com/vi/${id}/maxresdefault.jpg" 1280x720
esac
Default consigliato: `high` (480×360) per bilanciamento qualità/peso.
Limitazioni Attuali
1. **Modalità Offline:**
– Titolo e autore devono essere forniti manualmente
– Nessuna verifica esistenza video
2. **Metadata:**
– Non recupera durata video
– Non recupera conteggio visualizzazioni
– Non recupera data pubblicazione
3. **Thumbnail:**
– URL fissi (nessuna verifica disponibilità)
– MaxRes potrebbe non esistere per video vecchi
4. **Playlist:**
– Nessun supporto diretto per playlist
– Richiede estrazione manuale ID
Conclusioni
Yt2md Converter rappresenta una soluzione completa per l’integrazione di contenuti YouTube in documentazione tecnica. La sua architettura modulare, la varietà di interfacce disponibili e l’assenza di dipendenze per le versioni base lo rendono adatto a scenari d’uso diversificati.Il progetto è completamente open source (licenza MIT) e accetta contributi dalla community. Il codice è disponibile su GitHub.
Yt2md Converter YouTube to Markdown
enjoy 😉
