Mkdocs, skapa dokumentation tack vare denna programvara med öppen källkod

I nästa artikel ska vi ta en titt på Mkdocs. Om du utvecklar programvara och söker en plattform för att skapa dokumentation för ett av dina projekt. Eller om du arbetar i ett företag som behöver skapa intern dokumentation för personalen. Även om du är en avancerad användare som vill spara några anteckningar. MkDocs är ett verktyg som du bör prova.

Denna programvara är en statisk webbplatsgenerator som syftar till att skapa dokumentationsplattformar. Det är ganska enkelt, vackert att titta på och lätt att installera och distribuera. Är skrivet i python och helt enkelt kräver att du skapar dina filer i Markdown-format. Med en enda YAML-konfigurationsfil kan du sedan skapa en statisk webbplats som fungerar för dig.

Därefter kommer vi att se hur lätt det är att få en fullständig dokumentationswebbplats med MkDocs. Det finns många andra webbplatsgeneratorer liknande statisk, men detta har en konfiguration och implementering av det enklaste.

En vanlig användare kan också använda denna programvara för att skapa en lokal plattform för att göra anteckningar för sig själv eller något liknande.

Installera MkDocs

Installera lokalt

Låt oss se att det är ganska enkelt att installera MkDocs. Vi kan installera den med pip. Du måste bara öppna en terminal (Ctrl + Alt + T) och skriva i den:

pip install mkdocs

Efter installationen, i din arbetskatalog, kör följande kommando till initialisera en webbplats:

mkdocs new mkdocspro

Och sedan för börja servera den springa:

cd mkdocspro

mkdocs serve

Då kan du gå till localhost: 8000 (eller din IP-adress / värdnamn med port 8000) för att se hur MkDocs fungerar.

Installera på din nginx-server

Eftersom detta är en statisk generator, ingen backend-motor behövs som PHP eller Python. Du kommer att kunna implementera MkDocs-projektet på din webbserver (nginx, apache2) på en minut. Till exempel är här nginx virtuell värdkonfiguration:

server {
        server_name ejemplo.com;

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

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

Ersätter exempel.com med den domän du har på din server. Du måste också ändra / var / www / mkdocspro / site genom sökvägen till undermappen på webbplatsen på din server. Då har vi bara starta om nginx med följande kommando:

sudo service nginx restart

Nu kan du gå över till example.com och se att det fungerar.

Installera ett annat tema i Mkdocs

Standardtema Mkdocs är inte särskilt bra. Men du kan installera en annan på en minut. Ett exempel på installation av ett annat tema är följande. Med vilken vi ska installera materialtema:

pip install mkdocs-material

Efter installationen måste du aktivera temat redigera din mkdocs.yml-fil och gör den liknande den här. Några alternativ kan läggas till:

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'

Alternativen är helt tydliga. Men här är några förklaringar:

• repo_url: är Git-förvarets URL. Om du planerar att integrera Git direkt i ditt MkDocs-projekt kan du använda det här alternativet för att låta folk redigera sidorna eller dela upp projektet.
• edit_uri: Det här är postfix för redigering av sidor på GitHub. Du kan ändra det om du använder GitLab eller GitBucket.
• google_analytics: Det finns ingen kontrollpanel för MkDocs. Därför att veta som besöker din webbplats måste du använda Google Analytics. Med det här alternativet kan du infoga ditt spårningsnummer för att associera ditt konto till webbplatsen.
• Disqus: Om du vill aktivera Disqus kommentarsystem på webbplatsen kan du infoga ditt korta namn här.
• tema: Den namnet på temat du vill använda. Du måste installera det tidigare, precis som vi gjorde med materialtemat. Detta är namnet som vi kommer att använda i exemplet.

Se ändringarna av det nya temat

Efter att ha sparat filen, kör mkdocs build inuti mappen mkdocsproject. Din webbplats kommer att anta standardutseendet och känslan för materialtemat:

Viktigt: se till att alltid köra mkdocs build efter varje modifiering som du gör i filerna. Annars ser du ingen förändring.

det finns många andra teman och alternativ för att konfigurera denna programvara. Du kan konsultera dem i officiell dokumentation av MkDocs. Här är en lista över möjliga alternativ som vi kan använda.