{"id":4104,"date":"2021-05-03T17:44:56","date_gmt":"2021-05-03T15:44:56","guid":{"rendered":"https:\/\/esferas.org\/msqlu\/?p=4104"},"modified":"2021-05-03T17:44:57","modified_gmt":"2021-05-03T15:44:57","slug":"mkdocs-paginas-web-para-documentacion","status":"publish","type":"post","link":"https:\/\/esferas.org\/msqlu\/2021\/05\/03\/mkdocs-paginas-web-para-documentacion\/","title":{"rendered":"mkdocs: p\u00e1ginas web para documentaci\u00f3n"},"content":{"rendered":"\n

Empleando el lenguaje de marcado markdown<\/a>, con paquetes Debian y m\u00e1s simple y r\u00e1pido que cualquier otra cosa que he visto antes. <\/p>\n\n\n\n\n\n\n\n

Llevaba la tira de tiempo intentando agrupar toda la documentaci\u00f3n -legal y de referencia- sobre protecci\u00f3n de datos en mi lugar de trabajo y en otro par de sitios m\u00e1s en los que tengo instalaciones personales. La idea b\u00e1sica era tener primero el contenido y luego darle forma y para ello nada mejor que un lenguaje sencillo para escribir los textos con posibilidades despu\u00e9s de darle forma y vestirlo. <\/p>\n\n\n\n

Estuve mirando unos cuantos programas del tipo generador de sitios web est\u00e1ticos y no consegu\u00eda arrancar ni entender casi ninguno. He usado Hugo<\/a> en otros proyectos de p\u00e1ginas de inicio y prob\u00e9 primero con \u00e9l sin conseguir centrarme en el contenido ni lo m\u00e1s m\u00ednimo. Hugo, como ya hab\u00eda le\u00eddo por ah\u00ed, se ha vuelto un monstruo bastante dif\u00edcil de gestionar. Es el t\u00edpico ejemplo de martillo preciso y bien equilibrado que terminamos usando para operaciones de neurocirug\u00eda porque le podemos ir a\u00f1adiendo extensiones. No. As\u00ed no. <\/p>\n\n\n\n

Tampoco con Jekyll<\/a> ni con PicoCMS<\/a>. Con el primero me ech\u00f3 para atr\u00e1s la propia documentaci\u00f3n y los temas tan coloridos. Con el segundo estuve chocando en la instalaci\u00f3n una y otra vez sin conseguir despreocuparme de la forma; tarde o temprano hab\u00eda detalles tontos como el logotipo que eran casi imposibles. Al menos en tres sitios de la configuraci\u00f3n encontr\u00e9 c\u00f3mo cambiarlo sin llegar a hacerlo del todo en ninguno de ellos. Una l\u00e1stima porque he visto que tiene integraci\u00f3n con Nextcloud<\/a> y me ven\u00eda de perlas para poder crear p\u00e1ginas web integradas en el programa. P\u00e1ginas con contenido que s\u00f3lo podr\u00edan ver unos u otros usuarios siempre que abriesen sesi\u00f3n en el servidor. Bueno, a\u00fan no he probado qu\u00e9 tal se desenvuelve. S\u00f3lo espero que de verdad est\u00e9 bien integrado.<\/p>\n\n\n\n

Pero a lo que iba, el programa mkdocs<\/a> ha sido una aut\u00e9ntica salvaci\u00f3n. En menos de un d\u00eda he constru\u00eddo el sitio para la empresa con casi toda la documentaci\u00f3n sobre protecci\u00f3n de datos. No toda, ojo, que me queda un buen pu\u00f1ado de formularios para imprimir y reclamar derechos y otro par de lotes de textos legales que parecen sacados de primeros del siglo anterior. <\/p>\n\n\n\n

Para construir el sitio se instala primero el paquete mkdocs y tal vez alguno m\u00e1s si se quiere cambiar el tema o disponer de la documentaci\u00f3n y en un directorio se procede a a\u00f1adir contenido. Y ya. O casi, porque se configura con un archivo YAML<\/em> en el que conviene cambiar el t\u00edtulo, la URL, el autor y cuatro cosas m\u00e1s para diferenciarlo. <\/p>\n\n\n\n

Con una \u00fanica llamada al programa se construye el sitio web incluyendo hojas de estilo, tipograf\u00edas y fuentes javascript. El contenido se define con markdown<\/em> y la estructura se mantiene tan simple como la siguiente:<\/p>\n\n\n\n

victor@falcata:~\/git\/rgpd.venexma.es$ tree docs\/\ndocs\/\n\u251c\u2500\u2500 aviso-legal\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 blog.venexma.es.md\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 boletines.venexma.es.md\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 forms.venexma.es.md\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 index.md\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 outlet.venexma.com.md\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 suelaexpress.com.md\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 venexma.com.md\n\u251c\u2500\u2500 cookies\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 index.md\n\u251c\u2500\u2500 descargas\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 formulario-derecho-de-acceso.docx\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 formulario-derecho-de-acceso.pdf\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 index.md\n\u251c\u2500\u2500 img\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 favicon.ico\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 venexma.png\n\u251c\u2500\u2500 index.md\n\u251c\u2500\u2500 segunda-capa\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 index.md\n\u2514\u2500\u2500 terminos\n\n6 directories, 15 files\n<\/pre>\n\n\n\n
Un ejemplo de p\u00e1gina sencilla ser\u00eda la de descargas:<\/p>\n\n\n\n
## Descargas \n\n### Formularios en PDF \n\n* [Derecho de acceso](\/descargas\/formulario-derecho-de-acceso.pdf)\n\n\n### Formularios en formato DOC\n\n* [Derecho de acceso](\/descargas\/formulario-derecho-de-acceso.docx)\n\n<\/code><\/pre>\n\n\n\n
Una vez construido el sitio \u00e9l solo se encarga de darle la forma y la navegaci\u00f3n:<\/p>\n\n\n\n
\"\"<\/a><\/figure><\/div>\n\n\n\n
El tema predeterminado incluye una barra lateral de navegaci\u00f3n que se puede definir en la configuraci\u00f3n de la siguiente forma:<\/p>\n\n\n\n
site_name: GRPD - Venexma Europa, S.L.\nsite_url: https:\/\/rgpd.venexma.es\nsite_description: Documentaci\u00f3n sobre protecci\u00f3n de datos\nsite_author: Venexma Europa, S.L.\ncopyright: (c) 2021 Venexma Europa, S.L.\nuse_directory_urls: false\nnav:\n    - Primera capa: index.md\n    - Segunda capa: segunda-capa\/index.md\n    - Avisos legales: aviso-legal\/index.md\n    - Pol\u00edtica de cookies: cookies\/index.md\n    - Descargas: descargas\/index.md\ntheme: \n    name: readthedocs\n    include_sidebar: true\n    prev_next_buttons_location: both\nplugins:\n    - search:\n        lang: en\n<\/code><\/pre>\n\n\n\n
M\u00e1s ventajas<\/h3>\n\n\n\n
Con lo anterior se consigue un \u00e1rbol de archivos que pueden servirse directamente desde un Apache o un Nginx a la velocidad m\u00e1xima porque es est\u00e1tico de verdad. El javascript tambi\u00e9n puede eliminarse pero molesta muy poco y proporciona ventajas como la b\u00fasqueda sobre los documentos. <\/p>\n\n\n\n
El programa tambi\u00e9n puede servir en el puerto local 8000 una copia en vivo del sitio por lo que depurarlo se convierte en algo muy sencillo. No s\u00f3lo ves el contenido, tambi\u00e9n los errores en direcciones y archivos. <\/p>\n\n\n\n
Un ejemplo de ello es la siguiente captura<\/p>\n\n\n\n
\"\"<\/a>
mkdocs serve<\/figcaption><\/figure><\/div>\n\n\n\n
Y luego est\u00e1n las b\u00fasquedas. B\u00fasquedas sobre los documentos que no<\/strong> necesitan scripts<\/em> en el servidor. Para ello construye un diccionario en formato JSON en el directorio final como se puede ver a continuaci\u00f3n:<\/p>\n\n\n\n
victor@falcata:~\/git\/rgpd.venexma.es\/site$ tree -s  search\nsearch\n\u251c\u2500\u2500 [     100219]  lunr.js\n\u251c\u2500\u2500 [       2766]  main.js\n\u251c\u2500\u2500 [     293615]  search_index.json\n\u2514\u2500\u2500 [       3585]  worker.js\n\n0 directories, 4 files\n<\/pre>\n\n\n\n
Y lo cierto es que funciona muy bien, tanto que puede llevarse en una unidad de disco contigo y abrirlo en local con un navegador. Es verdad que si la documentaci\u00f3n es muy extensa, tipo libro, las b\u00fasquedas ser\u00e1n m\u00e1s pesadas y m\u00e1s lentas pero creo que merece la pena para no tener que instalar nada en el servidor. <\/p>\n\n\n\n
Y por \u00faltimo est\u00e1 la opci\u00f3n de construir la documentaci\u00f3n de tu programa e incluirla en el paquete Debian correspondiente. Se incluye el programa dh_mkdocs para debhelper por lo que una vez instalado la integraci\u00f3n es completa en el sistema. Adem\u00e1s, al crear URL fijos se puede usar como sistema de ayuda en l\u00ednea para cualquier desarrollo. Es justo lo que estaba buscando tiempo atr\u00e1s. <\/p>\n\n\n\n
As\u00ed que s\u00ed, ha sido un gran descubrimiento que ten\u00eda al alcance de mi mano y que hasta que no he hecho una b\u00fasqueda un poco retorcida en la web no lo he encontrado<\/a>. <\/p>\n","protected":false},"excerpt":{"rendered":"
Empleando el lenguaje de marcado markdown, con paquetes Debian y m\u00e1s simple y r\u00e1pido que cualquier otra cosa que he visto antes.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_import_markdown_pro_load_document_selector":0,"_import_markdown_pro_submit_text_textarea":"","webmentions_disabled_pings":false,"webmentions_disabled":false,"footnotes":""},"categories":[2],"tags":[85,734,1099,44],"class_list":["post-4104","post","type-post","status-publish","format-standard","hentry","category-software","tag-documentacion","tag-markdown","tag-mkdocs","tag-servicios-web"],"_links":{"self":[{"href":"https:\/\/esferas.org\/msqlu\/wp-json\/wp\/v2\/posts\/4104","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/esferas.org\/msqlu\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/esferas.org\/msqlu\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/esferas.org\/msqlu\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/esferas.org\/msqlu\/wp-json\/wp\/v2\/comments?post=4104"}],"version-history":[{"count":4,"href":"https:\/\/esferas.org\/msqlu\/wp-json\/wp\/v2\/posts\/4104\/revisions"}],"predecessor-version":[{"id":4112,"href":"https:\/\/esferas.org\/msqlu\/wp-json\/wp\/v2\/posts\/4104\/revisions\/4112"}],"wp:attachment":[{"href":"https:\/\/esferas.org\/msqlu\/wp-json\/wp\/v2\/media?parent=4104"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/esferas.org\/msqlu\/wp-json\/wp\/v2\/categories?post=4104"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/esferas.org\/msqlu\/wp-json\/wp\/v2\/tags?post=4104"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}