Configuración

Todos los archivos de configuración de Grav están escritos en sintaxis YAML con la extensión .yaml. YAML es muy intuitivo, lo que lo hace muy fácil de leer y escribir, sin embargo, puedes consultar la página YAML en el capítulo avanzado para obtener una comprensión completa de la sintaxis disponible.

Configuración del Sistema

Grav se enfoca en hacer las cosas lo más sencillas posible para el usuario, y lo mismo ocurre con la configuración. Grav viene con algunas opciones predeterminadas razonables, y estas están contenidas en un archivo que reside en system/config/system.yaml.

Sin embargo, nunca debes cambiar este archivo, en su lugar, cualquier cambio de configuración que necesites hacer debe guardarse en un archivo llamado user/config/system.yaml. Cualquier configuración en este archivo con la misma estructura y nombre sobrescribirá la configuración proporcionada en el archivo de configuración del sistema predeterminado.

Aquí están las variables que se encuentran en el archivo predeterminado system/config/system.yaml:

Opciones Básicas

absolute_urls: false
timezone: ''
default_locale:
param_sep: ':'
wrapped_site: false
reverse_proxy_setup: false
force_ssl: false
force_lowercase_urls: true
custom_base_url: ''
username_regex: '^[a-z0-9_-]{3,16}$'
pwd_regex: '(?=.*\d)(?=.*[a-z])(?=.*[A-Z]).{8,}'
intl_enabled: true
http_x_forwarded:
  protocol: true
  host: false
  port: true
  ip: true

Estas opciones de configuración no aparecen dentro de sus propias secciones secundarias. Son opciones generales que afectan el funcionamiento del sitio, su zona horaria y la URL base.

Idiomas

languages:
  supported: []
  default_lang:
  include_default_lang: true
  include_default_lang_file_extension: true
  pages_fallback_only: false
  translations: true
  translations_fallback: true
  session_store_active: false
  http_accept_language: false
  override_locale: false
  content_fallback: {}

El área de Idiomas del archivo establece las configuraciones de idioma del sitio. Esto incluye qué idioma(s) son compatibles, la designación del idioma predeterminado en las URLs y las traducciones. Aquí está el desglose para el área de Idiomas en el archivo de configuración del sistema:

Inicio

home:
  alias: '/home'
  hide_in_urls: false

La sección de Inicio es donde configuras la ruta predeterminada a la página principal del sitio. También puedes optar por ocultar la ruta de inicio en las URLs.

Páginas

pages:
  type: regular
  theme: quark
  order:
    by: default
    dir: asc
  list:
    count: 20
  dateformat:
    default:
    short: 'jS M Y'
    long: 'F jS \a\t g:ia'
  publish_dates: true
  process:
    markdown: true
    twig: false
  twig_first: false
  never_cache_twig: false
  events:
    page: true
    twig: true
  markdown:
    extra: false
    auto_line_breaks: false
    auto_url_links: false
    escape_markup: false
    special_chars:
      '>': 'gt'
      '<': 'lt'
    valid_link_attributes:
      - rel
      - target
      - id
      - class
      - classes
  types: [html,htm,xml,txt,json,rss,atom]
  append_url_extension: ''
  expires: 604800
  cache_control:
  last_modified: false
  etag: false
  vary_accept_encoding: false
  redirect_default_route: false
  redirect_default_code: 302
  redirect_trailing_slash: true
  ignore_files: [.DS_Store]
  ignore_folders: [.git, .idea]
  ignore_hidden: true
  hide_empty_folders: false
  url_taxonomy_filters: true
  frontmatter:
    process_twig: false
    ignore_fields: ['form','forms']

La sección de Páginas del archivo system/config/system.yaml es donde configuras muchas de las opciones principales relacionadas con el tema. Por ejemplo, aquí es donde defines el tema utilizado para renderizar el sitio, el orden de las páginas, los ajustes predeterminados de procesamiento de twig y markdown, y más. Aquí es donde se toman la mayoría de las decisiones que afectan la forma en que se renderizan tus páginas.

Caché

cache:
  enabled: true
  check:
    method: file
  driver: auto
  prefix: 'g'
  purge_at: '0 4 * * *'
  clear_at: '0 3 * * *'
  clear_job_type: 'standard'
  clear_images_by_default: false
  cli_compatibility: false
  lifetime: 604800
  gzip: false
  allow_webserver_gzip: false
  redis:
    socket: false
    password:
    database:

La sección de Caché es donde puedes configurar los ajustes de caché del sitio. Puedes habilitar, deshabilitar, elegir el método y más.

Twig

twig:
  cache: true
  debug: true
  auto_reload: true
  autoescape: false
  undefined_functions: true
  undefined_filters: true
  umask_fix: false

La sección de Twig te proporciona un conjunto de herramientas rápidas para configurar Twig en tu sitio para depuración, caché y optimización.

Activos (Assets)

assets:
  css_pipeline: false
  css_pipeline_include_externals: true
  css_pipeline_before_excludes: true
  css_minify: true
  css_minify_windows: false
  css_rewrite: true
  js_pipeline: false
  js_pipeline_include_externals: true
  js_pipeline_before_excludes: true
  js_module_pipeline: false
  js_module_pipeline_include_externals: true
  js_module_pipeline_before_excludes: true
  js_minify: true
  enable_asset_timestamp: false
  enable_asset_sri: false
  collections:
    jquery: system://assets/jquery/jquery-2.x.min.js

La sección de Activos te permite configurar opciones relacionadas con el gestor de activos (JS, CSS).

Errores

errors:
  display: 0
  log: true

La sección de Errores determina cómo Grav maneja la visualización y el registro de errores.

Registro

log:
  handler: file
  syslog:
    facility: local6

La sección de Registro te permite configurar capacidades alternativas de registro para Grav.

Depurador

debugger:
  enabled: false
  provider: clockwork
  censored: false
  shutdown:
    close_connection: true

La sección de Depurador te permite activar el depurador de Grav. Una herramienta útil durante el desarrollo.

Imágenes

images:
  default_image_quality: 85
  cache_all: false
  cache_perms: '0755'
  debug: false
  auto_fix_orientation: false
  seofriendly: false
  cls:
    auto_sizes: false
    aspect_ratio: false
    retina_scale: 1
  defaults:
    loading: auto

La sección de Imágenes te da la capacidad de establecer la calidad de imagen predeterminada a la que se re-muestrean las imágenes, así como controlar el almacenamiento en caché de imágenes y las funciones de depuración.

Medios

media:
  enable_media_timestamp: false
  unsupported_inline_types: []
  allowed_fallback_types: []
  auto_metadata_exif: false

La sección de Medios maneja las opciones de configuración relacionadas con el manejo de archivos multimedia. Esto incluye la visualización de la marca de tiempo, el tamaño de carga y más.

Sesión

session:
  enabled: true
  initialize: true
  timeout: 1800
  name: grav-site
  uniqueness: path
  secure: false
  httponly: true
  samesite: Lax
  split: true
  domain:
  path:

Estas opciones determinan las propiedades de la sesión para tu sitio.

GPM

gpm:
  releases: stable
  proxy_url:
  method: 'auto'
  verify_peer: true
  official_gpm_only: true

Las opciones en la sección GPM controlan el GPM de Grav (Grav Package Manager). Por ejemplo, puedes restringir GPM para que utilice solo fuentes oficiales y seleccionar el método que GPM usa para recuperar paquetes. También puedes elegir entre las versiones estables y de prueba, así como configurar una URL de proxy.

Cuentas

accounts:
  type: regular
  storage: file

La configuración de Cuentas te permite probar los nuevos usuarios experimentales Flex. Básicamente, esto significa que los usuarios se almacenan como objetos Flex, lo que permite mayor poder y rendimiento.

Flex

flex:
  cache:
    index:
      enabled: true
      lifetime: 60
    object:
      enabled: true
      lifetime: 600
    render:
      enabled: true
      lifetime: 600

La configuración de caché de Flex Objects es nueva en Grav 1.7. Estos son los ajustes predeterminados para todos los tipos de Flex, pero pueden ser sobrescritos para cada Directorio Flex.

Modo estricto

strict_mode:
  yaml_compat: true
  twig_compat: true
  blueprint_compat: false

El modo estricto permite una migración más limpia a futuras versiones de Grav al pasar a las versiones más recientes de los procesadores YAML y Twig. Estos pueden no ser compatibles con todas las extensiones de terceros.

Configuración del sitio

Además del archivo system.yaml, Grav también proporciona un archivo de configuración predeterminado site.yaml que se usa para establecer configuraciones específicas del front-end, como el nombre del autor, el correo electrónico del autor, así como algunas configuraciones clave de taxonomía. Puedes sobrescribir estas configuraciones de la misma manera que lo harías con el system.yaml, proporcionando tu propio archivo de configuración en user/config/site.yaml. También puedes usar este archivo para poner configuraciones arbitrarias que desees referenciar desde tu contenido o plantillas.

El archivo predeterminado system/config/site.yaml que viene con Grav tiene un aspecto similar a este:

title: Grav                                 # Name of the site
default_lang: en                            # Default language for site (potentially used by theme)

author:
  name: John Appleseed                      # Default author name
  email: 'john@example.com'                 # Default author email

taxonomies: [category,tag]                  # Arbitrary list of taxonomy types

metadata:
  description: 'My Grav Site'               # Site description

summary:
  enabled: true                             # enable or disable summary of page
  format: short                             # long = summary delimiter will be ignored; short = use the first occurrence of delimiter or size
  size: 300                                 # Maximum length of summary (characters)
  delimiter: ===                            # The summary delimiter

redirects:
#  '/redirect-test': '/'                    # Redirect test goes to home page
#  '/old/(.*)': '/new/$1'                   # Would redirect /old/my-page to /new/my-page

routes:
#  '/something/else': '/blog/sample-3'      # Alias for /blog/sample-3
#  '/new/(.*)': '/blog/$1'                  # Regex any /new/my-page URL to /blog/my-page Route

blog:
  route: '/blog'                            # Custom value added (accessible via site.blog.route)

#menu:                                      # Menu Example
#    - text: Source
#      icon: github
#      url: https://github.com/getgrav/grav
#    - icon: twitter
#      url: http://twitter.com/getgrav

Desglosamos los elementos de este archivo de ejemplo:

Seguridad

Para mayor seguridad, existe el archivo system/config/security.yaml que establece algunos valores predeterminados sensatos y es utilizado por el plugin Admin al Guardar contenido, así como en la nueva sección de Informes de Herramientas.

La configuración predeterminada se ve así:

xss_whitelist: [admin.super]
xss_enabled:
    on_events: true
    invalid_protocols: true
    moz_binding: true
    html_inline_styles: true
    dangerous_tags: true
xss_invalid_protocols:
    - javascript
    - livescript
    - vbscript
    - mocha
    - feed
    - data
xss_dangerous_tags:
    - applet
    - meta
    - xml
    - blink
    - link
    - style
    - script
    - embed
    - object
    - iframe
    - frame
    - frameset
    - ilayer
    - layer
    - bgsound
    - title
    - base
uploads_dangerous_extensions:
    - php
    - html
    - htm
    - js
    - exe
sanitize_svg: true

Si deseas realizar algún cambio en estas configuraciones, deberías copiar este archivo a user/config/security.yaml y hacer las ediciones allí.

Otras configuraciones y archivos

La configuración del usuario es completamente opcional. Puedes sobrescribir tan poco o tanto de los valores predeterminados como necesites. Esto se aplica tanto a la configuración del sistema, del sitio, como a cualquier configuración de plugin en tu sitio.

Tampoco estás limitado a los archivos user/config/system.yaml o user/config/site.yaml como se describió anteriormente. Puedes crear cualquier archivo de configuración .yaml arbitrario en la carpeta user/config que desees, y Grav lo detectará automáticamente.

Por ejemplo, si el nuevo archivo de configuración se llama user/config/data.yaml y una variable yaml en este archivo se llama count:

count: 39

La variable se accedería en tu plantilla Twig usando la siguiente sintaxis:

También sería accesible a través de PHP desde cualquier complemento con el siguiente código:

$count_var = Grav::instance()['config']->get('data.count');

¡También puedes proporcionar un blueprint personalizado para habilitar tu archivo personalizado para ser editable en el complemento de administración. Consulta la receta correspondiente en la sección de Recetas de Admin.

Nombres de Espacios de Nombres para las Variables de Configuración

Las rutas a los archivos de configuración se usarán como un espacio de nombres para tus opciones de configuración.

Alternativamente, puedes poner todas las opciones en un solo archivo y usar estructuras YAML para especificar la jerarquía de tus opciones de configuración. Este espacio de nombres se crea a partir de una combinación de ruta + nombre de archivo + nombre de opción.

Por ejemplo: Una opción como author: Frank Smith en el archivo plugins/myplugin.yaml podría ser accesible como: plugins.myplugin.author. Sin embargo, también podrías tener un archivo plugins.yaml y en ese archivo tener una opción llamada myplugin: author: Frank Smith y todavía sería accesible a través del mismo espacio de nombres plugins.myplugin.author.

Algunos archivos de configuración de ejemplo podrían estructurarse de la siguiente manera:

¡Tener un archivo de configuración con espacio de nombres sobrescribirá o enmascarará todas las opciones que tengan la misma ruta en los archivos de configuración predeterminados!

Configuración de Plugins

La mayoría de los plugins tendrán su propio archivo de configuración YAML. Se recomienda copiar este archivo a la carpeta user/config/plugins/ en lugar de editar directamente las opciones de configuración en el archivo ubicado en el directorio del plugin. Hacer esto asegurará que una actualización del plugin no sobrescriba tus configuraciones y mantendrá todas tus opciones configurables en un solo lugar conveniente.

Si tienes un plugin llamado user/plugins/myplugin que tiene un archivo de configuración llamado user/plugins/myplugin/myplugin.yaml, deberías copiar este archivo a user/config/plugins/myplugin.yaml y editarlo allí.

El archivo YAML que existe en el directorio principal del plugin actuará como una copia de seguridad. Cualquier configuración listada allí y que no esté en la copia de la carpeta de usuario será tomada y utilizada por Grav.

Configuración de Temas

Las mismas reglas para los temas se aplican como lo hacían para los plugins. Así que si tienes un tema llamado user/themes/mytheme que tiene un archivo de configuración llamado user/themes/mytheme/mytheme.yaml, deberías copiar este archivo a user/config/themes/mytheme.yaml y editarlo allí.

• PMORENO
• 12-10-2024

• Anterior