Intro

Estimated time to read: 3 minutes

Cos'é MkDocs?¶

MkDocs è uno strumento di generazione di documentazione progettato per semplificare il processo di creazione di documenti per progetti software, pagine web personali e altro ancora. Con MkDocs, è possibile scrivere la documentazione utilizzando il linguaggio di markup Markdown, rendendo il processo di creazione e manutenzione della documentazione accessibile anche a chi non è esperto di HTML o altri linguaggi di markup più complessi.

Perchè utilizzare MkDocs?¶

Ci sono diverse ragioni per scegliere MkDocs come strumento per la creazione della documentazione. Ecco qualche esempio:

Semplicità d'uso: MkDocs si basa sul linguaggio di markup Markdown, che è noto per la sua semplicità e chiarezza. Questo rende la creazione e la manutenzione della documentazione accessibile anche a coloro che non hanno familiarità con linguaggi di markup più complessi come HTML.
Rapidità nella creazione: MkDocs semplifica il processo di creazione della documentazione. Con pochi comandi, è possibile inizializzare un progetto, aggiungere nuove pagine e generare un sito di documentazione completo. Ciò consente di concentrarsi maggiormente sul contenuto, riducendo il tempo necessario per la creazione della documentazione.
Aspetto professionale ed elegante: MkDocs genera siti web di documentazione con un design moderno ed elegante. L'aspetto pulito e la navigazione intuitiva migliorano l'esperienza dell'utente, rendendo la documentazione più piacevole da leggere e consultare.
Configurazione flessibile: MkDocs offre molte opzioni di configurazione che consentono di personalizzare l'aspetto e il comportamento del sito di documentazione. Puoi personalizzare il tema, aggiungere elementi di navigazione e incorporare snippet di codice per adattare la documentazione alle esigenze del tuo progetto.
Ampia community: MkDocs gode di una comunità attiva e di un ecosistema di plugin che offre ulteriori funzionalità. Puoi trovare supporto online, tutorial, e risorse aggiuntive grazie alla comunità che contribuisce continuamente al miglioramento dell'ecosistema MkDocs.

Cosa vedremo?¶

In questo tutorial, esploreremo passo dopo passo come utilizzare MkDocs per creare una documentazione pulita e facilmente navigabile per il tuo progetto. Puoi usare Mkdocs anche per poter realizzare un sito per una community (come abbiamo fatto noi 😉)

Introduzione a MkDocs
Inizializzare il progetto
Creare pagine di documentazione utilizzando il Markdown.
Personalizzare l'aspetto del tuo sito di documentazione.
Sviluppare il tuo sito in locale
Deployare il tuo sito

Alcune considerazioni personali¶

Ci sentiamo di condividere alcune considerazioni dopo aver utilizzato mkdocs sia al lavoro che qui nella community:

È un'ottima libreria che consente di ottenere buoni risultati, ma che spesso sono simili tra loro, se cerchi la personalizzazione estrema che un frontend con javascript può offrirti non fa al caso tuo
È uno strumento molto flessibile, ma è difficile a volte integrare librerie diverse che vanno in conflitto
Ci sono delle ottime e valide alternative su Python, ma spesso sono meno belle
Wordpress è sicuramente un'alternativa valida alle landing page, ma siamo nerd e ci piaccono le cose un po' nerd :) Inoltre puoi versionare il codice e i tuoi file, oltre ad essere molto più collaborativo, senza strani punta e clicca o strani plugins
Personalizzare il template per creare un proprio stile non è così facile

Tuttavia noi ci siamo trovati molto bene con la libreria, consente di realizzare degli ottimi siti web molto veloci e leggeri.

Perchè Markdown?¶

Markdown è un formato standard molto usato per creare testo ricco in maniera facile e veloce, è lo stesso formato utilizzato anche nei file README su Github in ogni repository.

Ci sono tante estensioni che consentono di arricchire Markdown, tuttavia vi consigliamo di guardare e fare pratica con la guida standard di Github, in particolare tenendo sempre sotto mano questo comodissimo cheatsheet ufficiale di Github.