Categoria: Github

 

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:**

[![Tutorial Linux Base](https://img.youtube.com/vi/dQw4w9WgXcQ/hqdefault.jpg)](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:

[![TITOLO](THUMBNAIL_URL)](VIDEO_URL)

Simple Format
Link testuale senza thumbnail:

[TITOLO](VIDEO_URL)

Table Format
Per liste strutturate:

| [![TITOLO](THUMB)](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 😉