Mkdocs, créez de la documentation grâce à ce logiciel open source

Dans le prochain article, nous allons jeter un œil à Mkdocs. Si vous développez un logiciel et recherchez une plateforme de création de documentation pour l'un de vos projets. Ou si vous travaillez dans une entreprise qui a besoin de créer une documentation interne pour le personnel. Même si vous êtes un utilisateur avancé qui souhaite enregistrer des notes. MkDocs est un outil que vous devriez essayer.

Ce logiciel est un générateur de site statique destiné à créer des plateformes de documentation. C'est assez simple, joli à regarder et facile à configurer et à déployer. Est écrit en python y simplement vous oblige à créer vos fichiers au format Markdown. Ensuite, à l'aide d'un seul fichier de configuration YAML, vous pouvez générer un site Web statique qui fonctionne pour vous.

Ensuite, nous verrons à quel point il est facile d'obtenir un site Web de documentation complet à l'aide de MkDocs. Il y en a beaucoup d'autres générateurs de site statique similaire, mais ce a une configuration et une implémentation des plus simples.

Un utilisateur normal peut également utiliser ce logiciel pour créer une plateforme locale pour prendre des notes pour lui-même ou pour toute autre chose similaire.

Installez MkDocs

Installer localement

Voyons que l'installation de MkDocs est assez simple. Nous pourrons installez-le à l'aide de pip. Il vous suffit d'ouvrir un terminal (Ctrl + Alt + T) et d'y écrire:

pip install mkdocs

Après l'installation, dans votre répertoire de travail, exécutez la commande suivante pour initialiser un site:

mkdocs new mkdocspro

Et puis pour commencer à le servir courir:

cd mkdocspro

mkdocs serve

Ensuite vous pouvez aller à localhost: 8000 (ou votre adresse IP / nom d'hôte avec le port 8000) pour voir comment fonctionne MkDocs.

Installez sur votre serveur nginx

Puisqu'il s'agit d'un générateur de site statique, pas besoin d'un moteur backend comme PHP ou Python. Vous pourrez implémenter le projet MkDocs sur votre serveur web (nginx, apache2) en une minute. Par exemple, voici le configuration de l'hôte virtuel nginx:

server {
        server_name ejemplo.com;

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

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

Remplace ejemplo.com avec le domaine que vous avez sur votre serveur. Vous devrez également changer / var / www / mkdocspro / site par le chemin du sous-dossier du site sur votre serveur. Alors nous n'avons que redémarrer nginx avec la commande suivante:

sudo service nginx restart

Vous pouvez maintenant vous rendre sur example.com et le voir fonctionner.

Installer un autre thème dans Mkdocs

Le thème Mkdocs par défaut n'est pas particulièrement bon. Mais vous pouvez en installer un autre en une minute. Un exemple d'installation d'un autre thème, sera le suivant. Avec lequel nous allons installer le thème matériel:

pip install mkdocs-material

Après l'installation, pour activer le thème, vous devrez modifiez votre fichier mkdocs.yml et rendez-le similaire à celui-ci. Certaines options peuvent être ajoutées:

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 options sont assez claires. Mais voici quelques explications:

• dépôt_url: est le URL du référentiel Git. Si vous prévoyez d'intégrer Git directement dans votre projet MkDocs, vous pouvez utiliser cette option pour permettre aux utilisateurs de modifier les pages ou de créer un fork du projet.
• edit_uri: C'est lui postfix pour éditer des pages sur GitHub. Vous pouvez le modifier si vous utilisez GitLab ou GitBucket.
• Google Analytics: Il n'y a pas de panneau de contrôle pour MkDocs. Par conséquent, pour savoir qui visite votre site Web, vous devez utiliser Google Analytics. Cette option vous permettra d'insérer votre numéro de suivi pour associer votre compte au site Web.
• Disqus: Si tu veux activer le système de commentaires Disqus sur le site Web, vous pouvez insérer votre nom abrégé ici.
• thème: L' nom du thème que vous souhaitez utiliser. Vous devrez l'installer au préalable, comme nous venons de le faire avec le thème matériel. Ce sera le nom que nous utiliserons dans l'exemple.

Voir les changements du nouveau thème

Après avoir enregistré le fichier, exécuter mkdocs build dans le dossier mkdocsproject. Votre site Web adoptera l'aspect et la convivialité par défaut du thème Matériel:

Important: assurez-vous de toujours exécuter mkdocs build après chaque modification que vous faites dans les fichiers. Sinon, vous ne verrez aucun changement.

Il ya beaucoup de autres thèmes et options pour configurer ce logiciel. Vous pouvez les consulter dans le documentation officielle par MkDocs. Voici une liste de options possibles que nous pouvons utiliser.