Mkdocs, crea documentazione grazie a questo software open source

Nel prossimo articolo daremo uno sguardo a Mkdocs. Se sviluppi software e cerchi una piattaforma per la creazione di documentazione per uno dei tuoi progetti. Oppure se lavori in un'azienda che ha bisogno di creare documentazione interna per il personale. Anche se sei un utente avanzato che vuole salvare alcune note. MkDocs è uno strumento che dovresti provare.

Questo software è un generatore di siti statici finalizzato alla creazione di piattaforme di documentazione. È piuttosto semplice, bello da vedere e facile da configurare e distribuire. È scritto in pitone e semplicemente richiede di creare i file in formato Markdown. Quindi, utilizzando un singolo file di configurazione YAML, puoi generare un sito Web statico che funzioni per te.

Successivamente vedremo quanto è facile ottenere un sito Web completo di documentazione utilizzando MkDocs. Ce ne sono molti altri generatori di siti statica simile, ma questa ha una configurazione e implementazione delle più semplici.

Un utente normale potrebbe anche utilizzare questo software per creare una piattaforma locale per prendere appunti per se stesso o per qualsiasi altra cosa simile.

Installa MkDocs

Installa localmente

Vediamo che l'installazione di MkDocs è abbastanza semplice. Lo faremo installalo usando pip. Devi solo aprire un terminale (Ctrl + Alt + T) e scrivere in esso:

pip install mkdocs

Dopo l'installazione, nella directory di lavoro, eseguire il seguente comando su inizializzare un sito:

mkdocs new mkdocspro

E poi per inizia a servirlo correre:

cd mkdocspro

mkdocs serve

Allora puoi vai a localhost: 8000 (o il tuo indirizzo IP / nome host con la porta 8000) per vedere come funziona MkDocs.

Installa sul tuo server nginx

Poiché si tratta di un generatore di siti statici, nessun motore di backend necessario come PHP o Python. Sarai in grado di implementare il progetto MkDocs sul tuo server web (nginx, apache2) in un minuto. Ad esempio, ecco il file Configurazione dell'host virtuale nginx:

server {
        server_name ejemplo.com;

        root /var/www/mkdocspro/sitio;
        index index.html;

        location / {
                try_files $uri $uri/ =404;
        }
}

Sostituisce ejemplo.com con il dominio che hai sul tuo server. Dovrai anche cambiare / var / www / mkdocspro / site dal percorso della sottocartella del sito sul tuo server. Allora abbiamo solo riavvia nginx con il seguente comando:

sudo service nginx restart

Ora puoi andare su example.com e vederlo funzionare.

Installa un altro tema in Mkdocs

Il tema predefinito di Mkdocs non è particolarmente buono. Ma puoi installarne un altro in un minuto. Un esempio di installazione di un altro tema, sarà il seguente. Con cui andremo installa il tema del materiale:

pip install mkdocs-material

Dopo l'installazione, per attivare il tema, dovrai farlo modifica il tuo file mkdocs.yml e rendilo simile a questo. Alcune opzioni possono essere aggiunte:

site_name: Proyecto MkDocs
site_url: 'http://ejemplo.com'
repo_url: 'https://github.com/nombreusuario/proyectourlongithub'
edit_uri: edit/master
site_description: 'Aquí una descripción corta.'
google_analytics: ['UA-xxxxxxxxx-x', 'ejemplo.com']
extra:
  favicon: 'https://ejemplo/favicon.png'
  social:
    - type: 'github'
      link: 'https://github.com/xxxxxx'
    - type: 'facebook'
      link: 'https://facebook.com/xxxxxxx'
    - type: 'twitter'
      link: 'https://twitter.com/xxxxxxx'
  disqus: 'minombredisqus'
  theme: 'material'

Le opzioni sono abbastanza chiare. Ma ecco alcune spiegazioni:

• repository_url: è il URL del repository Git. Se prevedi di integrare Git direttamente nel tuo progetto MkDocs, puoi usare questa opzione per consentire alle persone di modificare le pagine o fare il fork del progetto.
• modifica_uri: Questo è il suffisso per la modifica delle pagine su GitHub. Puoi cambiarlo se stai usando GitLab o GitBucket.
• google_analytics: Non esiste un pannello di controllo per MkDocs. Pertanto, per sapere chi visita il tuo sito web, devi utilizzare Google Analytics. Questa opzione ti permetterà di inserire il tuo numero di tracciamento per associare il tuo account al sito web.
• Disqus: Se vuoi abilitare il sistema di commenti di Disqus sul sito web, puoi inserire qui il tuo nome breve.
• tema: L' nome del tema che desideri utilizzare. Dovrai installarlo in precedenza, come abbiamo appena fatto con il tema del materiale. Questo sarà il nome che useremo nell'esempio.

Guarda le modifiche del nuovo tema

Dopo aver salvato il file, eseguire mkdocs build all'interno della cartella mkdocsproject. Il tuo sito web adotterà l'aspetto predefinito del tema Materiale:

Importante: assicurati di eseguire sempre mkdocs build dopo ogni modifica che fai nei file. Altrimenti non vedrai alcun cambiamento.

Ci sono molti altri temi e opzioni per configurare questo software. Puoi consultarli nel documentazione ufficiale di MkDocs. Ecco un elenco di possibili opzioni che possiamo usare.