Mkdocs, crea documentació gràcies a aquest programari de codi obert

En el següent article anem a fer una ullada a Mkdocs. Si desenvolupes programari i busques una plataforma per crear documentació per un dels teus projectes. O si treballes en una empresa que necessita crear una documentació interna per al personal. Fins i tot si ets un usuari avançat que vol guardar algunes notes. MkDocs és una eina que hauries de provar.

Aquest programari és un generador de llocs estàtics orientat a la creació de plataformes de documentació. És bastant simple, bonic de veure i fàcil de configurar i desplegar. està escrit en Python i simplement requereix que creus els teus arxius en format Markdown. Després, utilitzant un sol arxiu de configuració YAML, pots generar un lloc web estàtic que funcioni per a tu.

A continuació anem a veure el fàcil que és obtenir un lloc web complet de documentació utilitzant MkDocs. Hi ha molts altres generadors de llocs estàtics similars, però aquest té una configuració i implementació de les més senzilles.

Un usuari normal també podria usar aquest programari per crear una plataforma local per prendre notes per a si mateix o qualsevol altra cosa semblant.

instal·lar MkDocs

instal·lar localment

Anem a veure que instal·lar MkDocs és bastant fàcil. podrem instal·lar utilitzant pip. Només cal obrir una terminal (Ctrl + Alt + T) i escriure-hi:

pip install mkdocs

Després de la instal·lació, en el teu directori de treball, executa la següent comanda per inicialitzar un lloc:

mkdocs new mkdocspro

I després, per començar a servir- executa:

cd mkdocspro

mkdocs serve

A continuació, ja pots anar a localhost: 8000 (o la teva adreça IP / nom de host amb el port 8000) Per veure com funciona MkDocs.

Instal·lar en el teu servidor nginx

Atès que aquest és un generador de lloc estàtic, no es necessita un motor de back-end com PHP o Python. Podràs implementar el projecte MkDocs en el teu servidor web (nginx, apache2) en un minut. Per exemple, aquí hi ha la configuració de l'amfitrió virtual nginx:

server {
        server_name ejemplo.com;

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

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

reemplaça exemple.com amb el domini que tens al teu servidor. També hauràs de canviar / Var / www / mkdocspro / lloc per la ruta de la subcarpeta de el lloc en el teu servidor. Després només ens queda reiniciar nginx amb la següent comanda:

sudo service nginx restart

Ara pots dirigir-te a ejemplo.com i veure-ho funcionar.

Instal·la altre tema en Mkdocs

El tema predeterminat de Mkdocs no és especialment bo. Però pots instal·lar un altre en un minut. Un exemple d'instal·lació d'un altre tema, serà el següent. Amb el que anem a instal·lar el tema material:

pip install mkdocs-material

Després de la instal·lació, per activar el tema, caldrà editar el seu arxiu mkdocs.yml i fer-ho semblant a aquest. Es poden afegir algunes opcions:

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'

Les opcions són bastant clares. Però aquí van algunes explicacions:

• repo_url: És la URL de l'repositori de Git. Si planeges integrar Git directament en el teu projecte de MkDocs, pots fer servir aquesta opció per permetre que les persones editin les pàgines o bifurquin el projecte.
• edit_uri: Aquest és el postfix per editar pàgines en GitHub. Pots canviar si estàs fent servir GitLab o GitBucket.
• google_analytics: No hi ha tauler de control per MkDocs. Per tant, per saber qui visita el teu lloc web, hauràs d'utilitzar Google Analytics. Aquesta opció et permetrà inserir el seu nombre de seguiment per associar el teu compte amb el lloc web.
• disqus: Si vols habilitar el sistema de comentaris de Disqus en el lloc web, podreu escriure el vostre nom curt aquí.
• tema: El nom del tema que vols fer servir. Hauràs de instal·lar prèviament, com acabem de fer amb el tema material. Aquest serà el nom que utilitzarem en l'exemple.

Veure els canvis de el nou tema

Després de guardar l'arxiu, executa mkdocs build dins de la carpeta mkdocsproject. El teu lloc web adoptarà l'aparença i l'estil per defecte de el tema Material:

Important: assegura't d'executar mkdocs build sempre després de cada modificació que facis en els arxius. En cas contrari no veuràs cap canvi.

hi ha molts altres temes i opcions per configurar aquest programari. Pot consultar-los a la documentació oficial de MkDocs. Aquí hi ha una llista de possibles opcions que podem utilitzar.