Diferencias

Muestra las diferencias entre dos versiones de la página.

--- informatica:software:mkdocs [2021/11/30 15:33] – creado tempwin
+++ informatica:software:mkdocs [2023/03/07 09:00] (actual) – [Material for MkDocs] tempwin
@@ Línea 1: / Línea 1: @@
 ====== MkDocs ======
-Generador de sitios web estáticos centrado en la construcción de documentación.
+Generador de sitios web estáticos escrito en Python y centrado en la construcción de documentación.
-La documentación se escribe con la sintaxis Markdown.
+La documentación se escribe con la sintaxis [[informatica:markdown|Markdown]].
   * [[https://www.mkdocs.org/|Web oficial]]
+===== Instalación =====
+<code>
+pip install mkdocs
+</code>
+===== Uso =====
+Para crear un nuevo proyecto:
+<code>
+mkdocs new miproyecto
+cd miproyect
+</code>
+Veremos que se ha generado la siguiente estructura:
+<code>
+miproyecto/
+├── docs
+│   └── index.md
+└── mkdocs.yml
+</code>
+  * ''mkdocs.yml'': fichero de configuración.
+  * ''docs'': por defecto, el directorio que contendrá la documentación
+  * ''index.md'': página con documentación.
+Para previsualizar, podemos utilizar el servidor web que incluye mkdocs ejecutando, dentro del proyecto, lo siguiente:
+<code>
+mkdocs serve
+</code>
+Eso construirá la documentación y la tendremos accesible desde http://localhost:8000
+==== Escribir documentación ====
+Lo mínimo es que exista un fichero ''index.md'' dentro del directorio ''docs''. Luego podemos organizar la documentación como queramos:
+<code>
+miproyecto/
+├── docs
+│   └── index.md
+│   └── pagina2.md
+│   └── pagina3.md
+</code>
+Incluso anidando ficheros Markdown en varios directorios:
+<code>
+docs/
+    index.md
+    user-guide/getting-started.md
+    user-guide/configuration-options.md
+    license.md
+</code>
+==== Generar sitio estático ====
+<code>
+mkdocs build
+</code>
+Esto creará un directorio llamado ''site'' donde se habrá generadon los ficheros necesarios para poder subirlos a cualquier servidor web y servir la documentación.
+===== Temas =====
+Una vez instalados, se usan indicándolo en el fichero de configuración ''mkdocs.yml'':
+<code yaml>
+theme:
+    name: material
+</code>
+  * [[https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes|Listado de temas para MkDocs]]
+==== Material for MkDocs ====
+  * https://squidfunk.github.io/mkdocs-material/
+Para instalar este tema (también instala todas las dependencias como el propio MkDocs):
+<code>
+pip install mkdocs-material
+</code>
+Para incluir admonitions (mensajes importantes):
+<code yaml>
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+</code>
+Para traducir al español:
+<code yaml>
+theme:
+    name: material
+    language: es
+</code>