From aaa4fae60d0e1b87af917829af1b1b4cceca9e31 Mon Sep 17 00:00:00 2001 From: Jieiku Date: Wed, 19 Aug 2026 11:51:59 -0700 Subject: Update Documentation --- content/overview-abridge/index.es.md | 59 +++++++++++++++++++++--------------- content/overview-abridge/index.fr.md | 59 +++++++++++++++++++++--------------- content/overview-abridge/index.md | 59 +++++++++++++++++++++--------------- content/overview-math.es.md | 2 +- content/overview-math.fr.md | 2 +- content/overview-math.md | 2 +- 6 files changed, 108 insertions(+), 75 deletions(-) (limited to 'content') diff --git a/content/overview-abridge/index.es.md b/content/overview-abridge/index.es.md index 99778b6..a17b4a8 100644 --- a/content/overview-abridge/index.es.md +++ b/content/overview-abridge/index.es.md @@ -29,7 +29,7 @@ Un tema para [Zola](https://getzola.org) rápido, ligero y moderno que utiliza H - Temas Dark, Light, Auto y Switcher. (colores personalizables, variables css) - [Resaltado de sintaxis de](https://abridge.pages.dev/overview-code-blocks/) código. (colores personalizables, variables css) - Bloques de código numerados con [resaltado de línea](https://abridge.pages.dev/overview-code-blocks/#toml). -- Sitio completamente Offline usando el PWA **o** configurando `search_library = "offline"` en `config.toml`. +- Sitio completamente Offline usando el PWA **o** configurando `search_library = "offline"` en `zola.toml`. - Soporte multi-idioma. - Soporte para búsquedas.[(elasticlunr](https://abridge.pages.dev/), [pagefind](https://abridge-pagefind.pages.dev/), [tinysearch](https://abridge-tinysearch.pages.dev/)) - Sugerencias de búsqueda teclas de navegación, `/` focus, `arrow` move, `enter` select, `escape` close. @@ -52,6 +52,17 @@ Un tema para [Zola](https://getzola.org) rápido, ligero y moderno que utiliza H - Media Components: [video](https://abridge.pages.dev/overview-rich-content/#video), [img](https://abridge.pages.dev/overview-images/#img-component), [imgswap](https://abridge.pages.dev/overview-images/#imgswap-component), [image](https://abridge.pages.dev/overview-rich-content/#image), [gif](https://abridge.pages.dev/overview-rich-content/#gif), [audio](https://abridge.pages.dev/overview-rich-content/#audio). - Otros Components: [showdata](https://abridge.pages.dev/overview-showdata/), [katex](https://abridge.pages.dev/overview-math/#usage-1). +## Usuarios de Windows + +A continuación utilizo algunos comandos de Linux durante la configuración; para contar con un entorno similar, puedes instalar [Msys2](https://www.msys2.org/). +En Msys2, utiliza Shift + Insert para pegar en la terminal; yo prefiero el lanzador UCRT64. + +```bash +MSYS2 +pacman -Syu +pacman -S --needed mingw-w64-ucrt-x86_64-git mingw-w64-ucrt-x86_64-zola rsync +``` + ## Inicio rápido Este tema requiere la versión {{}} o posterior de [Zola](https://www.getzola.org/documentation/getting-started/installation/) @@ -97,7 +108,7 @@ Copia algunos archivos del directorio del tema al directorio raíz de tu proyect ```bash rsync themes/abridge/.gitignore .gitignore -rsync themes/abridge/config.toml config.toml +rsync themes/abridge/zola.toml zola.toml rsync themes/abridge/content/_index.md content/ rsync -r themes/abridge/COPY-TO-ROOT-SASS/* sass/ rsync themes/abridge/netlify.toml netlify.toml @@ -105,17 +116,17 @@ rsync themes/abridge/package_abridge.js package_abridge.js rsync themes/abridge/package.json package.json ``` -- `config.toml` configuración base con todos los valores de configuración. +- `zola.toml` configuración base con todos los valores de configuración. - `content/_index.md` requerido para establecer la paginación. - `COPY-TO-ROOT-SASS/abridge.scss` overrides para personalizar las variables de Abridge. - `netlify.toml` configuración para desplegar su repo con netlfiy. - `package_abridge.js` node script para: actualizar la lista de archivos de caché en PWA, minify js, bundle js - `package.json` utilizado por node, define scripts y dependencias. -Descomenta la línea theme en el config.toml raíz de tu proyecto: +Descomenta la línea theme en el zola.toml raíz de tu proyecto: ```bash -sed -i 's/^#theme = "abridge"/theme = "abridge"/' config.toml +sed -i 's/^#theme = "abridge"/theme = "abridge"/' zola.toml ``` ### 4: Añadir nuevo contenido @@ -136,7 +147,7 @@ zola serve Zola iniciará el servidor web dev, accesible por defecto en `http://127.0.0.1:1111`. -Los cambios guardados se recargarán en vivo en el navegador. (pulse `ctrl+f5`, o mientras desarrolla configure `pwa=false` en `config.toml`) +Los cambios guardados se recargarán en vivo en el navegador. (pulse `ctrl+f5`, o mientras desarrolla configure `pwa=false` en `zola.toml`) ## Paginación {% raw %}{#pagination}{% endraw %} @@ -198,10 +209,10 @@ Si tiene abridge configurado para utilizar el modo conmutador en lugar de auto/o Si su visitante utiliza noscript o algún otro complemento de navegador que bloquee javascript, entonces estará atascado con cualquiera que sea el tema configurado por defecto para el modo conmutador. -Para ajustar este modo, debe establecer los siguientes dos valores de configuración en `abridge.scss` **Y** `config.toml`: +Para ajustar este modo, debe establecer los siguientes dos valores de configuración en `abridge.scss` **Y** `zola.toml`: ```scss -$switcherDefault: "dark",// default nojs switcher mode: dark, light (make sure to also set js_switcher_default in config.toml) +$switcherDefault: "dark",// default nojs switcher mode: dark, light (make sure to also set js_switcher_default in zola.toml) ``` ```toml @@ -210,13 +221,13 @@ js_switcher_default = "dark" # default nojs switcher mode: dark, light (make sur Por defecto abridge utiliza el modo oscuro para el conmutador, así que a menos que desee establecer el modo por defecto a la luz para los visitantes nojs/noscript, entonces usted no necesita preocuparse acerca de estos ajustes. -## Config.toml Configuración +## zola.toml Configuración -La mayoría de las opciones en `config.toml` se documentan por sí mismas. (obvio entre el nombre del valor config y los comentarios) +La mayoría de las opciones en `zola.toml` se documentan por sí mismas. (obvio entre el nombre del valor config y los comentarios) -Abridge trabajará con un `config.toml` barebones porque los valores por defecto se proporcionan en los archivos de plantilla. +Abridge trabajará con un `zola.toml` barebones porque los valores por defecto se proporcionan en los archivos de plantilla. -Recomiendo copiar todo el archivo config.toml como se indica en el paso 3, ya que proporciona todos los valores configurables. +Recomiendo copiar todo el archivo zola.toml como se indica en el paso 3, ya que proporciona todos los valores configurables. ### Menús superior y pie de página @@ -243,13 +254,13 @@ menu_footer = [ ### Etiquetas SEO y de cabecera {% raw %}{#seo}{% endraw %} -Puede revisar las etiquetas SEO en la component seo ubicada en `templates/components/seo.html`, todos los valores configurables deben estar en `config.toml` bajo `config.extra` o en los archivos markdown de contenido. +Puede revisar las etiquetas SEO en la component seo ubicada en `templates/components/seo.html`, todos los valores configurables deben estar en `zola.toml` bajo `config.extra` o en los archivos markdown de contenido. En el archivo markdown de su post debe establecer un título de menos de 60 caracteres y una descripción de entre 80 y 160 caracteres de longitud. La descripción es lo que se muestra en los resultados de búsqueda debajo del título de la página. Si no especifica una descripción de página, se utilizará en su lugar el archivo config.description del sitio principal. -También debe establecer palabras clave específicas de la página a menos que sus palabras clave definidas en config.toml sean suficientes, cualquier palabra clave que añada a la página es adicional a las definidas en config.toml, así que no añada esas mismas palabras clave a sus palabras clave de la página. +También debe establecer palabras clave específicas de la página a menos que sus palabras clave definidas en zola.toml sean suficientes, cualquier palabra clave que añada a la página es adicional a las definidas en zola.toml, así que no añada esas mismas palabras clave a sus palabras clave de la página. -Opcionalmente, también puede establecer una imagen específica de la página para los resultados de búsqueda utilizando page.extra.thumbnail. Facebook, Twitter y OpenGraph Cards son compatibles (imagen y descripción automáticas para los enlaces publicados). OpenGraph recomienda 1200 x 630 (1,9:1). Twitter recomienda 2:1 para las grandes y 1:1 para las pequeñas. Si no establece una miniatura específica para la página, se utilizará en su lugar el banner definido en config.toml. +Opcionalmente, también puede establecer una imagen específica de la página para los resultados de búsqueda utilizando page.extra.thumbnail. Facebook, Twitter y OpenGraph Cards son compatibles (imagen y descripción automáticas para los enlaces publicados). OpenGraph recomienda 1200 x 630 (1,9:1). Twitter recomienda 2:1 para las grandes y 1:1 para las pequeñas. Si no establece una miniatura específica para la página, se utilizará en su lugar el banner definido en zola.toml. Consulta [overview-images](https://raw.githubusercontent.com/Jieiku/abridge/master/content/overview-images/index.md) para ver un ejemplo: @@ -266,7 +277,7 @@ KaTeX se puede utilizar para mostrar matemáticas complejas, es una "Rápida com Puedes ver una demo en [esta página](https://abridge.pages.dev/overview-math/). -Para un mejor rendimiento, recomiendo sólo habilitar las matemáticas en una [base por página en sus archivos post.md](https://github.com/Jieiku/abridge/blob/master/content/overview-math.md?plain=1#L11-L13), en lugar de en su archivo config.toml principal. +Para un mejor rendimiento, recomiendo sólo habilitar las matemáticas en una [base por página en sus archivos post.md](https://github.com/Jieiku/abridge/blob/master/content/overview-math.md?plain=1#L11-L13), en lugar de en su archivo zola.toml principal. ### PWA, Aplicación Web Progresiva {% raw %}{#pwa}{% endraw %} @@ -276,15 +287,15 @@ Si utilizas Chrome en tu ordenador, busca el botón de instalación al final de Hay un script npm para generar la lista de caché de archivos y la minificación `npm run abridge`. Mi archivo [netlify.toml](https://github.com/Jieiku/abridge/blob/master/netlify.toml) ejecuta automáticamente este script npm durante el despliegue del sitio, por lo que todo es automático. Si Zola fuera capaz de crear un archivo js, entonces sería posible generar la lista de archivos de caché dinámicamente durante la compilación en lugar de depender de node/npm. -Para utilizar una lista específica de archivos en lugar de todos los archivos de editar la entrada `pwa_BASE_CACHE_FILES` en `config.toml`. Si incluso un solo archivo en la lista de caché no se encuentra entonces no pre caché de la lista, por lo que sólo la caché a medida que navega. (Si está configurando por primera vez, pruebe sólo con un par de páginas) +Para utilizar una lista específica de archivos en lugar de todos los archivos de editar la entrada `pwa_BASE_CACHE_FILES` en `zola.toml`. Si incluso un solo archivo en la lista de caché no se encuentra entonces no pre caché de la lista, por lo que sólo la caché a medida que navega. (Si está configurando por primera vez, pruebe sólo con un par de páginas) -La función PWA también es fácil de desactivar simplemente configurando `pwa = false` en `config.toml` +La función PWA también es fácil de desactivar simplemente configurando `pwa = false` en `zola.toml` ## Optimización del rendimiento ### Archivos Javascript -Todo javascript puede ser desactivado en `config.toml`: +Todo javascript puede ser desactivado en `zola.toml`: ```toml build_search_index = false @@ -317,7 +328,7 @@ Estos son los archivos javascript utilizados por Abridge: Todos los bundles necesarios son generados dinámicamente por el script node [package\_abridge.js](https://github.com/Jieiku/abridge/blob/master/package_abridge.js) -El script node escaneará su config.toml en busca de los valores de configuración relevantes y, basándose en su config.tomnl, generará los paquetes necesarios. +El script node escaneará su zola.toml en busca de los valores de configuración relevantes y, basándose en su config.tomnl, generará los paquetes necesarios. Todo lo que se necesita es `zola build && npm run abridge`. @@ -335,7 +346,7 @@ Para utilizar tinysearch se requieren pasos adicionales. ```bash npm install -sed -i 's/^search_library =.*/search_library = "pagefind"/' config.toml +sed -i 's/^search_library =.*/search_library = "pagefind"/' zola.toml npm run abridge # zola serve ``` @@ -343,14 +354,14 @@ npm run abridge **Cambiar a elasticlunr:** ```bash -sed -i 's/^search_library =.*/search_library = "elasticlunr"/' config.toml +sed -i 's/^search_library =.*/search_library = "elasticlunr"/' zola.toml npm run abridge ``` **Cambiar a nosearch:** ```bash -sed -i 's/^search_library =.*/search_library = "false"/' config.toml +sed -i 's/^search_library =.*/search_library = "false"/' zola.toml npm run abridge ``` @@ -369,7 +380,7 @@ exit # reload shell environment Cambiar Abridge a tinysearch ```bash -sed -i 's/^search_library =.*/search_library = "tinysearch"/' config.toml +sed -i 's/^search_library =.*/search_library = "tinysearch"/' zola.toml npm run abridge tinysearch --optimize --path static public/data_tinysearch/index.html # zola serve diff --git a/content/overview-abridge/index.fr.md b/content/overview-abridge/index.fr.md index b6b959a..187d153 100644 --- a/content/overview-abridge/index.fr.md +++ b/content/overview-abridge/index.fr.md @@ -29,7 +29,7 @@ Un thème [Zola](https://getzola.org) rapide, léger et moderne, utilisant un HT - Thèmes Dark, Light, Auto et Switcher. (les couleurs peuvent être personnalisées, variables css) - Code [coloration syntaxique](https://abridge.pages.dev/overview-code-blocks/). (couleurs personnalisables, variables css) - Blocs de code numérotés avec [mise en évidence des lignes](https://abridge.pages.dev/overview-code-blocks/#toml). -- Site entièrement hors ligne en utilisant le PWA **ou** en mettant `search_library = "offline"` dans `config.toml`. +- Site entièrement hors ligne en utilisant le PWA **ou** en mettant `search_library = "offline"` dans `zola.toml`. - Support multi-langues. - Support de la recherche. ([elasticlunr](https://abridge.pages.dev/), [pagefind](https://abridge-pagefind.pages.dev/), [tinysearch](https://abridge-tinysearch.pages.dev/)) - Touches de navigation pour les suggestions de recherche, `/` focus, `arrow` move, `enter` select, `escape` close. @@ -52,6 +52,17 @@ Un thème [Zola](https://getzola.org) rapide, léger et moderne, utilisant un HT - Raccourcis pour les médias : [video](https://abridge.pages.dev/overview-rich-content/#video), [img](https://abridge.pages.dev/overview-images/#img-component), [imgswap](https://abridge.pages.dev/overview-images/#imgswap-component), [image](https://abridge.pages.dev/overview-rich-content/#image), [gif](https://abridge.pages.dev/overview-rich-content/#gif), [audio](https://abridge.pages.dev/overview-rich-content/#audio). - Autres codes courts : [showdata](https://abridge.pages.dev/overview-showdata/), [katex](https://abridge.pages.dev/overview-math/#usage-1). +## Utilisateurs de Windows + +J'utilise ci-dessous quelques commandes Linux lors de la configuration ; pour disposer d'un environnement similaire, vous pouvez installer [Msys2](https://www.msys2.org/). +Avec Msys2, utilisez les touches Maj + Inser pour coller du texte dans le terminal ; je privilégie le lanceur UCRT64. + +```bash +MSYS2 +pacman -Syu +pacman -S --needed mingw-w64-ucrt-x86_64-git mingw-w64-ucrt-x86_64-zola rsync +``` + ## Démarrage rapide Ce thème nécessite la version {{}} ou ultérieure de [Zola](https://www.getzola.org/documentation/getting-started/installation/) @@ -97,7 +108,7 @@ Copiez quelques fichiers du répertoire theme vers le répertoire racine de votr ```bash rsync themes/abridge/.gitignore .gitignore -rsync themes/abridge/config.toml config.toml +rsync themes/abridge/zola.toml zola.toml rsync themes/abridge/content/_index.md content/ rsync -r themes/abridge/COPY-TO-ROOT-SASS/* sass/ rsync themes/abridge/netlify.toml netlify.toml @@ -105,17 +116,17 @@ rsync themes/abridge/package_abridge.js package_abridge.js rsync themes/abridge/package.json package.json ``` -- `config.toml` configuration de base avec toutes les valeurs de configuration. +- `zola.toml` configuration de base avec toutes les valeurs de configuration. - `content/_index.md` nécessaire pour définir la pagination. - `COPY-TO-ROOT-SASS/abridge.scss` pour personnaliser les variables d'Abridge. - `netlify.toml` pour déployer votre repo avec netlfiy. - `package_abridge.js` script node pour : mettre à jour la liste des fichiers cache dans PWA, minify js, bundle js - `package.json` utilisé par node, définit les scripts et les dépendances. -Décommentez la ligne theme dans le fichier config.toml de la racine de votre projet : +Décommentez la ligne theme dans le fichier zola.toml de la racine de votre projet : ```bash -sed -i 's/^#theme = "abridge"/theme = "abridge"/' config.toml +sed -i 's/^#theme = "abridge"/theme = "abridge"/' zola.toml ``` ### 4 : Ajouter un nouveau contenu @@ -136,7 +147,7 @@ zola serve Zola va démarrer le serveur web dev, accessible par défaut à `http://127.0.0.1:1111`. -Les changements sauvegardés seront rechargés en direct dans le navigateur. (appuyez sur `ctrl+f5`, ou pendant le développement mettez `pwa=false` dans `config.toml`) +Les changements sauvegardés seront rechargés en direct dans le navigateur. (appuyez sur `ctrl+f5`, ou pendant le développement mettez `pwa=false` dans `zola.toml`) ## Pagination {% raw %}{#pagination}{% endraw %} @@ -198,10 +209,10 @@ Si vous avez configuré abridge pour utiliser le mode switcher au lieu de auto/d Si votre visiteur utilise noscript ou un autre module complémentaire de navigateur bloquant le javascript, il sera bloqué avec le thème par défaut configuré pour le mode de commutation. -Pour ajuster ce mode, vous devez définir les deux valeurs de configuration suivantes dans `abridge.scss` **ET** `config.toml` : +Pour ajuster ce mode, vous devez définir les deux valeurs de configuration suivantes dans `abridge.scss` **ET** `zola.toml` : ```scss -$switcherDefault: "dark",// mode de commutation nojs par défaut : dark, light (assurez-vous de définir également js_switcher_default dans config.toml) +$switcherDefault: "dark",// mode de commutation nojs par défaut : dark, light (assurez-vous de définir également js_switcher_default dans zola.toml) ``` ```toml @@ -210,13 +221,13 @@ js_switcher_default = "dark" # mode de commutation nojs par défaut : sombre, cl Par défaut, abridge utilise le mode sombre pour le sélecteur, donc à moins que vous ne souhaitiez mettre le mode par défaut à clair pour les visiteurs nojs/noscript, vous n'avez pas besoin de vous préoccuper de ces paramètres. -## Config.toml Configuration +## zola.toml Configuration -La plupart des options de `config.toml` sont auto-documentées. (évident entre le nom de la valeur de configuration et les commentaires) +La plupart des options de `zola.toml` sont auto-documentées. (évident entre le nom de la valeur de configuration et les commentaires) -Abridge fonctionnera avec un `config.toml` dépouillé parce que les valeurs par défaut sont fournies dans les fichiers modèles. +Abridge fonctionnera avec un `zola.toml` dépouillé parce que les valeurs par défaut sont fournies dans les fichiers modèles. -Je recommande de copier l'intégralité du fichier config.toml comme indiqué à l'étape 3, car il contient toutes les valeurs configurables. +Je recommande de copier l'intégralité du fichier zola.toml comme indiqué à l'étape 3, car il contient toutes les valeurs configurables. ### Menus du haut et du bas de page @@ -243,13 +254,13 @@ menu_footer = [ ### SEO et balises d'en-tête {% raw %}{#seo}{% endraw %} -Vous pouvez revoir les balises SEO dans la component seo située dans `templates/components/seo.html`, toutes les valeurs configurables doivent être dans `config.toml` sous `config.extra` ou dans les fichiers markdown du contenu. +Vous pouvez revoir les balises SEO dans la component seo située dans `templates/components/seo.html`, toutes les valeurs configurables doivent être dans `zola.toml` sous `config.extra` ou dans les fichiers markdown du contenu. Dans votre fichier markdown, vous devez définir un titre de moins de 60 caractères et une description de 80 à 160 caractères. La description est ce qui est affiché dans les résultats de recherche sous le titre de la page. Partout où vous ne définissez pas de description de page, le fichier config.description du site principal sera utilisé à la place. -Vous devez également définir des mots-clés spécifiques à la page, à moins que les mots-clés définis dans config.toml ne suffisent. Tous les mots-clés que vous ajoutez à la page s'ajoutent à ceux définis dans config.toml ; n'ajoutez donc pas ces mêmes mots-clés aux mots-clés de votre page. +Vous devez également définir des mots-clés spécifiques à la page, à moins que les mots-clés définis dans zola.toml ne suffisent. Tous les mots-clés que vous ajoutez à la page s'ajoutent à ceux définis dans zola.toml ; n'ajoutez donc pas ces mêmes mots-clés aux mots-clés de votre page. -Vous pouvez également définir une image spécifique à la page pour les résultats de recherche en utilisant page.extra.thumbnail. Les cartes Facebook, Twitter et OpenGraph sont prises en charge (image et description automatiques pour les liens affichés). OpenGraph recommande une taille de 1200 x 630 (1,9:1). Twitter recommande 2:1 pour les grandes images et 1:1 pour les petites. Si vous ne définissez pas de vignette spécifique à une page, la bannière définie dans config.toml sera utilisée à la place. +Vous pouvez également définir une image spécifique à la page pour les résultats de recherche en utilisant page.extra.thumbnail. Les cartes Facebook, Twitter et OpenGraph sont prises en charge (image et description automatiques pour les liens affichés). OpenGraph recommande une taille de 1200 x 630 (1,9:1). Twitter recommande 2:1 pour les grandes images et 1:1 pour les petites. Si vous ne définissez pas de vignette spécifique à une page, la bannière définie dans zola.toml sera utilisée à la place. Référez-vous à [overview-images](https://raw.githubusercontent.com/Jieiku/abridge/master/content/overview-images/index.md) pour un exemple : @@ -266,7 +277,7 @@ KaTeX peut être utilisé pour afficher des mathématiques complexes. Il s'agit Vous pouvez voir une démo sur [cette page] (https://abridge.pages.dev/overview-math/). -Pour de meilleures performances, je recommande de n'activer les mathématiques que [par base de page dans vos fichiers post.md](https://github.com/Jieiku/abridge/blob/master/content/overview-math.md?plain=1#L11-L13), plutôt que dans votre fichier config.toml principal. +Pour de meilleures performances, je recommande de n'activer les mathématiques que [par base de page dans vos fichiers post.md](https://github.com/Jieiku/abridge/blob/master/content/overview-math.md?plain=1#L11-L13), plutôt que dans votre fichier zola.toml principal. ### PWA, Progressive Web App {% raw %}{#pwa}{% endraw %} @@ -276,15 +287,15 @@ Si vous utilisez Chrome sur un ordinateur de bureau, cherchez le bouton d'instal Il y a un script npm pour générer la liste de cache des fichiers et la minification `npm run abridge`. Mon fichier [netlify.toml](https://github.com/Jieiku/abridge/blob/master/netlify.toml) exécute automatiquement ce script npm lors du déploiement du site, donc tout est automatique. Si Zola était capable de modéliser un fichier js, alors il serait possible de générer la liste des fichiers cache dynamiquement lors de la construction au lieu de s'appuyer sur node/npm. -Pour utiliser une liste spécifique de fichiers au lieu de tous les fichiers, éditez l'entrée `pwa_BASE_CACHE_FILES` dans `config.toml`. Si un seul fichier de la liste de cache est manquant, alors la liste ne sera pas pré-cachée, et le cache ne se fera qu'au fur et à mesure que vous naviguerez. (Si vous vous installez pour la première fois, testez avec seulement quelques pages). +Pour utiliser une liste spécifique de fichiers au lieu de tous les fichiers, éditez l'entrée `pwa_BASE_CACHE_FILES` dans `zola.toml`. Si un seul fichier de la liste de cache est manquant, alors la liste ne sera pas pré-cachée, et le cache ne se fera qu'au fur et à mesure que vous naviguerez. (Si vous vous installez pour la première fois, testez avec seulement quelques pages). -La fonctionnalité PWA est également facile à désactiver en mettant simplement `pwa = false` dans `config.toml` +La fonctionnalité PWA est également facile à désactiver en mettant simplement `pwa = false` dans `zola.toml` ## Optimisation des performances ### Fichiers Javascript -Tout le javascript peut être désactivé dans `config.toml` : +Tout le javascript peut être désactivé dans `zola.toml` : ```toml build_search_index = false @@ -317,7 +328,7 @@ Voici les fichiers javascript utilisés par Abridge : Tous les bundles nécessaires sont générés dynamiquement par le script node [package_abridge.js](https://github.com/Jieiku/abridge/blob/master/package_abridge.js) -Le script node va analyser votre config.toml pour trouver les valeurs de configuration pertinentes, et ensuite, en se basant sur votre config.tomnl, générer les bundles nécessaires. +Le script node va analyser votre zola.toml pour trouver les valeurs de configuration pertinentes, et ensuite, en se basant sur votre config.tomnl, générer les bundles nécessaires. Tout ce qui est nécessaire est `zola build && npm run abridge`. @@ -335,7 +346,7 @@ Pour utiliser tinysearch, des étapes supplémentaires sont nécessaires. ```bash npm install -sed -i 's/^search_library =.*/search_library = "pagefind"/' config.toml +sed -i 's/^search_library =.*/search_library = "pagefind"/' zola.toml npm run abridge # zola serve ``` @@ -343,14 +354,14 @@ npm run abridge **Switch to elasticlunr:** ```bash -sed -i 's/^search_library =.*/search_library = "elasticlunr"/' config.toml +sed -i 's/^search_library =.*/search_library = "elasticlunr"/' zola.toml npm run abridge ``` **Switch to nosearch:** ```bash -sed -i 's/^search_library =.*/search_library = "false"/' config.toml +sed -i 's/^search_library =.*/search_library = "false"/' zola.toml npm run abridge ``` @@ -369,7 +380,7 @@ exit # reload shell environment Passer Abridge à tinysearch : ```bash -sed -i 's/^search_library =.*/search_library = "tinysearch"/' config.toml +sed -i 's/^search_library =.*/search_library = "tinysearch"/' zola.toml npm run abridge tinysearch --optimize --path static public/data_tinysearch/index.html # zola serve diff --git a/content/overview-abridge/index.md b/content/overview-abridge/index.md index a7a49b1..130759f 100644 --- a/content/overview-abridge/index.md +++ b/content/overview-abridge/index.md @@ -29,7 +29,7 @@ A fast, lightweight, and modern [Zola](https://getzola.org) theme utilizing clas - Dark, Light, Auto, and Switcher themes. (colors can be customized, css variables) - Code [syntax highlighting](https://abridge.pages.dev/overview-code-blocks/). (colors can be customized, css variables) - Numbered code blocks with [line highlighting](https://abridge.pages.dev/overview-code-blocks/#toml). -- Entirely Offline Site by using the PWA **or** by setting `search_library = "offline"` in `config.toml`. +- Entirely Offline Site by using the PWA **or** by setting `search_library = "offline"` in `zola.toml`. - Multi-language support. - Search support. ([elasticlunr](https://abridge.pages.dev/), [pagefind](https://abridge-pagefind.pages.dev/), [tinysearch](https://abridge-tinysearch.pages.dev/)) - Search Suggestions navigation keys, `/` focus, `arrow` move, `enter` select, `escape` close. @@ -52,6 +52,17 @@ A fast, lightweight, and modern [Zola](https://getzola.org) theme utilizing clas - Media Components: [video](https://abridge.pages.dev/overview-rich-content/#video), [img](https://abridge.pages.dev/overview-images/#img-component), [imgswap](https://abridge.pages.dev/overview-images/#imgswap-component), [image](https://abridge.pages.dev/overview-rich-content/#image), [gif](https://abridge.pages.dev/overview-rich-content/#gif), [audio](https://abridge.pages.dev/overview-rich-content/#audio). - Other Components: [showdata](https://abridge.pages.dev/overview-showdata/), [katex](https://abridge.pages.dev/overview-math/#usage-1). +## Windows Users + +Below I use some linux commands during setup, to have a similar environment you can install [Msys2](https://www.msys2.org/). +With msys2 use shift insert to paste into the terminal, I prefer the UCRT64 launcher. + +```bash +MSYS2 +pacman -Syu +pacman -S --needed mingw-w64-ucrt-x86_64-git mingw-w64-ucrt-x86_64-zola rsync +``` + ## Quick Start This theme requires version {{}} or later of [Zola](https://www.getzola.org/documentation/getting-started/installation/) @@ -97,7 +108,7 @@ Copy some files from the theme directory to your project's root directory: ```bash rsync themes/abridge/.gitignore .gitignore -rsync themes/abridge/config.toml config.toml +rsync themes/abridge/zola.toml zola.toml rsync themes/abridge/content/_index.md content/ rsync -r themes/abridge/COPY-TO-ROOT-SASS/* sass/ rsync themes/abridge/netlify.toml netlify.toml @@ -105,17 +116,17 @@ rsync themes/abridge/package_abridge.js package_abridge.js rsync themes/abridge/package.json package.json ``` -- `config.toml` base configuration with all config values. +- `zola.toml` base configuration with all config values. - `content/_index.md` required to set pagination. - `COPY-TO-ROOT-SASS/abridge.scss` overrides to customize Abridge variables. - `netlify.toml` settings to deploy your repo with netlfiy. - `package_abridge.js` node script to: update cache files list in PWA, minify js, bundle js - `package.json` used by node, defines scripts and dependencies. -Uncomment the theme line in your project's root config.toml: +Uncomment the theme line in your project's root zola.toml: ```bash -sed -i 's/^#theme = "abridge"/theme = "abridge"/' config.toml +sed -i 's/^#theme = "abridge"/theme = "abridge"/' zola.toml ``` ### 4: Add new content @@ -136,7 +147,7 @@ zola serve Zola will start the dev web server, accessible by default at `http://127.0.0.1:1111`. -Saved changes will live reload in the browser. (press `ctrl+f5`, or while developing set `pwa=false` in `config.toml`) +Saved changes will live reload in the browser. (press `ctrl+f5`, or while developing set `pwa=false` in `zola.toml`) ## Pagination {% raw %}{#pagination}{% endraw %} @@ -198,10 +209,10 @@ If you have abridge configured to use the switcher mode instead of auto/dark/lig If your visitor uses noscript or some other javascript blocking browser addon, then they will be stuck with whatever the configured default theme is for the switcher mode. -To adjust this mode you would set the following two config values in `abridge.scss` **AND** `config.toml`: +To adjust this mode you would set the following two config values in `abridge.scss` **AND** `zola.toml`: ```scss -$switcherDefault: "dark",// default nojs switcher mode: dark, light (make sure to also set js_switcher_default in config.toml) +$switcherDefault: "dark",// default nojs switcher mode: dark, light (make sure to also set js_switcher_default in zola.toml) ``` ```toml @@ -210,13 +221,13 @@ js_switcher_default = "dark" # default nojs switcher mode: dark, light (make sur By default abridge uses dark mode for the switcher, so unless you want to set the default mode to light for nojs/noscript visitors, then you do not need to worry about these settings. -## Config.toml Configuration +## Zola.toml Configuration -Most Options in `config.toml` are self documenting. (obvious between name of config value and comments) +Most Options in `zola.toml` are self documenting. (obvious between name of config value and comments) -Abridge will work with a barebones `config.toml` because default values are provided in the template files. +Abridge will work with a barebones `zola.toml` because default values are provided in the template files. -I recommend copying the entire config.toml file as outlined in Step 3 as it provides all configurable values. +I recommend copying the entire zola.toml file as outlined in Step 3 as it provides all configurable values. ### Top and Footer menus @@ -243,13 +254,13 @@ menu_footer = [ ### SEO and Header Tags {% raw %}{#seo}{% endraw %} -You can review the SEO tags in the seo component located at `templates/components/seo.html`, all configurable values should be in `config.toml` under `config.extra` or in the content markdown files. +You can review the SEO tags in the seo component located at `templates/components/seo.html`, all configurable values should be in `zola.toml` under `config.extra` or in the content markdown files. In your post markdown file you should set a title less than 60 characters and a description between 80 and 160 characters in length. The description is what is displayed in search results below the page title. Anywhere that you do not set a page description, the primary site config.description will be used instead. -You should also set page specific keywords unless your keywords defined in config.toml suffice, any keywords that you add to the page are in addition to the ones defined in config.toml, so do not add those same keywords to your page keywords. +You should also set page specific keywords unless your keywords defined in zola.toml suffice, any keywords that you add to the page are in addition to the ones defined in zola.toml, so do not add those same keywords to your page keywords. -You can optionally also set a page specific image for search results by using page.extra.thumbnail. Facebook, Twitter, and OpenGraph Cards are supported (automatic image & description for posted links). OpenGraph recommends 1200 x 630 (1.9:1). Twitter recommends 2:1 for large and 1:1 for small. If you do not set a page specific thumbnail then the banner defined in config.toml will be used instead. +You can optionally also set a page specific image for search results by using page.extra.thumbnail. Facebook, Twitter, and OpenGraph Cards are supported (automatic image & description for posted links). OpenGraph recommends 1200 x 630 (1.9:1). Twitter recommends 2:1 for large and 1:1 for small. If you do not set a page specific thumbnail then the banner defined in zola.toml will be used instead. Refer to [overview-images](https://raw.githubusercontent.com/Jieiku/abridge/master/content/overview-images/index.md) for an example. @@ -266,7 +277,7 @@ KaTeX can be used to display complex mathematics, it is a "Fast math typesetting You can see a demo on [this page](https://abridge.pages.dev/overview-math/). -For better performance I recommend only enabling math on a [per page bases in your post.md files](https://github.com/Jieiku/abridge/blob/master/content/overview-math.md?plain=1#L11-L13), instead of in your main config.toml file. +For better performance I recommend only enabling math on a [per page bases in your post.md files](https://github.com/Jieiku/abridge/blob/master/content/overview-math.md?plain=1#L11-L13), instead of in your main zola.toml file. ### PWA, Progressive Web App {% raw %}{#pwa}{% endraw %} @@ -276,15 +287,15 @@ If using Chrome on desktop then look at the end of the address bar for the insta There is an npm script to generate the file cache list and minification `npm run abridge`. My [netlify.toml](https://github.com/Jieiku/abridge/blob/master/netlify.toml) file automatically runs this npm script during site deployment, so everything is automatic. If Zola was able to template a js file then it might be possible to generate the list of cache files dynamically at build instead of relying on node/npm. -To use a specific list of files instead of all files edit the `pwa_BASE_CACHE_FILES` entry in `config.toml`. If even a single file in the cache list is missing then it wont pre cache the list, so it will only cache as you browse. (If just initially setting up, test with only a couple pages.) +To use a specific list of files instead of all files edit the `pwa_BASE_CACHE_FILES` entry in `zola.toml`. If even a single file in the cache list is missing then it wont pre cache the list, so it will only cache as you browse. (If just initially setting up, test with only a couple pages.) -The PWA feature is also easy to disable by simply setting `pwa = false` in `config.toml` +The PWA feature is also easy to disable by simply setting `pwa = false` in `zola.toml` ## Performance Optimization ### Javascript files -All javascript can be disabled in `config.toml`: +All javascript can be disabled in `zola.toml`: ```toml build_search_index = false @@ -317,7 +328,7 @@ These are the javascript files used by Abridge: All necessary bundles are dynamically generated by the node script [package_abridge.js](https://github.com/Jieiku/abridge/blob/master/package_abridge.js) -The node script will scan your config.toml for relevant config values, and then based on your config.tomnl generate your required bundles. +The node script will scan your zola.toml for relevant config values, and then based on your zola.tomnl generate your required bundles. All that is necessary is `zola build && npm run abridge`. @@ -335,7 +346,7 @@ To use tinysearch extra steps are required. ```bash npm install -sed -i 's/^search_library =.*/search_library = "pagefind"/' config.toml +sed -i 's/^search_library =.*/search_library = "pagefind"/' zola.toml npm run abridge # zola serve ``` @@ -343,14 +354,14 @@ npm run abridge **Switch to elasticlunr:** ```bash -sed -i 's/^search_library =.*/search_library = "elasticlunr"/' config.toml +sed -i 's/^search_library =.*/search_library = "elasticlunr"/' zola.toml npm run abridge ``` **Switch to nosearch:** ```bash -sed -i 's/^search_library =.*/search_library = "false"/' config.toml +sed -i 's/^search_library =.*/search_library = "false"/' zola.toml npm run abridge ``` @@ -369,7 +380,7 @@ exit # reload shell environment Switch Abridge to tinysearch: ```bash -sed -i 's/^search_library =.*/search_library = "tinysearch"/' config.toml +sed -i 's/^search_library =.*/search_library = "tinysearch"/' zola.toml npm run abridge tinysearch --optimize --path static public/data_tinysearch/index.html # zola serve diff --git a/content/overview-math.es.md b/content/overview-math.es.md index 81bafbc..ce24c57 100644 --- a/content/overview-math.es.md +++ b/content/overview-math.es.md @@ -27,7 +27,7 @@ Puede activar el soporte $\\KaTeX$ globalmente, por sección o por página. ## Habilitar globalmente -Para habilitar el soporte $\\KaTeX$ globalmente, añada `math = true` bajo `[extra]` del `config.toml` +Para habilitar el soporte $\\KaTeX$ globalmente, añada `math = true` bajo `[extra]` del `zola.toml` en la raíz de su sitio. También puede añadir `math_auto_render = true` y cada sección y página de su sitio cargará la [extensión](https://katex.org/docs/autorender.html) KaTeX [autorender](https://katex.org/docs/autorender.html). diff --git a/content/overview-math.fr.md b/content/overview-math.fr.md index a7a2efe..8f991bf 100644 --- a/content/overview-math.fr.md +++ b/content/overview-math.fr.md @@ -27,7 +27,7 @@ Vous pouvez activer le $\KaTeX$ prise en charge globale, par section ou par page ## Activer globalement -Pour activer le $\KaTeX$ prise en charge dans le monde entier, ajoutez `math = true` sous `[extra]` à la `config.toml` +Pour activer le $\KaTeX$ prise en charge dans le monde entier, ajoutez `math = true` sous `[extra]` à la `zola.toml` racine de votre site. Maintenant, le component katex sera rendu, vous pouvez également ajouter `math_auto_render = true` et chaque section et page de votre site chargera l' [extension KaTeX autorender](https://katex.org/docs/autorender.html). diff --git a/content/overview-math.md b/content/overview-math.md index 57ef6fd..ea8f267 100644 --- a/content/overview-math.md +++ b/content/overview-math.md @@ -27,7 +27,7 @@ You can enable the $\KaTeX$ support globally, per-section or per-page basis. ## Enable Globally -To enable the $\KaTeX$ support globally, add `math = true` under `[extra]` of the `config.toml` +To enable the $\KaTeX$ support globally, add `math = true` under `[extra]` of the `zola.toml` at your site root. Now the katex component will be rendered, you can also add `math_auto_render = true` and every section and page of your site will load the KaTeX [autorender extension](https://katex.org/docs/autorender.html). -- cgit v1.3.1