Att använda MkDocs

Innehåll skapas i valfritt redigeringsprogram som klarar av Markdown-filer (.md), därefter bygger MkDocs en statisk sajt utifrån innehållet i dessa filer. Den genererade HTML-sajten kan sedan laddas upp där den skall visas. Detta kan naturligtvis automatiseras via t ex git eller liknande.

En stor fördel med "statiska HTML-sajter" är att de är enormt snabba, kräver väldigt lite resurser och är mycket säkrare än dynamiska sidor som ofta kräver större ramverk med fler komponenter. Det finns självklart nackdelar så som att det inte går att hantera dynamiskt innehåll lika lätt (men det går).

Det finns mängder av tillägg ("plugins") till MkDocs, som t ex PDF-export, Blogg, RSS, mm.

Att använda MkDocs

• mkdocs new [dir-name] - Skapa ett nytt projekt.
• mkdocs serve - Starta en utvecklingsserver för att se sajten i realtid.
• mkdocs build - Skapa de statiska sidorna.
• mkdocs -h - Visa hjälp och avsluta.

Projektlayout

mkdocs.yml    # Konfigurationsfil
docs/
    index.md  # Startsidan för din sajt/dokumentation.
    ...       # Andra markdown-sidor, bilder och andra filer/dokument.

Aktivera resultatet

Det går naturligtvis bra att använda i princip vilket verktyg som helst för att överföra de skapade sidorna till en server som kan visa dem; med t ex git och/eller rsync (över ssh) så går det väldigt snabbt att överföra sidorna till en server.

Du kan också bygga sidorna på samma server som visar dem.