Jump to content
Sign in to follow this  
lightbug

Documentación (html) online a offline

Recommended Posts

Hola gente, acá les traigo un problemita que estoy teniendo con la documentación.

Resulta que hace poco lancé un nuevo asset para el Asset Store y realicé la documentación online (Este es el sitio: https://lightbug14.gitbook.io/ccp/ ). La cosa es que quiero tenerla de forma offline también ( sin pagar 1 centavo ;) ).

Dicho esto, no quiero usar ningun formato de libro o impreso, quiero se sea contenido web, tipo html (o markdown, que basicamente terminará en html).Es decir, ningún GoogleDocs, MS Office , Libreoffice, etc, ya que estos no están pensados para documentos técnicos (formato muy caótico, además de que tampoco disponen de la creación de un panel de navegación). Tengo experiencia con LaTeX para generar documentación/tesis en pdf (lo he usado muchísimo y es genial) pero estoy buscando algo más "digital", de nuevo, esto no va a ir a parar a un formato impreso.

 

Para que se entienda un poco, realicé esto usando Markdown + GitBook + Github pages. Para los que no sepan que es esto que les digo (y ya que está les hago conocer estos grandes recursos):

  • Markdown: Un lenguaje que te permite rapidamente escribir y etiquetar los bloques de texto como en el html de toda la vida (parrafo, header1,header2, itálica, negrita, etc) pero sin usar los tags de html (Ej <strong> ... </strong>). Si quieren jugar con esto aca dejo un editor online de Markdown -->  https://stackedit.io/ (denle a "Start writing" arriba). ... el típico readme.md de los repositorios de github está en markdown.
  • Gitbook: una plataforma de generación de sitios estáticos (sin bases de datos, permisos, etc, simplemente todo el contenido va localmente a la computadora, como un documento estático), la cual permite recopilar "páginas" en lenguaje markdown y crear/compartir un sitio online, ya sea público o privado. Te ofrece todos los chiches incluidos, buscador, barra de navegación (con anidación y todo), sistema de puntajes, estadísticas, una interfaz gráfica muy amigable, etc.
  • Github pages: (muy pero muy de moda hoy en día) Basicamente te permite convertir un branch de un repositorio de github, usandolo como "hosting" gratis. Por ejemplo, se puede usar para una página estática (html+css+js). Este tiene la interesante posibilidad de usar markdown directamente + Jekyll (un embellecedor).

Bueno, usé todo esto combinado y estoy muy contento con el resultado. El tema es que quiero "descargar" el html completo para entregarlo con el asset en formato html. Gitbook ofrece una opción de "PDF Export", pero hay que pagar :(

Y por qué no pagar y listo?  Por dos cosas:

  1. Termina siendo pdf, cosa que no quiero.
  2. Porque hay tantos generadores de sitios estáticos gratuitos en internet, que seguramente gracias a mi incompetencia e inexperiencia en el tema estoy obviando alguna alternativa 100% viable y sencilla.

--->  Por eso escribo este hilo, si alguien tiene o ha tenido experiencia en esto sería muy bueno conocer su opinión al respecto. Desde ya que esta consulta no está ligada al desarrollo de juegos, puede ser que hayan utilizado generadores para construit su sitio de poesías, su blog personal, su sitio ilegal de ventas de armas, lo que sea que requiera de contenido estático.

 

Alternativas:

He probado mkdocs. Este hace exactamente esto, recopila páginas de markdown y te indexa todo con un lindo panel de navegación etc etc. Problema: ha quedado algo obsoleto, o por lo menos la versión que uso no funca para nada.

La última sería usar html de toda la vida(manualmente). Problema: Sería un dolor de quinotos, sobretodo el tema del panel de navegación, pero si se pudiera automatizar el proceso (con scripts y que se yo) estaría dispuesto a hacerlo.

 

Saludos.

  • Like 1

Share this post


Link to post
Share on other sites

@lightbug Felicitaciones por la documentación, te quedo excelente, la lei solo por ser agradable a la vista.

En cuanto a tu pregunta.... intentaste con lo siguiente?

Please note that if you change self_contained = TRUE to make self-contained HTML pages, the total size of all HTML files can be significantly increased since there are many JS and CSS files that have to be embedded in every single HTML file.

Besides these html_document() options, gitbook() has three other arguments: split_by, split_bib, and config. The split_by argument specifies how you want to split the HTML output into multiple pages, and its possible values are:

  • rmd: use the base filenames of the input Rmd files to create the HTML filenames, e.g., generate chapter3.html for chapter3.Rmd.
  • none: do not split the HTML file (the book will be a single HTML file).
  • chapter: split the file by the first-level headers.
  • section: split the file by the second-level headers.
  • chapter+number and section+number: similar to chapter and section, but the files will be numbered.

 

Share this post


Link to post
Share on other sites

Gracias @francoe1, es un sitio super agradable es cierto. Una cosa que no mencioné es que posee una extensión para respaldar todo el contenido el github, muy útil esto.

De donde has sacado esa info? me interesa ese "none". Googleando eso encontré este link pero no caigo como puedo implementarlo en mi caso :35_thinking:. Supongo que habrá que hacer eso que algunos llaman ... leer ... :52_fearful:.

 

Share this post


Link to post
Share on other sites

Jajaja --- 

Es ese link, exactamente en #gitbook-style (pegalo al final del link :])

En lo personal hay varios software para "documentación técnica", si bien es cierto que Markdown acelera mucho el proceso, tambien tiene muchas limitaciones.

Estoy buscando un programa que programe hace un tiempo para generar un Single Page con .md siguiente la estructura de carpeta, era una boludes el programa, pero no me acuerdo en lenguaje lo hice, creo que python... si lo encuentro lo comparto.

El software que usaba y uso para escribir los .md es ... Zettlr que de hecho ahora está bastante actualizado, creo que usaban LaTex para la exportación. 

 

Share this post


Link to post
Share on other sites

No conocía Gitbook, thx. Este tipo de servicios son todos iguales. Te dejan la web "bonita" por el formato de presentación y los estilos, pero luego son un desastre o una estafa para exportar y convertir a otros formatos. Además, el PDF no es un formato viable si quieres incluir vídeos o gif's animados, y otras cosas típicas de HTML. No te va a permitir exportar el paginado exactamente como tú quieres...

En mi caso, yo tengo un contenido bastante extenso creado en GoogleDocs  y quiero hacerlo lo bastante flexible y universal para ser visualizado desde cualquier forma, PDF/HTML/MHT/EPUB. Hasta la fecha, lo mejor que he encontrado es Reveal.js y subirlo directamente a Github, pero es un engorro "programar una web" para hacer documentación. 

 

Así que estoy igual que tú @lightbug. Si alguien conoce algún servicio o formato que soporte tantas cosas como HTML y a la vez se pueda exportar en un archivo único y soportado en todos los sistemas operativos, que me avise, pls...

Share this post


Link to post
Share on other sites
10 hours ago, francoe1 said:

Es ese link, exactamente en #gitbook-style (pegalo al final del link :])

No me salió nada ... :58_disappointed_relieved: pegarlo al final del link? de la url?

Dicho de paso, ese sitio era de rmd (una versión de markdown de R) y el uso del paquete bookdown. Ya que estaba me descargué R y Rstudio, la verdad un mundo nuevo por descubrir.

 

10 hours ago, francoe1 said:

El software que usaba y uso para escribir los .md es ... Zettlr que de hecho ahora está bastante actualizado, creo que usaban LaTex para la exportación. 

Lo probé y está bueno, la interfaz es muy agradable. Hay algo que me está volviendo loco-> no soporta el uso del "tab" (?), útil normalmente para insertar bloques de código dentro de los markdowns. Los formatos de exportación están geniales, todavía tengo que indagar más en el software, pero pinta lindo.

Ya que está, encontré dando vueltas por ahí este excelente editor de markdown (markdown monster), --> https://markdownmonster.west-wind.com/  , podés hasta convertir md -> html y html -> md.

Otra opción en su momento fue la de usar helpNDocs, pero no usa markdown, tampoco permite insertar bloques de código. Lo bueno es que podés generar html, pdf, chm (esos viejos archivo de ayuda, clásicos) y demás.

 

Es decir, hay herramientas de sobra para esto, pero lamentablemente todo está muy orientado a comandos de consola. No es que no me guste descargar paquetes y usar comandos de consola, pero a ver, es 2020 y no puede ser que no exista un simple programita que haga esto de manera offline. Bueno no me voy a simplemente quejar y quejar, lo voy a escribir en estos días. Basicamente que pase mardown a html (o pego directamente el html) y me genere la barra de navegación automagicamente, siguiendo una estructura de directorio.

 

11 minutes ago, pioj said:

Además, el PDF no es un formato viable si quieres incluir vídeos o gif's animados, y otras cosas típicas de HTML. No te va a permitir exportar el paginado exactamente como tú quieres...

Claro, buen punto.

En mi caso esto surgió de algo super simple, de la necesidad de crear una de esas barras de navegación laterales (sidebars). Desde luego, sin tener que andar copiando y pegando código html por todos los documentos.

 

Share this post


Link to post
Share on other sites

muy pro la documentacion, no esperaba menos de @lightbug (no esperaba menos de 200 paginas XD)

no sabia que habias continuado con tu character controler (conocia la version 2d) ...pero ahora has completado tu complemento con un completo y funcional 3D...

muy pro todo....

...este @lightbug es muy pro...

dan ganas de secuestrarle y encerrarle en una habitacion a teclear codigo... digo... estaria guai colaborar con el en algun proyecto...

  • Like 3

Share this post


Link to post
Share on other sites
On 2/9/2020 at 10:27 AM, Igor said:

no sabia que habias continuado con tu character controler (conocia la version 2d) ...pero ahora has completado tu complemento con un completo y funcional 3D...

Jaja  sí, surgió como un "fork" de la versión en 2D, ya que quería una versión "todo terreno 4x4" (a.k.a 2D/3D), y ante un problema con la falta de depenetración en 2D (que en 3D funciona a la perfección) dije "y si lo hago dinámico ???" y ahí está. (de los rigidbodies dinámicos aprendí muchísimo, sobre todo de contactos y demás)

Ahora estoy tratando de pasar el asset 2D (Kinematic 2D) al mundo del 3D pero manteniendolo kinemático y 2D (no se si me explico). Y así dar soporte a los dos, pensándolos como uno solo (a grandes rasgos).

On 2/9/2020 at 10:27 AM, Igor said:

...este @lightbug es muy pro...

Para nada, todo pura fachada.

On 2/9/2020 at 10:27 AM, Igor said:

estaria guai colaborar con el en algun proyecto...

off kors

  • Like 1

Share this post


Link to post
Share on other sites

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.

Guest
Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

Sign in to follow this  

×
×
  • Create New...