MKDOCS

Mkdocs es un generador de sitios estático que esta orientado a la creación de documentación de proyectos.Los archivos fuente estan escritos en Markdown y configurado con un unico archivo de configuración YAML. Existen multitud de temas para mkdocs, se pueden consultar en la wiki de mkdocs.

Instalación

Para instalar mkdocs en su sistema necesita Python y el administrador de paquetes de python pip instalado en su sistema,en mi caso solo funciono con python3, por eso aqui hablare de python3 en lugar de python. comprobar si lo tienes instalado en tu sistema

$ python3 --version
$ pip3 --version

instalar python3 y pip3 en tu sistema

para instalar python y pip3

$ apt install python3
$ apt install pithon3-pip

instalar mkdocs

instalaremos mkdocs usando pip3

$ pip3 install mkdocs

para comprobar su esta instalado en nuestro sistema

$ mkdocs --version ejecute 

Empezando

dentro del directorio donde queremos crear el proyecto escribiremos

mkdocs new nombre_proyecto
cd nombre_proyecto

aqui no has creado el directorio docs (donde pondremos nuestros archivos md) con un index.md y un archivo que se llama mkdocs.yml que ira la configuracion de mi sitio mkdocs viene con un visor de desarrollo del proyecto dentro de la directorio del proyecto, donde esta el archivo mkdocs.yml ejecute

$ mkdocs serve

abre http://127.0.0.1:8000/ en tu navegador y veras la pagina de inicio predeterminada El servidor tambien admite la recarga, Abre el documento docs/index.md en el editor de texto de su elección, cambie el encabezado inicial a MkLorum, y guarde sus cambios. Su navegador se recargará automáticamente y debería ver su documentación actualizada inmediatamente. Ahora intente editar el archivo de configuración: mkdocs.yml. Cambie la configuración de site_name a MkLorum y guarde el archivo.

site_name: MkLorum

Su navegador debería recargarse de inmediato y verá que el nombre de su nuevo sitio surte efecto.

Añadiendo paginas

Ahora agregue una segunda página a su documentación:

curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md

Como nuestro sitio de documentación incluirá algunos encabezados de navegación, es posible que desee editar el archivo de configuración y agregar información sobre el orden, el título y el anidamiento de cada página en el encabezado de navegación agregando una configuración de páginas:

site_name: MkLorum
nav:
    - Home: index.md
    - About: about.md

Guarde sus cambios y ahora verá una barra de navegación con los elementos Inicio y Acerca de a la izquierda, así como los elementos Buscar, Anterior y Siguiente a la derecha.

Cambiar el tema

Ahora cambie el archivo de configuración para alterar cómo se muestra la documentación cambiando el tema. Edite el archivo mkdocs.yml y agregue una configuración de tema:

site_name: MkLorum
nav:
    - Home: index.md
    - About: about.md
theme: readthedocs

Guarde sus cambios y verá que se utiliza el tema ReadTheDocs.

Cambiar el icono Favicon

Por defecto, MkDocs usa el ícono favicon de MkDocs. Para usar un icono diferente, cree un subdirectorio img en su docs_dir y copie su archivo favicon.ico personalizado en ese directorio. MkDocs detectará y usará automáticamente ese archivo como su icono de favicon.

Construyendo el sitio

Está listo para implementar el primer paso de su documentación de MkLorum. Primero construya la documentación

 mkdocs build

Esto creará un nuevo directorio, llamado sitio Tenga en cuenta que su documentación de origen se ha generado como dos archivos HTML llamados index.html y about / index.html. También tiene otros medios que se han copiado en el directorio del sitio como parte del tema de la documentación. Incluso tiene un archivo sitemap.xml y mkdocs / search_index.json. Después de un tiempo, los archivos pueden eliminarse de la documentación pero seguirán residiendo en el directorio del sitio. Para eliminar esos archivos obsoletos, simplemente ejecute mkdocs con el modificador --clean.

mkdocs build --clean

Otros comandos y opciones

Hay varios otros comandos y opciones disponibles. Para obtener una lista completa de comandos, use el indicador --help:

mkdocs --help

o ver una lista de opciones disponibles en un comando dado, use el indicador --help con ese comando. Por ejemplo, para obtener una lista de todas las opciones disponibles para el comando de compilación, ejecute lo siguiente:

mkdocs build --help

Volver al inicio