Diferencia entre revisiones de «Usuario:ManuelRomero/hugo»

De WikiEducator
Saltar a: navegación, buscar
(→‎Docsy (imgproc))
(→‎Docsy)
 
(20 revisiones intermedias por el mismo usuario no mostrado)
Línea 1: Línea 1:
 +
===Goldmark===
 +
 +
La configuración que mencionas está relacionada con Goldmark, el motor de procesamiento de Markdown que utiliza Hugo por defecto desde la versión 0.60. Esta configuración se encuentra en el archivo de configuración de Hugo (como config.toml o config.yaml) y define cómo se procesan los archivos Markdown en el sitio web.
 +
 +
Desglose de la configuración:
 +
<sourcel lang=toml>
 +
 +
[markup]
 +
  [markup.goldmark]
 +
    [markup.goldmark.renderer]
 +
      unsafe = true
 +
</source>
 +
;1. [markup]
 +
 +
**Este bloque es la configuración general para el procesamiento de Markdown en Hugo. Aquí es donde se define el motor que procesará los archivos .md. En este caso, se está utilizando Goldmark, que es el motor predeterminado desde Hugo 0.60.
 +
 +
;2. [markup.goldmark]
 +
Este bloque específico es para configurar el comportamiento de Goldmark, el procesador de Markdown en Hugo. Puedes configurar varios aspectos de Goldmark, como el renderizado, las extensiones, etc.
 +
 +
;3. [markup.goldmark.renderer]
 +
*Aquí es donde defines cómo se van a renderizar los archivos Markdown procesados. El renderizado es el paso donde el Markdown se convierte en HTML.
 +
 +
;4. unsafe = true
 +
*Esta línea específica le dice a Hugo que permita contenido "no seguro" o "peligroso" en el HTML generado a partir de Markdown. Cuando unsafe = true, Hugo permitirá ciertos elementos y atributos de HTML que normalmente se bloquearían por razones de seguridad.
 +
 +
;¿Qué significa "contenido no seguro"?
 +
*Cuando unsafe = true, Hugo permite el uso de elementos HTML dentro de tus archivos Markdown. Esto incluye:
 +
 +
*Etiquetas HTML incrustadas: Si tienes HTML directo dentro de tus archivos Markdown (como <div>, <iframe>, etc.), este contenido se permitirá en el HTML final.
 +
 +
*Ejemplo
 +
<source lang=bash>
 +
## Título
 +
 +
<div class="custom-div">Contenido HTML aquí</div>
 +
</source>
 +
*Sin unsafe = true, este contenido HTML podría ser ignorado o escapado (mostrado como texto literal), lo que impediría que se renderice correctamente.
 +
 +
*Atributos de HTML peligrosos: Hugo puede bloquear ciertos atributos en etiquetas HTML (como onClick, style, script, etc.), que podrían ser considerados riesgosos. Con unsafe = true, estos atributos se permitirán en el HTML generado.
 +
 +
;¿Cuándo usar unsafe = true?
 +
*Incluir HTML personalizado en Markdown: Si estás incluyendo fragmentos HTML dentro de tus archivos Markdown, como formularios, videos incrustados, o cualquier otro contenido HTML personalizado, deberías habilitar unsafe = true para que se renderice correctamente.
 +
 +
*Usar shortcodes personalizados que contengan HTML: Si estás usando shortcodes personalizados en Hugo que contienen código HTML que quieres insertar directamente en las páginas generadas, unsafe = true garantizará que ese código no sea filtrado o escapado.
 +
 +
*Proyectos que requieren HTML más complejo: Si tu proyecto necesita una combinación de Markdown y HTML más avanzada, como estilos en línea, scripts incrustados, o estructuras HTML complejas, esta opción es útil.
 +
 +
;¿Cuándo no deberías usarlo?
 +
*Si tu sitio web tiene usuarios que podrían editar o subir contenido en Markdown, activar unsafe = true puede representar un riesgo de inserción de scripts maliciosos (XSS). En esos casos, deberías evitarlo o usar medidas de sanitización adicionales.
 +
 +
* Ejemplo de uso:  Antes de habilitar unsafe = true:
 +
<source lang=bash>
 +
# Título
 +
 +
<div class="custom-div">Este contenido no se mostrará correctamente</div>
 +
</source>
 +
*Esto podría no renderizarse correctamente o ser escapado como texto literal, y verías algo como:
 +
 +
{{MRM_Resumen|
 +
 +
unsafe = true le dice a Hugo que permita contenido HTML incrustado en los archivos Markdown.
 +
Es útil si estás mezclando HTML y Markdown o si necesitas incluir etiquetas HTML personalizadas en tu contenido.
 +
Precaución: Solo debes habilitarlo si tienes control sobre el contenido, ya que puede aumentar el riesgo de vulnerabilidades XSS.
 +
}}
 +
 
===Docsy ===
 
===Docsy ===
 +
* Instalar en el proyecto autoprefixer
 +
<source lang=bash>
 +
  npm install autoprefixer --save-dev
 +
</source>
 +
* Copiar el '''''favicon.ico''''' en '''''static/favicon'''''
 +
 +
===Crear una librería con iconos===
 +
*Se prentende usar como si fueran iconos de font awesome
 +
;Crear la librería en la web y descargarla en local
 +
*Acceo https://icomoon.io/ a https://icomoon.io/app/ y me logueo
 +
*Previamente tengo preparada una  carpeta en local con los iconos svg
 +
** Buscar pe en https://icons8.com/
 +
*Subir los iconos SVG.
 +
*Agruparlos en una fuente de iconos.
 +
* Haz clic en "Generate Font" (PArte inferior derecha de la pantalla). para crear la fuente.
 +
* Descarga el paquete generado, que incluirá los archivos de fuente (.woff, .ttf) y un archivo CSS para incluir en tu proyecto.
 +
*Descargar el paquete con archivos CSS y de fuentes.
 +
;Incluir la fuente en tu proyecto Hugo:
 +
*Sube los archivos .woff, .ttf a la carpeta static/fonts/ de tu proyecto.
 +
*sube el archivo CSS a static/css/ (por ejemplo, my-icons.css).
 +
*Incluye el CSS en tu archivo hugo.toml:
 +
 +
====Crear un nuevo sitio como submódulo====
 +
<source lang=bash>
 +
hugo new site sitio_nuevo
 +
</source>
 +
 +
*En este caso voy a usar el tema docsy
 +
*Tengo 3 formas de hacerlo:
 +
*1.- Clonando el tema directamente (no recomendado)
 +
*2.- Clonando el tema como un submodulo de git (recomendado)
 +
<source lang=bash>
 +
  git init
 +
  git submodule add  https://github.com/google/docsy.git themes/docsy
 +
</source>
 +
*3.- Creando un modulo de go (el más recomendado)
 +
 
====imgproc====
 
====imgproc====
 
*Si quiero usar el shortdoce '''''imgproc'''''
 
*Si quiero usar el shortdoce '''''imgproc'''''
Línea 6: Línea 108:
 
  tengo un fichero p.e '''''objetivo.md''''' dónde quiero usar una imagen llamada objetivo_general.png
 
  tengo un fichero p.e '''''objetivo.md''''' dónde quiero usar una imagen llamada objetivo_general.png
  
−
;Acción'
+
;Acción
 
  Creo en content... un directorio llamado '''''objetivo'''''
 
  Creo en content... un directorio llamado '''''objetivo'''''
 
  en él creo un fichero llamado index.md con el contenido de objetivo.md
 
  en él creo un fichero llamado index.md con el contenido de objetivo.md
Línea 17: Línea 119:
 
---
 
---
 
  </source>
 
  </source>
 +
 
====markmap====
 
====markmap====
 
*En el config.toml
 
*En el config.toml
−
<source lang="bash">
+
<source lang="yaml">
 
# Para crear gráficos direccionales
 
# Para crear gráficos direccionales
 
[params.markmap]
 
[params.markmap]
Línea 25: Línea 128:
 
</source>
 
</source>
 
*En el fichero '''''md'''''
 
*En el fichero '''''md'''''
−
<source lang="json>
+
<source lang="yaml">
 
```markmap
 
```markmap
 
#raiz_1
 
#raiz_1
Línea 37: Línea 140:
 
```
 
```
 
</source>
 
</source>
 +
====emojin====
 +
*Común para todo hugo
 +
*En el config.toml
 +
<source lang="yaml">
 +
 +
# Para poder cargar emogin https://www.webfx.com/tools/emoji-cheat-sheet/
 +
enableEmoji = true
 +
</source>
 +
*En el fichero '''''md''''' se incluye el nombre de emojin que podemos sacar del '''''cheat sheet''''' https://www.webfx.com/tools/emoji-cheat-sheet/
 +
 +
===Errores. Solución usar el tema como  módulo===
 +
*Me encuentro con este error
 +
Error: Error building site: "/home/oem/hugo/web/content/es/_index.html:6:1": failed to extract shortcode: template for shortcode "blocks/cover" not found
 +
Built in 5 ms
 +
(3/05/2023)
 +
SOLUCIÓN
 +
Agrego el tema como un módulo en el fichero config,toml o hugo.toml
 +
<source lang=yaml>
 +
[module]
 +
  # uncomment line below for temporary local development of module
 +
  # replacements = "github.com/google/docsy -> ../../docsy"
 +
  [module.hugoVersion]
 +
    extended = true
 +
    min = "0.75.0"
 +
  [[module.imports]]
 +
    path = "github.com/google/docsy"
 +
    disable = false
 +
  [[module.imports]]
 +
    path = "github.com/google/docsy/dependencies"
 +
    disable = false
 +
</source>
 +
 +
*Ahora cargo el módulo
 +
<source lang=bash>
 +
hugo mod init  .
 +
</source>
 +
{{nota|El punto final no estoy seguro. si haces un hugo serve también funciona la descarga del módulo/s (el tema)}}
 +
 +
====Incluir librería de iconos====
 +
;Crear una fuente de iconos personalizados
 +
*Se trata de poder tener disponibles más iconos de los que nos ofrece font awesome.
 +
{{MRM_Actividad|Title=Icoomon|
 +
Herramientas como '''''Icomoon'''''  te permiten cargar tus íconos en formato SVG y generar una fuente de íconos que puedes utilizar con clases CSS, igual que con Font Awesome:
 +
}}
 +
;Acciones:
 +
# Sube tus íconos a Icomoon.
 +
# Genera la fuente y descarga los archivos.
 +
# Incluye los archivos generados en tu proyecto.
 +
# Usa los íconos en HTML, similar a cómo lo harías con Font Awesome:
 +
===== Subir iconos =====
 +
 +
 +
==Syna==
 +
====Documentación====
 +
https://github.com/okkur/syna
 +
https://about.okkur.org/syna/docs/
 +
====Instalación====
 +
<source lang=bash>
 +
hugo new site main
 +
cd main
 +
cd themes
 +
git clone https://git.okkur.org/syna themes/syna
 +
</source>
 +
*Establecer el tema en '''''config.toml'''''.
 +
<source lang=bash>
 +
....
 +
theme = 'syna'
 +
....
 +
</source>
 +
====Contenido====
 +
*
 +
*En esta plantilla el contenido está basado en páginas y fragmentos o '''''framgment''''
 +
*Ĉada página está formada por uno o varios fragmentos
 +
*Para crear una página creamos un directorio con un fichero.
 +
**Si no hay secciones se llamará '''''index.md'''''.
 +
**Si hay secciones se llamará '''''_index.md'''''.
 +
<source lang=bash>
 +
hugo new docencia_reglada/_index.md
 +
hugo new myself/index.md
 +
</source>
 +
 +
*Para crear páginas de contenido lo podemos hacer de dos formas:
 +
# Creando un grupo de páginas simple:'''''single'''''.
 +
# Creando lista de páginas '''''list'''''
 +
 +
;Modo single: (MRM revisar esta sección)
 +
*En este caso cada nueva sección va a ser un directorio y va a cointener un fichero llamado index.md que será el índice de la sección
 +
*El directorio creado será el nombre del fragmento
 +
*Cada nueva página deberá de referenciar el fragmento del que depende
 +
vamos a agruparlas en '''''directorios''''' con un fichero '''''index.md'''''.
 +
;Modo list: (MRM revisar esta sección)
 +
*
 +
*El directorio creado será el nombre del fragmento
 +
*Cada nueva página deberá de referenciar el fragmento del que depende
 +
vamos a agruparlas en '''''directorios''''' con un fichero '''''index.md'''''.

Última revisión de 06:49 4 nov 2024

Goldmark

La configuración que mencionas está relacionada con Goldmark, el motor de procesamiento de Markdown que utiliza Hugo por defecto desde la versión 0.60. Esta configuración se encuentra en el archivo de configuración de Hugo (como config.toml o config.yaml) y define cómo se procesan los archivos Markdown en el sitio web.

Desglose de la configuración: <sourcel lang=toml>

[markup] 

 [markup.goldmark]
   [markup.goldmark.renderer]
     unsafe = true

</source>

1. [markup]
    • Este bloque es la configuración general para el procesamiento de Markdown en Hugo. Aquí es donde se define el motor que procesará los archivos .md. En este caso, se está utilizando Goldmark, que es el motor predeterminado desde Hugo 0.60.
2. [markup.goldmark]

Este bloque específico es para configurar el comportamiento de Goldmark, el procesador de Markdown en Hugo. Puedes configurar varios aspectos de Goldmark, como el renderizado, las extensiones, etc.

3. [markup.goldmark.renderer]
  • Aquí es donde defines cómo se van a renderizar los archivos Markdown procesados. El renderizado es el paso donde el Markdown se convierte en HTML.
4. unsafe = true
  • Esta línea específica le dice a Hugo que permita contenido "no seguro" o "peligroso" en el HTML generado a partir de Markdown. Cuando unsafe = true, Hugo permitirá ciertos elementos y atributos de HTML que normalmente se bloquearían por razones de seguridad.
¿Qué significa "contenido no seguro"?
  • Cuando unsafe = true, Hugo permite el uso de elementos HTML dentro de tus archivos Markdown. Esto incluye:
  • Etiquetas HTML incrustadas: Si tienes HTML directo dentro de tus archivos Markdown (como
    , <iframe>, etc.), este contenido se permitirá en el HTML final.
  • Ejemplo 
## Título
 
<div class="custom-div">Contenido HTML aquí</div>
  • Sin unsafe = true, este contenido HTML podría ser ignorado o escapado (mostrado como texto literal), lo que impediría que se renderice correctamente.
  • Atributos de HTML peligrosos: Hugo puede bloquear ciertos atributos en etiquetas HTML (como onClick, style, script, etc.), que podrían ser considerados riesgosos. Con unsafe = true, estos atributos se permitirán en el HTML generado.
¿Cuándo usar unsafe = true?
  • Incluir HTML personalizado en Markdown: Si estás incluyendo fragmentos HTML dentro de tus archivos Markdown, como formularios, videos incrustados, o cualquier otro contenido HTML personalizado, deberías habilitar unsafe = true para que se renderice correctamente.
  • Usar shortcodes personalizados que contengan HTML: Si estás usando shortcodes personalizados en Hugo que contienen código HTML que quieres insertar directamente en las páginas generadas, unsafe = true garantizará que ese código no sea filtrado o escapado.
  • Proyectos que requieren HTML más complejo: Si tu proyecto necesita una combinación de Markdown y HTML más avanzada, como estilos en línea, scripts incrustados, o estructuras HTML complejas, esta opción es útil.
¿Cuándo no deberías usarlo?
  • Si tu sitio web tiene usuarios que podrían editar o subir contenido en Markdown, activar unsafe = true puede representar un riesgo de inserción de scripts maliciosos (XSS). En esos casos, deberías evitarlo o usar medidas de sanitización adicionales.
  • Ejemplo de uso: Antes de habilitar unsafe = true: 
# Título
 
<div class="custom-div">Este contenido no se mostrará correctamente</div>
  • Esto podría no renderizarse correctamente o ser escapado como texto literal, y verías algo como:


Icon summary.gif
Resumen
{{{1}}}


Docsy

  • Instalar en el proyecto autoprefixer 
  npm install autoprefixer --save-dev
  • Copiar el favicon.ico en static/favicon

Crear una librería con iconos

  • Se prentende usar como si fueran iconos de font awesome
Crear la librería en la web y descargarla en local
  • Acceo https://icomoon.io/ a https://icomoon.io/app/ y me logueo
  • Previamente tengo preparada una carpeta en local con los iconos svg
  • Subir los iconos SVG.
  • Agruparlos en una fuente de iconos.
  • Haz clic en "Generate Font" (PArte inferior derecha de la pantalla). para crear la fuente.
  • Descarga el paquete generado, que incluirá los archivos de fuente (.woff, .ttf) y un archivo CSS para incluir en tu proyecto.
  • Descargar el paquete con archivos CSS y de fuentes.
Incluir la fuente en tu proyecto Hugo
  • Sube los archivos .woff, .ttf a la carpeta static/fonts/ de tu proyecto.
  • sube el archivo CSS a static/css/ (por ejemplo, my-icons.css).
  • Incluye el CSS en tu archivo hugo.toml:

Crear un nuevo sitio como submódulo

hugo new site sitio_nuevo
  • En este caso voy a usar el tema docsy
  • Tengo 3 formas de hacerlo:
  • 1.- Clonando el tema directamente (no recomendado)
  • 2.- Clonando el tema como un submodulo de git (recomendado) 
  git init
  git submodule add  https://github.com/google/docsy.git themes/docsy
  • 3.- Creando un modulo de go (el más recomendado)

imgproc

  • Si quiero usar el shortdoce imgproc
Situación
tengo un fichero p.e objetivo.md dónde quiero usar una imagen llamada objetivo_general.png
Acción 
Creo en content... un directorio llamado objetivo
en él creo un fichero llamado index.md con el contenido de objetivo.md
Igualmente copio la imagen objetivo_general.png
Establezco el recuros de la imagen en el frontmatter de index.md:

 ***********
resources:
- src: "objetivo.jpg"
---

markmap

  • En el config.toml 
# Para crear gráficos direccionales
[params.markmap]
    enable = true
  • En el fichero md 
```markmap
#raiz_1
##raiz_1_1
##raiz_1_2
##raiz_1_3
### raiz_1_3_1
### raiz_1_3_2
### raiz_1_3_2
....
```

emojin

  • Común para todo hugo
  • En el config.toml 
# Para poder cargar emogin https://www.webfx.com/tools/emoji-cheat-sheet/
enableEmoji = true

Errores. Solución usar el tema como módulo

  • Me encuentro con este error 
Error: Error building site: "/home/oem/hugo/web/content/es/_index.html:6:1": failed to extract shortcode: template for shortcode "blocks/cover" not found

Built in 5 ms (3/05/2023) SOLUCIÓN Agrego el tema como un módulo en el fichero config,toml o hugo.toml 

[module]
  # uncomment line below for temporary local development of module
  # replacements = "github.com/google/docsy -> ../../docsy"
  [module.hugoVersion]
    extended = true
    min = "0.75.0"
  [[module.imports]]
    path = "github.com/google/docsy"
    disable = false
  [[module.imports]]
    path = "github.com/google/docsy/dependencies"
    disable = false
  • Ahora cargo el módulo 
hugo mod init  .

(Comment.gif: El punto final no estoy seguro. si haces un hugo serve también funciona la descarga del módulo/s (el tema))



Incluir librería de iconos

Crear una fuente de iconos personalizados
  • Se trata de poder tener disponibles más iconos de los que nos ofrece font awesome.


Icon activity.jpg
Icoomon

Herramientas como Icomoon te permiten cargar tus íconos en formato SVG y generar una fuente de íconos que puedes utilizar con clases CSS, igual que con Font Awesome:



Acciones
  1. Sube tus íconos a Icomoon.
  2. Genera la fuente y descarga los archivos.
  3. Incluye los archivos generados en tu proyecto.
  4. Usa los íconos en HTML, similar a cómo lo harías con Font Awesome:
Subir iconos

Syna

Documentación

https://github.com/okkur/syna
https://about.okkur.org/syna/docs/

Instalación

 hugo new site main
 cd main
 cd themes
 git clone https://git.okkur.org/syna themes/syna
  • Establecer el tema en config.toml. 
 ....
 theme = 'syna'
 ....

Contenido

  • En esta plantilla el contenido está basado en páginas y fragmentos o framgment'
  • Ĉada página está formada por uno o varios fragmentos
  • Para crear una página creamos un directorio con un fichero.
    • Si no hay secciones se llamará index.md.
    • Si hay secciones se llamará _index.md. 
hugo new docencia_reglada/_index.md
hugo new myself/index.md
  • Para crear páginas de contenido lo podemos hacer de dos formas:
  1. Creando un grupo de páginas simple:single.
  2. Creando lista de páginas list
Modo single
(MRM revisar esta sección)
  • En este caso cada nueva sección va a ser un directorio y va a cointener un fichero llamado index.md que será el índice de la sección
  • El directorio creado será el nombre del fragmento
  • Cada nueva página deberá de referenciar el fragmento del que depende

vamos a agruparlas en directorios con un fichero index.md.

Modo list
(MRM revisar esta sección)
  • El directorio creado será el nombre del fragmento
  • Cada nueva página deberá de referenciar el fragmento del que depende
vamos a agruparlas en directorios con un fichero index.md.
Obtenido de «https://es.wikieducator.org/index.php?title=Usuario:ManuelRomero/hugo&oldid=31278»