mdBook: herramienta de línea de comandos para crear libros con Markdown

 (rust-lang.github.io)
4 puntos por GN⁺ 2023-07-01 | 1 comentarios | Compartir por WhatsApp
  • Cuando se necesita distribuir documentación y tutoriales en formato de libro, mdBook 0.5.3 ofrece escritura basada en Markdown junto con una salida navegable
  • Gracias a la ligera sintaxis de Markdown y a la búsqueda integrada, los autores pueden concentrarse más en el contenido que en el formato
  • Los bloques de código con resaltado de sintaxis y los archivos de tema permiten ajustar la legibilidad y el formato de salida necesarios para la documentación técnica
  • Los preprocesadores y backends ofrecen puntos de extensión para sintaxis personalizada, modificación de contenido y renderizado en múltiples formatos de salida
  • Al ser una herramienta usada en proyectos de Rust y en el libro The Rust Programming Language, tiene una fuerte conexión con el ecosistema de documentación de Rust

Funciones básicas necesarias para crear libros con Markdown

  • mdBook es una herramienta de línea de comandos para crear libros con Markdown
  • Es adecuada para crear contenido limpio y fácil de navegar, como documentación de productos, documentación de API, tutoriales y material de clase
  • Ofrece funciones que ayudan tanto a la experiencia de escritura como de lectura
    • Permite enfocarse en el contenido usando la sintaxis ligera de Markdown
    • Soporta búsqueda integrada dentro del libro
    • Aplica resaltado de sintaxis con colores a bloques de código en varios lenguajes
    • Permite personalizar el formato de salida mediante archivos de tema

Extensibilidad y conexión con el ecosistema de Rust

  • Los preprocesadores pueden encargarse de extender sintaxis personalizada y modificar contenido
  • Mediante backends, es posible renderizar a varios formatos de salida
  • mdBook está escrito en Rust para ofrecer velocidad, seguridad y simplicidad
  • Soporta pruebas automáticas de ejemplos de código en Rust

Casos de uso reales y formas de contribuir

Lecturas relacionadas

1 comentarios

 
GN⁺ 2023-07-01
Opiniones de Hacker News

  • Según recuerdo, esta plataforma usa bibliotecas alojadas en CDN en lugar de empaquetarlas o incluirlas como vendorizadas. Por eso, el usuario queda expuesto no solo a fallas del CDN, sino también a los datos que recopila ese servidor.
    Lo más lamentable es que la forma en que se usan Highlight.js y MathJax en el frontend es muy derrochadora. Cada cliente tiene que parsear y renderizar directamente la sintaxis y LaTeX, y repite el mismo trabajo en cada visita para obtener el mismo resultado. El resaltado de sintaxis podría procesarse en tiempo de compilación, y casi no hay razón para que requiera JavaScript.

    • MathJax parece estar alojado en un CDN, mientras que el CSS y otros archivos JS están colocados junto al archivo HTML.
      Parece que eligieron eso porque el soporte de MathJax es opcional: https://rust-lang.github.io/mdBook/format/mathjax.html
      Sin embargo, es muy probable que el JS de MathJax vuelva a cargar archivos adicionales desde el CDN, así que cuesta entender por qué no ponen todos los archivos de MathJax junto al HTML generado.
    • Parece que ya hay un PR abierto relacionado con esto: https://github.com/rust-lang/mdBook/pull/1918

  • Las herramientas de documentación y sitios estáticos mencionadas en este hilo son, aproximadamente, Jekyll, Hugo Book, MdBook, MkDocs, MkDocs Material, GitBook, Antora, Docusaurus, Nextra, Astro, Starlight, Clowncar, Keenwrite, Quarto, Honkit, JupyterBook.
    Jekyll, Hugo Book, MdBook, MkDocs, MkDocs Material, GitBook, Antora, Docusaurus, Nextra, Astro, Starlight, Clowncar, Keenwrite, Quarto, Honkit, JupyterBook

    • También probé nimibook.
      Es un port de mdBook a Nim, pero también amplía funciones para generar contenido interactivo usando el backend JavaScript de Nim. No lo he probado personalmente, pero me gusta la idea de poder crear elementos interactivos en un solo lugar cuando haga falta: https://pietroppeter.github.io/nimib/interactivity.html
    • Sphinx también es difícil de omitir. Su flujo de trabajo está más orientado al formato de libro que a blogs, foros o hilos.
    • HackMD suele ser una opción frecuente cuando se quieren crear documentos Markdown compartibles y editables en colaboración, con soporte para notación matemática: https://hackmd.io/
    • Sería bueno que existiera una tabla o sitio de comparación de funciones para estas herramientas. Me gustaría comparar búsqueda integrada, salida a PDF, salida a ePub, múltiples temas y otras funciones.
    • También está https://jupyterbook.org/en/stable/. Estoy contribuyendo a Jupyter Book.

  • Probé MdBook, Jekyll y MkDocs, y MdBook se siente pulido para proyectos básicos, pero demasiado minimalista. Al ver el código fuente de algunos sitios hechos con MdBook que me gustaron, en ciertos casos estaban extendidos con código Rust personalizado
    Mi recomendación: MkDocs es una opción predeterminada razonablemente flexible; Jekyll sirve cuando se necesita más flexibilidad, como para una landing page o un blog; y Antora es para cuando quieres reunir documentación de varios proyectos y varias versiones para crear el mejor sitio de documentación, y estás dispuesto a dedicarle mucho esfuerzo. AsciiDoc tiene muchas funciones útiles para escribir documentación
    Hugo parece flexible como Jekyll, pero requiere más esfuerzo para ajustarlo a lo que uno quiere, y las diferencias de funcionamiento entre temas parecen demasiado grandes. Al tema que usaba le faltaba una función que necesitaba, así que intenté cambiar a otro, pero la transición no fue fácil y al final me rendí. MdBook parece bastante activo, así que creo que eventualmente se pondrá al día

    • Soy usuario veterano de Jekyll y sigo pensando que es excelente para blogs, pero entre los generadores de sitios estáticos para sitios de documentación, Docusaurus fue el que más me gustó: https://docusaurus.io/
      Lo pospuse durante mucho tiempo porque no quería usar herramientas basadas en JavaScript, pero al probarlo vi que es fácil empezar, muy rápido, el sitio base es hermoso y también es fácil de personalizar. El soporte de MDX también es excelente
    • La landing page de material mkdocs theme(https://squidfunk.github.io/mkdocs-material/) es realmente elegante. Es especialmente impresionante si se considera que es un tema para otro software
    • Para ciencia y estadística, creo que Quarto es excelente: https://quarto.org
    • Es la primera vez que oigo hablar de Antora, pero su forma de ensamblar documentación desde varios repositorios y gestionar versiones con ramas es justo el comportamiento que quiero. Eso sí, es una lástima que la documentación existente sea una combinación de Markdown y componentes React interactivos, así que no usar MDX es un punto en contra
    • Uso mucho MkDocs y me gusta muchísimo
      También estoy probando BookStack; es más parecido a una wiki, pero es bueno para personas que no están familiarizadas con la tecnología. Normalmente edito proyectos de MkDocs en VSCode y los guardo en un repositorio Git, pero BookStack es completamente web

  • Antes generaba til.secretGeek.net con GitBook, pero con el tiempo se volvió lento hasta tardar 45 minutos en compilar el sitio, y las funciones que usaba fueron eliminadas o pasaron a ser “premium”. En definitiva, empezó la enshitificación
    Si estás usando una herramienta gratuita que parece demasiado buena, espera unos años y es muy probable que se arruine. Al final hice yo mismo un generador de sitios estáticos muy mínimo en .NET, y volvió a compilar en cuestión de segundos. No lo promociono para que otros lo usen, porque si se vuelve popular probablemente terminaría arruinándolo de la misma manera

  • Usé mdBook en varios proyectos, pero últimamente siento que material for mkdocs es más cómodo porque trae muchas más funciones de serie
    Por ejemplo, me gusta el índice de la página a la derecha, y esa función falta claramente en mdBook. En mdBook, el enfoque estándar parece ser configurar el SUMMARY con mucho detalle y dividir en varios archivos contenido que originalmente podría quedar en una sola página

    • material for mkdocs es lo bastante bueno como para valer la pena soportar la instalación de Python y la configuración de un entorno virtual
    • Me gusta MkDocs desde hace bastante tiempo. Permite resolver las cosas con una molestia mínima, tiene muchos temas para elegir y también es relativamente fácil personalizar uno o crear uno nuevo
    • Para obtener un índice por capítulo uso https://github.com/JorelAli/mdBook-pagetoc

  • Hace unos días empecé a usar mdBook para documentar un proyecto pequeño, y es exactamente el pequeño generador de páginas estáticas que necesitaba
    También probé HUGO, pero comparado con mdBook se siente demasiado grande y pesado. Ahora edito la documentación con Obsidian/VIM y, al hacer push a Gitea, se genera documentación pública en menos de 1 minuto

    • Uso Hugo con el book theme(https://github.com/alex-shpak/hugo-book). Si no estás familiarizado con Hugo, requiere un tiempo de adaptación, pero después se agradece la flexibilidad que ofrece Hugo, como los shortcodes
      Con shortcodes adecuados se puede numerar automáticamente figuras, fórmulas, etc. Me pregunto si mdBook también permite numeración automática. También tiene índice a la derecha, etiquetas y la posibilidad de dividir páginas en columnas, y el soporte de KaTeX es bueno. MdBook parece usar MathJax, y el despliegue es fácil con solo push o rsync
    • Hace poco empecé a usar una extensión de PlantUML, que ayuda a incluir diagramas de arquitectura en la documentación

  • Hace poco empecé a pasar lentamente contenido de .md a .mdx y a revisarlo, y me pareció bastante refrescante. Lo más difícil de Markdown era que cada dialecto tenía límites distintos, y también distintas formas de extender esos límites
    Estoy muy satisfecho con el 80~90% del dialecto estándar de GitBook Markdown, pero a veces necesito tablas complejas, bloques de código que mantengan el resaltado de sintaxis mientras enfatizan solo unas líneas, sliders interactivos, calculadoras integradas en el documento, o ciertos gráficos o charts. No sé cómo funcionará MDX en equipos grandes, pero para trabajo personal se ve como una mejora clara

    • Escuché hablar de .mdx por primera vez y busqué [0]. No estaba siguiendo lo suficiente la corriente de estandarización del frontend
      Sería bueno eliminar los dialectos y tener un único enfoque universal, pero la documentación dice que “MDX no está atado a React; también puede usarse con Preact, Vue, Emotion, Theme UI, etc., y soporta tanto el runtime JSX classic como automatic”. Como ya existe una implementación para Svelte [1], no estoy seguro de que esta vez no sea una caja de Pandora que genere más dialectos atados a frameworks frontend. También puede fragmentarse dentro de .mdx y no ser compatible con .md
      [0] https://mdxjs.com/docs/what-is-mdx/
      [1] https://mdsvex.com/docs
    • Totalmente de acuerdo. Cuando descubrí Mdsvex, sentí que me cambiaba la vida: https://mdsvex.com
    • .mdx se puede usar muy fácilmente con https://astro.build/. Astro es un metaframework de JavaScript y adopta un enfoque centrado en generación de sitios estáticos que no envía JS al cliente
      También hay temas disponibles, pero si eres un desarrollador web moderno, hacer uno propio debería ser bastante fácil

  • Creé KeenWrite, una herramienta gratuita, open source y multiplataforma para crear libros basados en Markdown: https://github.com/DaveJarvis/keenwrite
    KeenWrite invoca ConTeXt para la composición tipográfica de documentos y, en modo de vista previa, usa un fork de KeenType para la composición de fórmulas. Puede generar PDF desde la línea de comandos. El libro que estoy escribiendo ahora referencia en el cuerpo varias variables definidas en archivos externos, pasa propiedades del PDF mediante metadatos y permite compilar solo algunos capítulos con el argumento chapters. El directorio theme contiene instrucciones de composición tipográfica como colores, fuentes, layout y anotaciones
    Salida de ejemplo: https://github.com/DaveJarvis/keenwrite-themes/tree/main/exa...

  • Me pregunto por qué Markdown o algún formato parecido no es el formato predeterminado para libros, documentos y casi cualquier texto. Hace unos años me pasé a Typora y, desde entonces, casi no necesito Word/Writer para lo que escribo yo; solo los uso para abrir documentos que me mandan otros
    Tampoco veo una razón clara para que el 90% de los libros que leo no estén en formato Markdown. Entiendo que para imprimir libros en papel de forma bonita hace falta composición tipográfica, pero la mayoría de los textos que se leen en una computadora o un smartphone, o que se imprimen directamente desde MS/LibreOffice, de todos modos no tienen ese trabajo de composición bien hecho

    • Markdown es bastante pobre como formato de almacenamiento. Existe CommonMark, un estándar semioficial, pero le faltan funciones, así que la mayoría usa variantes como GitHub Markdown, y muchas apps individuales extienden Markdown de formas incompatibles entre sí
      Hay alternativas mejores, como AsciiDoc, pero están más enfocadas en documentación y no tienen ni de cerca el impulso de Markdown. Si se considera que Markdown es un formato relativamente tardío, la pregunta más acertada es por qué los libros deberían estar en Markdown. Frente a formatos binarios o basados en XML, la mayor ventaja de Markdown es que se puede leer más o menos como texto plano, pero eso no es tan importante para la mayoría de las editoriales y lectores
    • La composición tipográfica de libros tiene muchas sutilezas y complejidades que no son evidentes para un ojo no entrenado, y Markdown+CSS no es lo bastante sofisticado para abordarlas. HTML/CSS+JS también es técnicamente posible, pero está bastante por detrás del estado del arte en composición digital
      Esto también es la típica trampa del ingeniero de “yo puedo hacerlo mejor”, así que no conviene asumirlo sin investigar. La composición tipográfica es un campo mucho más antiguo que las herramientas tratadas aquí, y no deberíamos descartar las ideas y técnicas valiosas acumuladas durante todo ese tiempo solo porque Markdown sea casi suficiente para algunos usos
    • En el trabajo escribo muchos documentos, y me gusta la forma de ver Markdown y el resultado renderizado lado a lado. Una vez que te acostumbras a la sintaxis, Markdown es mucho más rápido que editores como Word, y hasta hacer una lista en un editor de texto me empieza a parecer engorroso

  • mdBook es fácil de usar, y me gusta especialmente que los usuarios puedan elegir el tema. Lo uso sobre todo para versiones online de ebooks [0] y para recursos curados [1][2]
    [0] https://github.com/learnbyexample/scripting_course#ebooks
    [1] https://learnbyexample.github.io/py_resources/
    [2] https://learnbyexample.github.io/curated_resources/