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