🚀 Generador de sitios web estáticos MkDocs.
Tabla de Contenido
Introducción
MkDocs es una herramienta para generar sitios web simples y rápidos enfocados en sitios para documentación, utiliza archivos Markdown.
Instalación
Para realizar la instalación de MkDocs es importante completar algunos requisitos previos.
Prerrequisitos
- MkDocs requiere de tener instalado Python , recomendable una versión reciente.
~ $ python --version
Python 3.11.7
- Tener instalado el administrador de paquetes pip .
~ $ pip --version
pip 24.2 from /Users/.pyenv/versions/3.11.7/lib/python3.11/site-packages/pip (python 3.11)
- si se requiere actualizar, se puede realizar mediante el siguiente comando:
pip install --upgrade pip
Instalar MkDocs
Para instalar MkDocs se necesita ejecutar el siguiente comando con pip:
pip install mkdocs
Para verificar que quedó correctamente instalado, se puede realizar con el comando:
~ $ mkdocs --version
mkdocs, version 1.6.0 from /Users/.pyenv/versions/3.11.7/lib/python3.11/site-packages/mkdocs (Python 3.11)
Creación de sitio web
Para crear un sitio web con MkDocs es simplemente ejecutar el siguiente comando en el directorio que lo desea generar:
$ mkdocs new first-site
INFO - Creating project directory: first-site
INFO - Writing config file: first-site/mkdocs.yml
INFO - Writing initial docs: first-site/docs/index.md
Ingresar al directorio generado first-site con el comando cd first-site . Se crea la estructura.
docsen este directorio van todos los archivos con el contenido del proyecto, inicialmente se genera con elindex.mdcomo ejemplo.mkdocs.ymles el archivo de configuración del proyecto.
Despliegue del sitio
Para iniciar el proyecto es suficiente con ejecutar el siguiente comando en el directorio raíz:
$ mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
INFO - Documentation built in 0.05 seconds
INFO - [19:26:16] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO - [19:26:16] Serving on http://127.0.0.1:8000/
Ingresamos a la url: http://127.0.0.1:8000/. Al ingresar en el navegador se abrirá el sitio en la máquina local.
En caso de querer parar el servidor, basta con presionar las teclas Ctrl + C .
Construcción del sitio
Para compilar los archivos del sitio web y poderlos subir a una web o hosting, se puede lograr ejecutando el comando:
$ mkdocs build
INFO - Cleaning site directory
INFO - Building documentation to directory:
/Users/development/mkdocs/first-site/site
INFO - Documentation built in 0.05 seconds
Esto generará un directorio site con todos archivos necesarios para subirlos en un sitio web productivo.
Configuraciones
En el archivo de configuración mkdocs.yml está inicialmente la propiedad site_name la cual identifica el nombre que se mostrará de su sitio en la pestaña del navegador.
Para agregar otra pestaña a la página se puede realizar agregando una propiedad en el archivo mkdocs.yml, como por ejemplo: nav para el menú superior. Se necesita un archivo en docs/blog.md.
site_name: Mi sitio
nav:
- Inicio: index.md
- Blog: blog.md
Temas
- Por defecto MkDocs viene con Bootstrap como tema.
- Se puede utilizar otro como readthedocs .
theme:
name: readthedocs
- También existe otras opciones de temas: https://github.com/mkdocs/catalog .
Para instalarlos basta con ingresar a la documentación de cada uno y seguir los pasos, en este caso instalaremos material que tienen sitios de documentación como FastAPI .
- Ejecutar el comando:
pip install mkdocs-material
- Configurar tema:
theme:
name: material
Conclusión
Para concluir, podemos decir que MkDocs es una gran opción para documentar algún tipo de proyecto, donde se pueda hacer referencia al funcionamiento de cada detalle del mismo.
Referencias
Conclusión
En conclusión, Hugo es una excelente alternativa para generar sitios web estáticos que sean rápidos y con una curva de aprendizaje baja para crear nuestro sitio web.
