Je kunt gebruiken pandoc op Linux om meer dan 40 bestandsformaten te converteren. U kunt het ook gebruiken om een ​​eenvoudig docs-as-code-systeem te maken door in Markdown te schrijven en op te slaan in git, en publiceren in elk van de ondersteunde formaten.
Documentconversie en Docs-as-Code
Als je een document hebt in een van pandoc's veel ondersteunde bestandsindelingen, het converteren naar een van de andere is een makkie. Dat is een handig hulpmiddel om te hebben!
Maar de echte kracht van pandoc wordt duidelijk wanneer u het gebruikt als de basis van een eenvoudig docs-als-codesysteem. Het uitgangspunt van docs-as-code is om enkele van de technieken en principes van softwareontwikkeling over te nemen en toe te passen op het schrijven van documentatie, vooral voor softwareontwikkelingsprojecten. U kunt het echter toepassen op de ontwikkeling van elk soort documentatie.
Softwareontwikkelaars gebruiken hun favoriete editor of geïntegreerde ontwikkelomgeving (IDE) om hun programma’s te schrijven. De code die ze typen, wordt opgeslagen in tekstbestanden. Deze bevatten de broncode van het programma.
Ze gebruiken een versiebeheersysteem, of VCS (Git is het populairst), om wijzigingen in de broncode vast te leggen terwijl deze wordt ontwikkeld en verbeterd. Dit betekent dat de programmeur een volledige geschiedenis heeft van alle versies van de broncodebestanden. Hij of zij heeft snel toegang tot een eerdere versie van een bestand. Git slaat bestanden op in een repository. Er is een lokale opslagplaats op de computer van elke ontwikkelaar en een centrale, gedeelde opslagplaats op afstand die vaak in de cloud wordt gehost.
Als ze klaar zijn om een ​​werkende versie van het programma te produceren, gebruiken ze een compiler om de broncode te lezen en een binair uitvoerbaar bestand te genereren.
Door uw documenten te schrijven in een lichtgewicht, op tekst gebaseerde opmaaktaal, kunt u een VCS gebruiken om uw schrijven te beheren. Als u klaar bent om een ​​document te verspreiden of te publiceren, kunt u pandoc om zoveel verschillende versies van uw documentatie te genereren als u nodig heeft, inclusief webgebaseerde (HTML), tekstverwerkte of typografie (LibreOffice, Microsoft Word, TeX), draagbaar documentformaat (PDF), e-book (ePub) en spoedig.
U kunt dit allemaal doen vanuit één set versie-gecontroleerde, lichtgewicht tekstbestanden.
Pandoc installeren
Installeren pandoc gebruik op Ubuntu deze opdracht:
sudo apt-get install pandoc
Op Fedora is het commando dat je nodig hebt het volgende:
sudo dnf install pandoc
Op Manjaro moet je typen:
sudo pacman -Syu pandoc
U kunt controleren welke versie u heeft geïnstalleerd door de --version optie:
pandoc --version
Pandoc gebruiken zonder bestanden
Als je gebruikt pandoc zonder enige opdrachtregelopties, accepteert het ook getypte invoer. U drukt gewoon op Ctrl + D om aan te geven dat u klaar bent met typen. pandoc verwacht dat u in Markdown-indeling typt, en het genereert HTML-uitvoer.
Laten we naar een voorbeeld kijken:
pandoc
We hebben een paar regels Markdown getypt en staan ​​op het punt Ctrl + D te raken.
Zodra we dat doen, pandoc genereert de equivalente HTML-uitvoer.
Om iets nuttigs mee te doen pandocwe hebben echter echt bestanden nodig.
Markdown Basics
Markdown is een lichtgewicht opmaaktaal en aan bepaalde tekens wordt een speciale betekenis gegeven. U kunt een platte-teksteditor gebruiken om een ​​Markdown-bestand te maken.
Markdown kan gemakkelijk worden gelezen, omdat er geen visueel omslachtige tags zijn die de tekst afleiden. Opmaak in Markdown-documenten lijkt op de opmaak die het vertegenwoordigt. Hieronder staan ​​enkele basisprincipes:
- Om tekst te benadrukken met cursief, wikkel het in asterisken.
*This will be emphasized* - Naar stoutmoedig tekst, gebruik dan twee asterisken.
**This will be in bold** - Koppen worden weergegeven door het hekje / hekje (
#). Tekst wordt van de hash gescheiden door een spatie. Gebruik één hash voor een kop op het hoogste niveau, twee voor een tweede niveau, enzovoort. - Om een ​​lijst met opsommingstekens te maken, begint u elke regel van de lijst met een asterisk en voegt u een spatie in voor de tekst.
- Om een ​​genummerde lijst te maken, begint u elke regel met een cijfer gevolgd door een punt, en voegt u vervolgens een spatie in voor de tekst.
- Om een ​​hyperlink te maken, plaatst u de naam van de site tussen vierkante haken (
[]) en de URL tussen haakjes [()] zo:[Link to How to Geek](https://www.howtogeek.com/). - Als u een afbeelding wilt invoegen, typt u een uitroepteken direct vóór haakjes (
![]). Typ een alternatieve tekst voor de afbeelding tussen haakjes. Zet vervolgens het pad naar de afbeelding tussen haakjes [()“]. Hier is een voorbeeld:.
In de volgende sectie zullen we van al deze voorbeelden meer voorbeelden bespreken.
VERWANT: Wat is markdown en hoe gebruik je het?
Bestanden converteren
Bestandsconversies zijn eenvoudig. pandoc kan meestal uit hun bestandsnamen achterhalen met welke bestandsindelingen u werkt. Hier gaan we een HTML-bestand genereren vanuit een Markdown-bestand. De -o (output) optie vertelt pandoc de naam van het bestand dat we willen maken:
pandoc -o sample.html sample.md
Ons voorbeeld van Markdown-bestand, sample.md, bevat het korte gedeelte van Markdown dat in de onderstaande afbeelding wordt weergegeven.
Er wordt een bestand met de naam sample.html gemaakt. Wanneer we dubbelklikken op het bestand, zal onze standaardbrowser het openen.
Laten we nu een tekstdocument in Open Document-indeling genereren dat we kunnen openen in LibreOffice Writer:
pandoc -o sample.odt sample.md
Het ODT-bestand heeft dezelfde inhoud als het HTML-bestand.
Een leuke bijkomstigheid is dat de alternatieve tekst voor de afbeelding ook wordt gebruikt om automatisch een bijschrift voor de figuur te genereren.
Bestandsformaten specificeren
De -f (van) en -t (to) opties worden gebruikt om te vertellen pandoc welke bestandsindelingen u wilt converteren van en naar. Dit kan handig zijn als u werkt met een bestandsindeling die een bestandsextensie deelt met andere gerelateerde indelingen. TeX en LaTeX gebruiken bijvoorbeeld beide de extensie “.tex”.
We gebruiken ook de -s (standalone) optie dus pandoc genereert alle LaTeX-preambule die nodig is om een ​​document een compleet, op zichzelf staand en goed gevormd LaTeX-document te laten zijn. Zonder de -s (standalone) optie, zou de uitvoer nog steeds goedgevormde LaTeX zijn die in een ander LaTeX-document zou kunnen worden ingevoegd, het zou niet correct worden geparseerd als een op zichzelf staand LaTeX-document.
We typen het volgende:
pandoc -f markdown -t latex -s -o sample.tex sample.md
Als u het bestand “sample.tex” in een teksteditor opent, ziet u de gegenereerde LaTeX. Als u een LaTeX-editor heeft, kunt u het TEX-bestand openen om een ​​voorbeeld te zien van hoe de LaTeX-typografische commando’s worden geïnterpreteerd. Door het venster te verkleinen om in de onderstaande afbeelding te passen, zag het scherm er krap uit, maar in werkelijkheid was het prima.
We gebruikten een LaTeX-editor genaamd Texmaker. Als je het in Ubuntu wilt installeren, typ je het volgende:
sudo apt-get install texmaker
In Fedora is het commando:
sudo dnf install texmaker
Gebruik in Manjaro:
sudo pacman -Syu texmaker
Bestanden converteren met sjablonen
Je begint waarschijnlijk de flexibiliteit ervan te begrijpen pandoc biedt. U kunt één keer schrijven en in bijna elk formaat publiceren. Dat is een mooie prestatie, maar de documenten zien er wel een beetje vanille uit.
Met sjablonen kunt u bepalen welke stijlen pandoc gebruikt wanneer het documenten genereert. U kunt het bijvoorbeeld zien pandoc om de stijlen te gebruiken die zijn gedefinieerd in een Cascading Style Sheets (CSS) -bestand met de --css optie.
We hebben een klein CSS-bestand gemaakt met de onderstaande tekst. Het verandert de afstand boven en onder de niveaukop één stijl. Het verandert ook de tekstkleur in wit en de achtergrondkleur in een blauwe tint:
h1 {
color: #FFFFFF;
background-color: #3C33FF;
margin-top: 0px;
margin-bottom: 1px;
}
Het volledige commando staat hieronder – merk op dat we ook de zelfstandige optie hebben gebruikt (-s):
pandoc -o sample.html -s --css sample.css sample.md
pandoc gebruikt de enkele stijl uit ons minimalistische CSS-bestand en past deze toe op de koptekst van niveau één.
Een andere fijnafstemmingsoptie die u beschikbaar hebt wanneer u met HTML-bestanden werkt, is om HTML-markeringen op te nemen in uw Markdown-bestand. Dit wordt als standaard HTML-opmaak doorgegeven aan het gegenereerde HTML-bestand.
Deze techniek moet echter worden gereserveerd voor wanneer u alleen HTML-uitvoer genereert. Als u met meerdere bestandsindelingen werkt, pandoc negeert de HTML-opmaak voor niet-HTML-bestanden en wordt als tekst aan die bestanden doorgegeven.
We kunnen ook specificeren welke stijlen worden gebruikt wanneer ODT-bestanden worden gegenereerd. Open een leeg LibreOffice Writer-document en pas de kop- en lettertypestijlen aan uw behoeften aan. In ons voorbeeld hebben we ook een kop- en voettekst toegevoegd. Sla uw document op als “odt-template.odt.”
We kunnen dit nu als sjabloon gebruiken met de --reference-doc optie:
pandoc -o sample.odt --reference-doc=odt-template.odt sample.md
Vergelijk dit met het ODT-voorbeeld van eerder. Dit document gebruikt een ander lettertype, heeft gekleurde koppen en bevat kop- en voetteksten. Het werd echter gegenereerd op basis van exact hetzelfde “sample.md” Markdown-bestand.
Referentiedocumentsjablonen kunnen worden gebruikt om verschillende stadia van de productie van een document aan te geven. U kunt bijvoorbeeld sjablonen hebben met het watermerk “Concept” of “Ter beoordeling”. Een sjabloon zonder watermerk zou worden gebruikt voor een afgerond document.
PDF’s genereren
Standaard, pandoc gebruikt de LaTeX PDF-engine om PDF-bestanden te genereren. De eenvoudigste manier om ervoor te zorgen dat aan de juiste LaTeX-afhankelijkheden wordt voldaan, is door een LaTeX-editor te installeren, zoals Texmaker.
Dat is echter een behoorlijk grote installatie: Tex en LaTeX zijn beide behoorlijk fors. Als de ruimte op uw harde schijf beperkt is, of als u weet dat u TeX of LaTeX nooit zult gebruiken, geeft u er misschien de voorkeur aan om een ​​ODT-bestand te genereren. Vervolgens kunt u het gewoon openen in LibreOffice Writer en het opslaan als een pdf.
Docs-as-Code
Het gebruik van Markdown als uw schrijftaal heeft verschillende voordelen, waaronder de volgende:
-
Werken in platte tekstbestanden is snel: Ze worden sneller geladen dan tekstverwerkingsbestanden van vergelijkbare grootte en hebben de neiging om ook sneller door het document te bladeren. Veel editors, waaronder
gedit,Vim, enEmacs, gebruik syntaxisaccentuering met Markdown-tekst. - Je hebt een tijdlijn van alle versies van je documenten: Als je je documentatie opslaat in een VCS, zoals Git, kun je gemakkelijk de verschillen zien tussen twee versies van hetzelfde bestand. Dit werkt echter alleen echt als de bestanden platte tekst zijn, want dat is wat een VCS verwacht te werken.
- Een VCS kan registreren wie wijzigingen heeft aangebracht en wanneer: Dit is vooral handig als u vaak samen met anderen aan grote projecten werkt. Het biedt ook een centrale opslagplaats voor de documenten zelf. Veel in de cloud gehoste Git-services, zoals GitHub, GitLab en BitBucket, hebben gratis niveaus in hun prijsmodellen.
- U kunt uw documenten in meerdere indelingen genereren: Met slechts een paar eenvoudige shell-scripts kunt u de stijlen van CSS en referentiedocumenten binnenhalen. Als u uw documenten opslaat in een VCS-repository die integreert met Continuous Integration and Continuous Deployment (CI / CD) -platforms, kunnen ze automatisch worden gegenereerd wanneer de software wordt gebouwd.
VERWANT: Wat is GitHub en waarvoor wordt het gebruikt?
Laatste gedachten
Er zijn veel meer opties en functies binnen pandoc dan wat we hier hebben besproken. De conversieprocessen voor de meeste bestandstypen kunnen worden aangepast en verfijnd. Bekijk voor meer informatie de uitstekende voorbeelden op de officiële (en uiterst gedetailleerde) pandoc-webpagina.