Material for mkdocs es un "framework" para crear materiales muy profesionales a partir de ficheros en markdown muy fácil de usar, configurar y muy vistoso.
La página base de "material for mkdocs" es : https://squidfunk.github.io/mkdocs-material/
Aquí un ejemplo de un compañero:
https://raul-profesor.github.io/DEAW/
Los pasos básicos para poder usarlo son:
- Antes de hacer nada tienes que tener cuenta en github. Así que lo primero créatela.
- Y después instalar Python en tu equipo. https://www.python.org/ Descarga e instala.
- Y no es imprescindible pero si recomendado usar Ms Visual Studio. Así que descarga e instala también. Es muy recomendable configurarlo para que automáticamente se conecte a tu cuenta GitHub. No lo explico aquí.
- Ahora ya puedes ir a https://squidfunk.github.io/mkdocs-material/getting-started/ y seguir el proceso:
- Crea un virtual environment de Python. Aquí dice como https://realpython.com/what-is-pip/#using-pip-in-a-python-virtual-environment . Básicamente es (linux):
- $ python3 -m venv venv //Eso creará un directorio llamado venv allí donde lo ejecutes. Cada vez que vayas a usarlo deberás activarlo en esa ruta. Así que si lo ejecutas en el raíz de tu usuario /home/Pp se creará /home/Pp/venv
- Esto se hace sólo una vez
- Cada vez que vayas a usarlo habrás de activarlo con:
- $ source venv/bin/activate
- Si lo has creado en el raíz de tu usuario podrás activarlo siempre con $ source /home/Pp/venv/bin/activate
- Y esto no lo dice en ningún sitio, pero cuando acabes de trabajar, desactivalo con
- $ deactivate
- Una vez dentro del entorno virtual (lo verás porque aparece (venv) delante del prompt: (venv) $ ) procedes a la instalación de mkdocs-material. Esto tb se hace solo una vez:
- (venv) $ pip install mkdocs-material
- Si todo ha ido bien ya tienes en entorno instalado. Ahora sigue el vídeo que hay en la página de “getting-started" https://www.youtube.com/watch?v=Q-YA_dA8C20 Yo te recomiendo crear una página de prueba siguiendo el vídeo
- En el video llega un momento que crea un archivo .github/workflows/ci.yml y pega unos contenidos. Están en "https://squidfunk.github.io/mkdocs-material/publishing-your-site/“ Sólo es copiar y pegar.
- Y con esto ya tendrás una página “up & running”. Luego querrás cambiar colores, hacer que el menú de la izquierda sea como tu quieras… En la web de mkdocs-material tienes mucha información.