Un README és còmode per revisar un projecte, però la mateixa informació pot necessitar un document estable per a una reunió, un lliurament o un arxiu. Convertir Markdown a PDF permet conservar una font de text pla i lliurar una còpia amb pàgines, marges i text seleccionable. La feina no acaba obtenint un fitxer amb extensió .pdf: cal comprovar que l'estructura, els enllaços, les taules i el codi continuen comunicant correctament després de paginar.
Aquesta guia construeix un README reproduïble i el converteix amb l'eina Markdown a PDF. UtilX processa l'entrada al navegador i només exporta quan es demana. L'exemple no conté informació confidencial i separa allò que mostra la previsualització d'allò que s'ha de verificar al PDF.
Definir el document abans de formatar-lo
Markdown descriu estructura mitjançant convencions de text. CommonMark distingeix blocs com títols, paràgrafs, citacions, llistes, separadors i blocs de codi d'elements en línia com enllaços, èmfasi i codi. GitHub Flavored Markdown afegeix taules, elements de tasca i ratllat. El convertidor trasllada aquestes estructures a un model de pàgines; no pot mantenir exactament l'amplada fluida d'un navegador.
Defineix primer la finalitat i el lector. En aquest exemple, un equip necessita una llista de publicació disponible sense connexió. El PDF s'ha de poder llegir en paper A4, conservar enllaços HTTPS actius, mostrar el codi com a codi i distingir les tasques completades. Són requisits verificables. “Es veu igual a tot arreu” no ho és: la previsualització i el PDF fan servir motors de composició diferents i poden variar els salts de línia i pàgina.
Un README complet d'exemple
Crea release-readme.md amb aquest contingut sintètic. Recorre la sintaxi admesa sense dependre de fitxers remots:
# Publicació d'Atlas 1.4
**Responsable:** equip de documentació
*Finestra:* 18 de setembre de 2026
~~Objectiu anterior: 1.3~~
> Publica només després de comprovar la reversió.
## Llista
- [x] Congelar traduccions
- [ ] Publicar el paquet
- [x] Verificar checksum
- [ ] Copiar la nota de versió
## Ordres
Executa `npm test` i després:
~~~sh
npm run build
npm run smoke
~~~
## Entorns
| Nom | URL | Responsable |
| --- | --- | --- |
| Proves | [estat](https://example.com/status) | Plataforma |
| Producció | pendent | Operacions |
---
Consulta el [procediment](https://example.com/runbook).
El PDF esperat conté un títol principal, tres metadades —responsable, finestra i objectiu anterior ratllat—, una citació, tasques imbricades, codi en línia i en bloc, una taula de tres columnes, un separador i dos enllaços. No s'especifica un nombre de pàgines: depèn del paper, els marges, la mida de lletra i l'ajustament.
Convertir i verificar pas a pas
Obre l'eina localitzada i enganxa l'exemple o importa el .md. Mantén la font per sota de 200 KiB en UTF-8; una entrada superior es rebutja abans d'analitzar-la. A la previsualització revisa la jerarquia, no els límits de pàgina. Confirma que el títol destaca sobre el cos, que les tasques obertes i acabades són diferents, que cada element imbricat queda sota el pare i que la taula conserva tres columnes.
Tria A4, marges de 20 mm, text de 12 pt i numeració. Escriu un nom descriptiu com atlas-1-4-publicacio.pdf i exporta explícitament. Canviar la font no ha d'iniciar cap descàrrega. Obre el PDF desat en un altre lector. Selecciona i copia una frase per confirmar que el cos és text, no una captura. Cerca reversió, activa els dos enllaços HTTPS i amplia el bloc d'ordres i la taula.
Repeteix amb Letter si el destinatari imprimeix en aquest format. Compara significat i llegibilitat, no coordenades. Una taula estreta pot ajustar-se diferent i un títol pot passar a la pàgina següent. Si una fila costa de llegir, escurça les cel·les o transforma-la en llista abans d'encongir tot el document.
Què canvia realment cada opció
A4 i Letter tenen dimensions diferents; el mateix paràgraf pot ocupar un nombre diferent de línies. Els marges de 12, 20 i 28 mm canvien l'àrea d'escriptura. Les mides de cos de 10, 12 i 14 pt canvien densitat i llegibilitat. Les opcions interactuen: augmentar marges i lletra causa salts anteriors i normalment més pàgines.
Els números de pàgina són decoració opcional de sortida. Ajuden a comentar una còpia fixa, però no formen part de Markdown. La generació distribueix contingut en una mida tancada i pot situar un número dinàmic al peu. El document exportat manté text seleccionable i els enllaços compatibles. La previsualització aproxima estil i ordre honestament, però no garanteix paginació idèntica.
La primera versió admet títols, paràgrafs, negreta, cursiva, ratllat, enllaços HTTP(S) i mailto, llistes ordenades o no ordenades imbricades, tasques, citacions, separadors, codi en línia i delimitat i taules GFM. Cal enumerar-ho perquè els dialectes Markdown difereixen. Que una extensió funcioni en un repositori no implica que tots els convertidors l'entenguin.
Resoldre errors habituals
Si una llista perd la imbricació, revisa el sagnat i deixa línies buides al voltant dels blocs veïns. Si una taula mostra les barres verticals literalment, comprova que tingui capçalera, fila delimitadora i les mateixes columnes lògiques a cada fila. Si el codi absorbeix format posterior, tanca la tanca amb el mateix marcador i almenys la longitud d'obertura. Aquestes comprovacions segueixen les regles de blocs, no l'espaiat visual d'un editor.
Les imatges remotes i les referències a fitxers locals no es carreguen. El convertidor mostra el text alternatiu i un avís perquè l'omissió sigui visible. Escriu un alt útil i adjunta les imatges aprovades per separat si el flux final les exigeix. L'HTML cru es mostra literalment amb un avís; no s'executa. No facis servir una etiqueta HTML per evitar una limitació de maquetació.
Si l'exportació s'atura, comprova primer la mida UTF-8. Dividir un document gran en capítols coherents és més segur que esborrar avisos o codi a cegues. Si un enllaç falla, verifica que comenci per https://, http:// o mailto: i prova'l al PDF exportat a més de la previsualització.
Decisions per a un lliurament durador
Conserva Markdown com a font editable i tracta el PDF com una sortida datada. Registra paper, marges, cos, numeració i data de l'eina al costat del procés. Així un altre revisor pot reproduir l'exportació en comptes d'editar un PDF opac. En documents controlats, desa conjuntament la revisió de la font i el fitxer exportat.
Ordena els títols i escriu text d'enllaç descriptiu. No depenguis només del color per indicar l'estat d'una tasca. Mantén curtes les línies de codi i compactes les taules: totes dues estructures tenen una amplada natural que el paper pot no admetre. Una llista sovint resisteix millor que una taula plena de prosa. Abans de compartir, llegeix el PDF amb zoom normal, selecció i cerca, no només com a miniatures.
El processament al navegador evita que aquesta conversió necessiti enviar el Markdown introduït al servidor de l'aplicació, però la descàrrega entra al flux normal d'emmagatzematge del navegador i del sistema. Aplica-hi les mateixes regles de classificació i compartició que a qualsevol document exportat.
Límits del convertidor
La primera versió no representa matemàtiques, diagrames Mermaid, HTML personalitzat ni contingut executable. No obté imatges remotes ni fitxers referenciats. Tampoc promet paginació o píxels idèntics entre vista i PDF, conformitat d'arxiu, accessibilitat de PDF etiquetat, signatures digitals, xifratge o complements propis d'un repositori. Que un PDF s'obri no demostra que sigui accessible, aprovat o complet.
Les taules complexes poden continuar sent poc llegibles encara que siguin vàlides. Per evitar retalls, el sagnat del PDF deixa d'augmentar després de sis nivells de llista imbricada, tot i que conserva el contingut restant. Si l'amplada disponible deixaria una columna per sota de 25 pt, la taula es rebutja amb un avís: divideix columnes o redueix els marges en lloc de forçar una exportació il·legible.
Les cadenes sense punts de tall i les línies llargues de codi poden ajustar-se de manera estranya. L'exportació afegeix oportunitats de salt i alguns lectors PDF poden inserir espais quan es copia text que les travessa. Si una ordre ha de ser exacta, copia la línia llarga des del PDF i compara-la caràcter per caràcter amb la font Markdown abans d'executar-la. Els lectors també gestionen diferent els enllaços i les fonts. Prova l'arxiu exportat en l'entorn d'ús i tria un flux editorial especialitzat quan calgui tipografia exacta, accessibilitat avançada o compliment normatiu.
Llista final de comprovació
Confirma que la font és UTF-8 i no supera 200 KiB. Comprova títols, èmfasi, ratllat, enllaços, llistes imbricades i de tasques, citacions, separadors, codi i taules davant del significat previst. Revisa cada avís d'imatge i d'HTML literal. Exporta amb A4 o Letter, marges de 12, 20 o 28 mm, cos de 10, 12 o 14 pt i l'opció de numeració acordada.
Obre independentment el PDF descarregat. Selecciona i copia text, cerca una frase coneguda, segueix els enllaços importants i inspecciona columnes, codi i transicions entre pàgines. Compara contingut i jerarquia amb el README sense exigir la mateixa paginació que la previsualització. Finalment, conserva la font i les opcions amb el PDF verificat perquè una altra persona pugui reproduir el resultat.
Fonts: especificació CommonMark, especificació GitHub Flavored Markdown i documentació de definició de documents de pdfmake.