Instalar MkDocs con Python y virtualenv

01. Verifica si Python y virtualenv están instalados de forma global y si no aparecen, instalalos.

02. Entra en “escritorio” y crea una carpeta de trabajo que se llame (proyecto-docs) con el comando (mkdir proyecto-docs).

03. Entra en “proyecto-docs” y crea una carpeta virtual que se llame (env).

04. Actíva la carpeta “env” en modo virtual con el comando (.\env\scripts\activate).

05. Instala la librería dentro de la carpeta “env” con el comando (pip install mkdocs).

06. Verifica si la librería mkdocs se instaló bien.

07. Crea nuevo proyecto de mkdocs que se llame (mi-documentacion).

08. Verifica si el proyecto se creó bien y desactiva el entorno virtual con el comando (deactivate). Cierra la terminal.

09. Abre VSCode y carga la carpeta del escritorio “proyecto-docs” desde el menu superior (Archivo / Abrir carpeta…).

10. Dentro del proyecto “mi-documentacion”, abre el archivo que pone index.md.

11. Abre una nueva terminal desde el menu superior (... / Terminal / Nuevo terminal) para ejecutar el servidor en local. Recordar que la librería mkdocs se instaló en un entorno virtual por lo que sera necesario primero activar el entorno virtual desde la carpeta de trabajo “proyecto-docs” con el comando (.\env\Scripts\activate). Luego entra en la carpeta del proyecto “mi-documentación” y desde ahí, ejecutar el siguiente comando (mkdocs serve), esto ejecutara el servidor local.

12. Para verificar, copia la URL del servidor y abre en el navegador, le aparecerá la página de bienvenida por defecto.

13. Con esto, ya tendrias instalado la librería mkdocs en un entorno virtual y creado el proyecto para empezar a editar tu propia documentación, porfolio, o lo que quieras de forma local.

14. Ahora que ya tenemos mkdocs en marcha, toca instalar un tema desarrollado para mkdocs que le va dar un diseño mucho mas moderno. Abre la terminal de VSCode, pulsa (ctrl + c) para detener el servidor, activa el entorno virtual, accede a la carpeta “mi-documentación” y desde ahí ejecuta el comando (pip install mkdocs-material). Una vez terminada la instalación, abre el archivo “mkdocs.yml” y modifica el nombre del tema. En este caso, se llama material. El tema que viene instalado por defecto se llama “readthedocs”.

15. Para finalizar, recarga la página y veras un aspecto mucho mas moderno de tu sitio web.