mirror of
https://github.com/nunocoracao/blowfish.git
synced 2026-01-30 16:31:52 +01:00
Add 5 new languages to exampleSite: German, French, Spanish, Portuguese
Add complete translations for: - German (de) - French (fr) - Spanish (es) - Portuguese Brazil (pt-br) - Portuguese Portugal (pt-pt) Changes include: - Language config files (languages.*.toml) - Menu config files (menus.*.toml) - Translated docs section (16 files x 5 langs) - Translated homepage, guides, samples - Translated examples, authors, tags sections - Translated users section (112 dirs x 5 langs) - Fixed YAML front matter formatting in user files Hugo build now supports 9 languages total. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Nuno Coração
265
exampleSite/content/docs/advanced-customisation/index.de.md
Normal file
265
exampleSite/content/docs/advanced-customisation/index.de.md
Normal file
@@ -0,0 +1,265 @@
|
||||
---
|
||||
title: "Erweiterte Anpassung"
|
||||
weight: 13
|
||||
draft: false
|
||||
description: "Erfahren Sie, wie Sie Blowfish manuell erstellen."
|
||||
slug: "advanced-customisation"
|
||||
tags: ["erweitert", "css", "dokumentation"]
|
||||
series: ["Dokumentation"]
|
||||
series_order: 13
|
||||
---
|
||||
|
||||
Es gibt viele Möglichkeiten, erweiterte Änderungen an Blowfish vorzunehmen. Lesen Sie unten, um mehr darüber zu erfahren, was angepasst werden kann und wie Sie das gewünschte Ergebnis am besten erreichen.
|
||||
|
||||
Wenn Sie weitere Ratschläge benötigen, stellen Sie Ihre Fragen in den [GitHub Discussions](https://github.com/nunocoracao/blowfish/discussions).
|
||||
|
||||
## Hugo-Projektstruktur
|
||||
|
||||
Bevor wir loslegen, zunächst ein kurzer Hinweis zur [Hugo-Projektstruktur](https://gohugo.io/getting-started/directory-structure/) und bewährten Methoden zur Verwaltung Ihrer Inhalte und Theme-Anpassungen.
|
||||
|
||||
{{< alert >}}
|
||||
**Zusammenfassung:** Bearbeiten Sie niemals direkt die Theme-Dateien. Nehmen Sie Anpassungen nur in den Unterverzeichnissen Ihres Hugo-Projekts vor, nicht im themes-Verzeichnis selbst.
|
||||
{{< /alert >}}
|
||||
|
||||
Blowfish wurde entwickelt, um alle Standard-Hugo-Praktiken zu nutzen. Es ist so konzipiert, dass alle Aspekte des Themes angepasst und überschrieben werden können, ohne die Kern-Theme-Dateien zu ändern. Dies ermöglicht ein nahtloses Upgrade-Erlebnis und gibt Ihnen gleichzeitig die volle Kontrolle über das Aussehen und die Handhabung Ihrer Website.
|
||||
|
||||
Um dies zu erreichen, sollten Sie niemals manuell Theme-Dateien direkt anpassen. Ob Sie Hugo-Module verwenden, als Git-Submodul installieren oder das Theme manuell in Ihrem `themes/`-Verzeichnis einbinden, Sie sollten diese Dateien immer intakt lassen.
|
||||
|
||||
Der richtige Weg, Theme-Verhalten anzupassen, ist das Überschreiben von Dateien mithilfe der leistungsfähigen Hugo [Datei-Suchreihenfolge](https://gohugo.io/templates/lookup-order/). Zusammenfassend stellt die Suchreihenfolge sicher, dass alle Dateien, die Sie in Ihr Projektverzeichnis einbinden, automatisch Vorrang vor Theme-Dateien haben.
|
||||
|
||||
Wenn Sie beispielsweise das Hauptartikel-Template in Blowfish überschreiben möchten, können Sie einfach Ihre eigene `layouts/_default/single.html`-Datei erstellen und sie im Root Ihres Projekts platzieren. Diese Datei überschreibt dann die `single.html` aus dem Theme, ohne das Theme selbst zu ändern. Dies funktioniert für alle Theme-Dateien - HTML-Templates, Partials, Shortcodes, Konfigurationsdateien, Daten, Assets, etc.
|
||||
|
||||
Solange Sie diese einfache Praxis befolgen, können Sie das Theme immer aktualisieren (oder verschiedene Theme-Versionen testen), ohne sich Sorgen machen zu müssen, dass Sie Ihre benutzerdefinierten Änderungen verlieren.
|
||||
|
||||
## Bildoptimierungseinstellungen ändern
|
||||
|
||||
Hugo verfügt über verschiedene integrierte Methoden zum Ändern der Größe, Zuschneiden und Optimieren von Bildern.
|
||||
|
||||
Als Beispiel - in `layouts/partials/article-link/card.html` haben Sie folgenden Code:
|
||||
|
||||
```go
|
||||
{{ with .Resize "600x" }}
|
||||
<div class="w-full thumbnail_card nozoom" style="background-image:url({{ .RelPermalink }});"></div>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Das Standardverhalten von Hugo hier ist, die Bildgröße auf 600px unter Beibehaltung des Seitenverhältnisses zu ändern.
|
||||
|
||||
Es ist erwähnenswert, dass Standard-Bildkonfigurationen wie der [Ankerpunkt](https://gohugo.io/content-management/image-processing/#anchor) auch in Ihrer [Site-Konfiguration](https://gohugo.io/content-management/image-processing/#processing-options) sowie im Template selbst festgelegt werden können.
|
||||
|
||||
Weitere Informationen finden Sie in den [Hugo-Dokumenten zur Bildverarbeitung](https://gohugo.io/content-management/image-processing/#image-processing-methods).
|
||||
|
||||
## Farbschemata
|
||||
|
||||
Blowfish wird mit einer Reihe von Farbschemata ausgeliefert. Um das grundlegende Farbschema zu ändern, können Sie den Theme-Parameter `colorScheme` festlegen. Lesen Sie den Abschnitt [Erste Schritte]({{< ref "getting-started#colour-schemes" >}}), um mehr über die integrierten Schemata zu erfahren.
|
||||
|
||||
Zusätzlich zu den Standardschemata können Sie auch eigene erstellen und die gesamte Website nach Ihren Wünschen gestalten. Schemata werden erstellt, indem Sie eine `<schema-name>.css`-Datei im Ordner `assets/css/schemes/` platzieren. Sobald die Datei erstellt ist, verweisen Sie einfach in der Theme-Konfiguration mit dem Namen darauf.
|
||||
|
||||
{{< alert "github">}}
|
||||
**Hinweis:** Die manuelle Generierung dieser Dateien kann schwierig sein. Ich habe ein `nodejs`-Terminal-Tool entwickelt, um dabei zu helfen: [Fugu](https://github.com/nunocoracao/fugu). Im Wesentlichen übergeben Sie die drei Haupt-`hex`-Werte Ihrer Farbpalette und das Programm gibt eine CSS-Datei aus, die direkt in Blowfish importiert werden kann.
|
||||
{{< /alert >}}
|
||||
|
||||
|
||||
Blowfish definiert eine Drei-Farben-Palette, die im gesamten Theme verwendet wird. Die drei Farben sind als `neutral`, `primary` und `secondary` Varianten definiert, jeweils mit zehn Farbstufen.
|
||||
|
||||
Aufgrund der Art und Weise, wie Tailwind CSS 3.0 Farbwerte mit Deckkraft berechnet, müssen die im Schema angegebenen Farben einem [bestimmten Format entsprechen](https://github.com/adamwathan/tailwind-css-variable-text-opacity-demo), indem sie die Rot-, Grün- und Blau-Farbwerte angeben.
|
||||
|
||||
```css
|
||||
:root {
|
||||
--color-primary-500: 139, 92, 246;
|
||||
}
|
||||
```
|
||||
|
||||
Dieses Beispiel definiert eine CSS-Variable für die `primary-500`-Farbe mit einem Rotwert von `139`, Grünwert von `92` und Blauwert von `246`.
|
||||
|
||||
Verwenden Sie eines der vorhandenen Theme-Stylesheets als Vorlage. Sie können Ihre eigenen Farben definieren, aber zur Inspiration schauen Sie sich die offizielle [Tailwind-Farbpaletten-Referenz](https://tailwindcss.com/docs/customizing-colors#color-palette-reference) an.
|
||||
|
||||
## Das Stylesheet überschreiben
|
||||
|
||||
Manchmal müssen Sie einen benutzerdefinierten Stil hinzufügen, um Ihre eigenen HTML-Elemente zu gestalten. Blowfish bietet diese Möglichkeit, indem Sie die Standardstile in Ihrem eigenen CSS-Stylesheet überschreiben können. Erstellen Sie einfach eine `custom.css`-Datei im Ordner `assets/css/` Ihres Projekts.
|
||||
|
||||
Die `custom.css`-Datei wird von Hugo minimiert und automatisch nach allen anderen Theme-Stilen geladen, was bedeutet, dass alles in Ihrer benutzerdefinierten Datei Vorrang vor den Standardeinstellungen hat.
|
||||
|
||||
### Zusätzliche Schriftarten verwenden
|
||||
|
||||
Blowfish ermöglicht es Ihnen, die Schriftart für Ihre Website einfach zu ändern. Nachdem Sie eine `custom.css`-Datei im Ordner `assets/css/` Ihres Projekts erstellt haben, platzieren Sie Ihre Schriftdatei in einem `fonts`-Ordner innerhalb des `static`-Root-Ordners.
|
||||
|
||||
```shell
|
||||
.
|
||||
├── assets
|
||||
│ └── css
|
||||
│ └── custom.css
|
||||
...
|
||||
└─── static
|
||||
└── fonts
|
||||
└─── font.ttf
|
||||
|
||||
```
|
||||
|
||||
Dies macht die Schriftart für die Website verfügbar. Jetzt kann die Schriftart einfach in Ihrer `custom.css` importiert und ersetzt werden, wo immer Sie es für richtig halten. Das folgende Beispiel zeigt, wie das Ersetzen der Schriftart für das gesamte `html` aussehen würde.
|
||||
|
||||
```css
|
||||
@font-face {
|
||||
font-family: font;
|
||||
src: url('/fonts/font.ttf');
|
||||
}
|
||||
|
||||
html {
|
||||
font-family: font;
|
||||
}
|
||||
```
|
||||
|
||||
### Schriftgröße anpassen
|
||||
|
||||
Das Ändern der Schriftgröße Ihrer Website ist ein Beispiel für das Überschreiben des Standard-Stylesheets. Blowfish macht dies einfach, da es im gesamten Theme skalierte Schriftgrößen verwendet, die von der Basis-HTML-Schriftgröße abgeleitet werden. Standardmäßig setzt Tailwind die Standardgröße auf `12pt`, aber sie kann auf jeden beliebigen Wert geändert werden.
|
||||
|
||||
Erstellen Sie eine `custom.css`-Datei gemäß den [obigen Anweisungen]({{< ref "#overriding-the-stylesheet" >}}) und fügen Sie die folgende CSS-Deklaration hinzu:
|
||||
|
||||
```css
|
||||
/* Standardschriftgröße erhöhen */
|
||||
html {
|
||||
font-size: 13pt;
|
||||
}
|
||||
```
|
||||
|
||||
Allein durch das Ändern dieses einen Wertes werden alle Schriftgrößen auf Ihrer Website an diese neue Größe angepasst. Um also die insgesamt verwendeten Schriftgrößen zu erhöhen, machen Sie den Wert größer als `12pt`. Um die Schriftgrößen zu verringern, machen Sie den Wert kleiner als `12pt`.
|
||||
|
||||
### Syntax-Highlighting-Theme ändern
|
||||
|
||||
Um das Syntax-Highlighting-Theme zu ändern, erstellen Sie `assets/css/custom.css` und fügen Sie Folgendes hinzu:
|
||||
|
||||
```css
|
||||
.chroma,
|
||||
.chroma *,
|
||||
.chroma:is(.dark *),
|
||||
.chroma:is(.dark *) * {
|
||||
color: unset;
|
||||
font-weight: unset;
|
||||
font-style: unset;
|
||||
}
|
||||
```
|
||||
|
||||
Dies löscht die Standard-Chroma-Stile. Der nächste Schritt ist, Chroma-Stile in Ihre CSS-Datei mit dem Befehl `hugo gen chromastyles` einzubinden:
|
||||
|
||||
```sh
|
||||
# Mac/Linux
|
||||
(echo 'html:not(.dark) {'; hugo gen chromastyles --style=emacs; echo '}') >> assets/css/custom.css
|
||||
(echo 'html.dark {'; hugo gen chromastyles --style=evergarden; echo '}') >> assets/css/custom.css
|
||||
|
||||
# Windows PowerShell
|
||||
# Dieser Befehl kann nicht in CMD ausgeführt werden; er muss in PowerShell ausgeführt werden
|
||||
@("html:not(.dark) {"; (hugo gen chromastyles --style=emacs); "}") | Add-Content -Path "assets/css/custom.css"
|
||||
@("html.dark {"; (hugo gen chromastyles --style=evergarden); "}") | Add-Content -Path "assets/css/custom.css"
|
||||
```
|
||||
|
||||
Alle verfügbaren Stile finden Sie in [Hugos Dokumentation](https://gohugo.io/quick-reference/syntax-highlighting-styles/#styles).
|
||||
|
||||
## Das Theme-CSS aus dem Quellcode erstellen
|
||||
|
||||
Wenn Sie eine größere Änderung vornehmen möchten, können Sie den Tailwind CSS JIT-Compiler nutzen und das gesamte Theme-CSS von Grund auf neu erstellen. Dies ist nützlich, wenn Sie die Tailwind-Konfiguration anpassen oder zusätzliche Tailwind-Klassen zum Haupt-Stylesheet hinzufügen möchten.
|
||||
|
||||
{{< alert >}}
|
||||
**Hinweis:** Das manuelle Erstellen des Themes ist für fortgeschrittene Benutzer gedacht.
|
||||
{{< /alert >}}
|
||||
|
||||
Lassen Sie uns durchgehen, wie das Erstellen des Tailwind CSS funktioniert.
|
||||
|
||||
### Tailwind-Konfiguration
|
||||
|
||||
Um eine CSS-Datei zu generieren, die nur die Tailwind-Klassen enthält, die tatsächlich verwendet werden, muss der JIT-Compiler alle HTML-Templates und Markdown-Inhaltsdateien scannen, um zu überprüfen, welche Stile im Markup vorhanden sind. Der Compiler macht dies, indem er die Datei `tailwind.config.js` betrachtet, die im Root-Verzeichnis des Themes enthalten ist:
|
||||
|
||||
```js
|
||||
// themes/blowfish/tailwind.config.js
|
||||
|
||||
module.exports = {
|
||||
content: [
|
||||
"./layouts/**/*.html",
|
||||
"./content/**/*.{html,md}",
|
||||
"./themes/blowfish/layouts/**/*.html",
|
||||
"./themes/blowfish/content/**/*.{html,md}",
|
||||
],
|
||||
|
||||
// und mehr...
|
||||
};
|
||||
```
|
||||
|
||||
Diese Standardkonfiguration enthält diese Inhaltspfade, damit Sie Ihre eigene CSS-Datei einfach generieren können, ohne sie ändern zu müssen, vorausgesetzt Sie folgen einer bestimmten Projektstruktur. Nämlich **müssen Sie Blowfish in Ihrem Projekt als Unterverzeichnis unter `themes/blowfish/` einbinden**. Dies bedeutet, dass Sie das Theme nicht einfach mit Hugo-Modulen installieren können und Sie müssen entweder den Git-Submodule-Weg (empfohlen) oder den manuellen Installationsweg gehen. Die [Installationsdokumentation]({{< ref "installation" >}}) erklärt, wie Sie das Theme mit einer dieser Methoden installieren.
|
||||
|
||||
### Projektstruktur
|
||||
|
||||
Um die Standardkonfiguration zu nutzen, sollte Ihr Projekt etwa so aussehen...
|
||||
|
||||
```shell
|
||||
.
|
||||
├── assets
|
||||
│ └── css
|
||||
│ └── compiled
|
||||
│ └── main.css # dies ist die Datei, die wir generieren werden
|
||||
├── config # Site-Konfiguration
|
||||
│ └── _default
|
||||
├── content # Site-Inhalt
|
||||
│ ├── _index.md
|
||||
│ ├── projects
|
||||
│ │ └── _index.md
|
||||
│ └── blog
|
||||
│ └── _index.md
|
||||
├── layouts # benutzerdefinierte Layouts für Ihre Site
|
||||
│ ├── partials
|
||||
│ │ └── extend-article-link/simple.html
|
||||
│ ├── projects
|
||||
│ │ └── list.html
|
||||
│ └── shortcodes
|
||||
│ └── disclaimer.html
|
||||
└── themes
|
||||
└── blowfish # Git-Submodul oder manuelle Theme-Installation
|
||||
```
|
||||
|
||||
Diese Beispielstruktur fügt einen neuen `projects`-Inhaltstyp mit eigenem benutzerdefinierten Layout zusammen mit einem benutzerdefinierten Shortcode und erweiterten Partial hinzu. Sofern das Projekt dieser Struktur folgt, muss nur die `main.css`-Datei neu kompiliert werden.
|
||||
|
||||
### Abhängigkeiten installieren
|
||||
|
||||
Damit dies funktioniert, müssen Sie in das Verzeichnis `themes/blowfish/` wechseln und die Projektabhängigkeiten installieren. Sie benötigen [npm](https://docs.npmjs.com/cli/v7/configuring-npm/install) auf Ihrem lokalen Rechner für diesen Schritt.
|
||||
|
||||
```shell
|
||||
cd themes/blowfish
|
||||
npm install
|
||||
```
|
||||
|
||||
### Tailwind-Compiler ausführen
|
||||
|
||||
Mit den installierten Abhängigkeiten bleibt nur noch, die [Tailwind CLI](https://tailwindcss.com/docs/installation/tailwind-cli) zu verwenden, um den JIT-Compiler aufzurufen. Navigieren Sie zurück zum Root Ihres Hugo-Projekts und geben Sie folgenden Befehl ein:
|
||||
|
||||
```shell
|
||||
cd ../..
|
||||
./themes/blowfish/node_modules/@tailwindcss/cli/dist/index.mjs -c ./themes/blowfish/tailwind.config.js -i ./themes/blowfish/assets/css/main.css -o ./assets/css/compiled/main.css --jit
|
||||
```
|
||||
|
||||
Es ist ein etwas unschöner Befehl aufgrund der beteiligten Pfade, aber im Wesentlichen rufen Sie die Tailwind CLI auf und übergeben ihr den Speicherort der Tailwind-Konfigurationsdatei (die wir oben betrachtet haben), wo die `main.css`-Datei des Themes zu finden ist und wohin Sie die kompilierte CSS-Datei platzieren möchten (sie geht in den Ordner `assets/css/compiled/` Ihres Hugo-Projekts).
|
||||
|
||||
Die Konfigurationsdatei scannt automatisch alle Inhalte und Layouts in Ihrem Projekt sowie alle im Theme und erstellt eine neue CSS-Datei, die alle für Ihre Website erforderlichen CSS enthält. Aufgrund der Art, wie Hugo die Dateihierarchie handhabt, überschreibt diese Datei in Ihrem Projekt nun automatisch die, die mit dem Theme geliefert wird.
|
||||
|
||||
Jedes Mal, wenn Sie Änderungen an Ihren Layouts vornehmen und neue Tailwind CSS-Stile benötigen, können Sie einfach den Befehl erneut ausführen und die neue CSS-Datei generieren. Sie können auch `-w` am Ende des Befehls hinzufügen, um den JIT-Compiler im Watch-Modus auszuführen.
|
||||
|
||||
### Ein Build-Skript erstellen
|
||||
|
||||
Um diese ganze Lösung abzurunden, können Sie diesen gesamten Prozess vereinfachen, indem Sie Aliase für diese Befehle hinzufügen, oder tun Sie, was ich tue, und fügen Sie eine `package.json` zum Root Ihres Projekts hinzu, die die notwendigen Skripte enthält...
|
||||
|
||||
```js
|
||||
// package.json
|
||||
|
||||
{
|
||||
"name": "my-website",
|
||||
"version": "1.0.0",
|
||||
"description": "",
|
||||
"scripts": {
|
||||
"server": "hugo server -b http://localhost -p 8000",
|
||||
"dev": "NODE_ENV=development ./themes/blowfish/node_modules/@tailwindcss/cli/dist/index.mjs -c ./themes/blowfish/tailwind.config.js -i ./themes/blowfish/assets/css/main.css -o ./assets/css/compiled/main.css --jit -w",
|
||||
"build": "NODE_ENV=production ./themes/blowfish/node_modules/@tailwindcss/cli/dist/index.mjs -c ./themes/blowfish/tailwind.config.js -i ./themes/blowfish/assets/css/main.css -o ./assets/css/compiled/main.css --jit"
|
||||
},
|
||||
// und mehr...
|
||||
}
|
||||
```
|
||||
|
||||
Wenn Sie nun am Design Ihrer Site arbeiten möchten, können Sie `npm run dev` aufrufen und der Compiler wird im Watch-Modus ausgeführt. Wenn Sie bereit zur Bereitstellung sind, führen Sie `npm run build` aus und Sie erhalten einen sauberen Tailwind CSS-Build.
|
||||
|
||||
🙋♀️ Wenn Sie Hilfe benötigen, können Sie gerne eine Frage in den [GitHub Discussions](https://github.com/nunocoracao/blowfish/discussions) stellen.
|
||||
265
exampleSite/content/docs/advanced-customisation/index.es.md
Normal file
265
exampleSite/content/docs/advanced-customisation/index.es.md
Normal file
@@ -0,0 +1,265 @@
|
||||
---
|
||||
title: "Personalización avanzada"
|
||||
weight: 13
|
||||
draft: false
|
||||
description: "Aprende cómo construir Blowfish manualmente."
|
||||
slug: "advanced-customisation"
|
||||
tags: ["avanzado", "css", "documentación"]
|
||||
series: ["Documentación"]
|
||||
series_order: 13
|
||||
---
|
||||
|
||||
Hay muchas formas de hacer cambios avanzados a Blowfish. Lee a continuación para aprender más sobre qué se puede personalizar y la mejor manera de lograr el resultado deseado.
|
||||
|
||||
Si necesitas más consejos, publica tus preguntas en [GitHub Discussions](https://github.com/nunocoracao/blowfish/discussions).
|
||||
|
||||
## Estructura del proyecto Hugo
|
||||
|
||||
Antes de empezar, primero una nota rápida sobre la [estructura del proyecto Hugo](https://gohugo.io/getting-started/directory-structure/) y las mejores prácticas para gestionar tu contenido y personalizaciones del tema.
|
||||
|
||||
{{< alert >}}
|
||||
**En resumen:** Nunca edites directamente los archivos del tema. Solo haz personalizaciones en los subdirectorios de tu proyecto Hugo, no en el directorio themes en sí.
|
||||
{{< /alert >}}
|
||||
|
||||
Blowfish está construido para aprovechar todas las prácticas estándar de Hugo. Está diseñado para permitir que todos los aspectos del tema se personalicen y anulen sin cambiar ninguno de los archivos del tema principal. Esto permite una experiencia de actualización sin problemas mientras te da control total sobre la apariencia y el comportamiento de tu sitio web.
|
||||
|
||||
Para lograr esto, nunca deberías ajustar manualmente ninguno de los archivos del tema directamente. Ya sea que instales usando módulos Hugo, como un submódulo git o incluyas manualmente el tema en tu directorio `themes/`, siempre debes dejar estos archivos intactos.
|
||||
|
||||
La forma correcta de ajustar cualquier comportamiento del tema es anulando archivos usando el poderoso [orden de búsqueda de archivos](https://gohugo.io/templates/lookup-order/) de Hugo. En resumen, el orden de búsqueda asegura que cualquier archivo que incluyas en el directorio de tu proyecto tendrá automáticamente prioridad sobre cualquier archivo del tema.
|
||||
|
||||
Por ejemplo, si quisieras anular el template principal de artículo en Blowfish, simplemente puedes crear tu propio archivo `layouts/_default/single.html` y colocarlo en la raíz de tu proyecto. Este archivo luego anulará el `single.html` del tema sin cambiar nunca el tema en sí. Esto funciona para cualquier archivo del tema - templates HTML, partials, shortcodes, archivos de configuración, datos, assets, etc.
|
||||
|
||||
Mientras sigas esta práctica simple, siempre podrás actualizar el tema (o probar diferentes versiones del tema) sin preocuparte de perder ninguna de tus modificaciones personalizadas.
|
||||
|
||||
## Cambiar configuraciones de optimización de imagen
|
||||
|
||||
Hugo tiene varios métodos incorporados para redimensionar, recortar y optimizar imágenes.
|
||||
|
||||
Como ejemplo - en `layouts/partials/article-link/card.html`, tienes el siguiente código:
|
||||
|
||||
```go
|
||||
{{ with .Resize "600x" }}
|
||||
<div class="w-full thumbnail_card nozoom" style="background-image:url({{ .RelPermalink }});"></div>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
El comportamiento predeterminado de Hugo aquí es redimensionar la imagen a 600px manteniendo la proporción.
|
||||
|
||||
Vale la pena notar que las configuraciones de imagen predeterminadas como el [punto de anclaje](https://gohugo.io/content-management/image-processing/#anchor) también se pueden establecer en tu [configuración del sitio](https://gohugo.io/content-management/image-processing/#processing-options) así como en el template mismo.
|
||||
|
||||
Consulta los [docs de Hugo sobre procesamiento de imágenes](https://gohugo.io/content-management/image-processing/#image-processing-methods) para más información.
|
||||
|
||||
## Esquemas de color
|
||||
|
||||
Blowfish viene con varios esquemas de color listos para usar. Para cambiar el esquema de color básico, puedes establecer el parámetro del tema `colorScheme`. Consulta la sección [Primeros pasos]({{< ref "getting-started#colour-schemes" >}}) para aprender más sobre los esquemas incorporados.
|
||||
|
||||
Además de los esquemas predeterminados, también puedes crear los tuyos propios y re-estilizar todo el sitio web a tu gusto. Los esquemas se crean colocando un archivo `<nombre-esquema>.css` en la carpeta `assets/css/schemes/`. Una vez creado el archivo, simplemente refiérete a él por su nombre en la configuración del tema.
|
||||
|
||||
{{< alert "github">}}
|
||||
**Nota:** generar estos archivos manualmente puede ser difícil, he construido una herramienta de terminal `nodejs` para ayudar con eso, [Fugu](https://github.com/nunocoracao/fugu). En resumen, pasas los tres valores `hex` principales de tu paleta de colores y el programa producirá un archivo css que puede ser importado directamente en Blowfish.
|
||||
{{< /alert >}}
|
||||
|
||||
|
||||
Blowfish define una paleta de tres colores que se usa en todo el tema. Los tres colores se definen como variantes `neutral`, `primary` y `secondary`, cada una conteniendo diez tonos de color.
|
||||
|
||||
Debido a la forma en que Tailwind CSS 3.0 calcula los valores de color con opacidad, los colores especificados en el esquema necesitan [conformarse a un formato particular](https://github.com/adamwathan/tailwind-css-variable-text-opacity-demo) proporcionando los valores de color rojo, verde y azul.
|
||||
|
||||
```css
|
||||
:root {
|
||||
--color-primary-500: 139, 92, 246;
|
||||
}
|
||||
```
|
||||
|
||||
Este ejemplo define una variable CSS para el color `primary-500` con un valor rojo de `139`, valor verde de `92` y valor azul de `246`.
|
||||
|
||||
Usa una de las hojas de estilo existentes del tema como plantilla. Eres libre de definir tus propios colores, pero para inspiración, consulta la [referencia de paleta de colores de Tailwind](https://tailwindcss.com/docs/customizing-colors#color-palette-reference) oficial.
|
||||
|
||||
## Anular la hoja de estilos
|
||||
|
||||
A veces necesitas añadir un estilo personalizado para estilizar tus propios elementos HTML. Blowfish provee para este escenario permitiéndote anular los estilos predeterminados en tu propia hoja de estilos CSS. Simplemente crea un archivo `custom.css` en la carpeta `assets/css/` de tu proyecto.
|
||||
|
||||
El archivo `custom.css` será minificado por Hugo y cargado automáticamente después de todos los otros estilos del tema lo que significa que cualquier cosa en tu archivo personalizado tendrá prioridad sobre los valores predeterminados.
|
||||
|
||||
### Usar fuentes adicionales
|
||||
|
||||
Blowfish te permite cambiar fácilmente la fuente de tu sitio. Después de crear un archivo `custom.css` en la carpeta `assets/css/` de tu proyecto, coloca tu archivo de fuente dentro de una carpeta `fonts` en la carpeta raíz `static`.
|
||||
|
||||
```shell
|
||||
.
|
||||
├── assets
|
||||
│ └── css
|
||||
│ └── custom.css
|
||||
...
|
||||
└─── static
|
||||
└── fonts
|
||||
└─── font.ttf
|
||||
|
||||
```
|
||||
|
||||
Esto hace que la fuente esté disponible para el sitio web. Ahora, la fuente simplemente puede ser importada en tu `custom.css` y reemplazada donde lo veas conveniente. El ejemplo de abajo muestra cómo se vería reemplazar la fuente para todo el `html`.
|
||||
|
||||
```css
|
||||
@font-face {
|
||||
font-family: font;
|
||||
src: url('/fonts/font.ttf');
|
||||
}
|
||||
|
||||
html {
|
||||
font-family: font;
|
||||
}
|
||||
```
|
||||
|
||||
### Ajustar el tamaño de fuente
|
||||
|
||||
Cambiar el tamaño de fuente de tu sitio web es un ejemplo de anular la hoja de estilos predeterminada. Blowfish hace esto simple ya que usa tamaños de fuente escalados en todo el tema que se derivan del tamaño de fuente HTML base. Por defecto, Tailwind establece el tamaño predeterminado en `12pt`, pero puede cambiarse a cualquier valor que prefieras.
|
||||
|
||||
Crea un archivo `custom.css` usando las [instrucciones de arriba]({{< ref "#overriding-the-stylesheet" >}}) y añade la siguiente declaración CSS:
|
||||
|
||||
```css
|
||||
/* Aumentar el tamaño de fuente predeterminado */
|
||||
html {
|
||||
font-size: 13pt;
|
||||
}
|
||||
```
|
||||
|
||||
Simplemente cambiando este único valor, todos los tamaños de fuente en tu sitio web se ajustarán para coincidir con este nuevo tamaño. Por lo tanto, para aumentar los tamaños de fuente generales usados, haz el valor mayor que `12pt`. De manera similar, para disminuir los tamaños de fuente, haz el valor menor que `12pt`.
|
||||
|
||||
### Cambiar el tema de resaltado de sintaxis
|
||||
|
||||
Para cambiar el tema de resaltado de sintaxis, crea `assets/css/custom.css` y añade lo siguiente:
|
||||
|
||||
```css
|
||||
.chroma,
|
||||
.chroma *,
|
||||
.chroma:is(.dark *),
|
||||
.chroma:is(.dark *) * {
|
||||
color: unset;
|
||||
font-weight: unset;
|
||||
font-style: unset;
|
||||
}
|
||||
```
|
||||
|
||||
Esto limpia los estilos predeterminados de Chroma. El siguiente paso es incorporar estilos de Chroma en tu archivo CSS usando el comando `hugo gen chromastyles`:
|
||||
|
||||
```sh
|
||||
# Mac/Linux
|
||||
(echo 'html:not(.dark) {'; hugo gen chromastyles --style=emacs; echo '}') >> assets/css/custom.css
|
||||
(echo 'html.dark {'; hugo gen chromastyles --style=evergarden; echo '}') >> assets/css/custom.css
|
||||
|
||||
# Windows PowerShell
|
||||
# Este comando no puede ejecutarse en CMD; debe ejecutarse en PowerShell
|
||||
@("html:not(.dark) {"; (hugo gen chromastyles --style=emacs); "}") | Add-Content -Path "assets/css/custom.css"
|
||||
@("html.dark {"; (hugo gen chromastyles --style=evergarden); "}") | Add-Content -Path "assets/css/custom.css"
|
||||
```
|
||||
|
||||
Consulta todos los estilos disponibles en la [documentación de Hugo](https://gohugo.io/quick-reference/syntax-highlighting-styles/#styles).
|
||||
|
||||
## Construir el CSS del tema desde la fuente
|
||||
|
||||
Si quisieras hacer un cambio mayor, puedes aprovechar el compilador JIT de Tailwind CSS y reconstruir todo el CSS del tema desde cero. Esto es útil si quieres ajustar la configuración de Tailwind o añadir clases extra de Tailwind a la hoja de estilos principal.
|
||||
|
||||
{{< alert >}}
|
||||
**Nota:** Construir el tema manualmente está pensado para usuarios avanzados.
|
||||
{{< /alert >}}
|
||||
|
||||
Repasemos cómo funciona la construcción del Tailwind CSS.
|
||||
|
||||
### Configuración de Tailwind
|
||||
|
||||
Para generar un archivo CSS que solo contenga las clases de Tailwind que realmente se están usando, el compilador JIT necesita escanear todos los templates HTML y archivos de contenido Markdown para verificar qué estilos están presentes en el markup. El compilador hace esto mirando el archivo `tailwind.config.js` que está incluido en la raíz del directorio del tema:
|
||||
|
||||
```js
|
||||
// themes/blowfish/tailwind.config.js
|
||||
|
||||
module.exports = {
|
||||
content: [
|
||||
"./layouts/**/*.html",
|
||||
"./content/**/*.{html,md}",
|
||||
"./themes/blowfish/layouts/**/*.html",
|
||||
"./themes/blowfish/content/**/*.{html,md}",
|
||||
],
|
||||
|
||||
// y más...
|
||||
};
|
||||
```
|
||||
|
||||
Esta configuración predeterminada ha sido incluida con estas rutas de contenido para que puedas generar fácilmente tu propio archivo CSS sin necesidad de modificarla, siempre que sigas una estructura de proyecto particular. Es decir, **tienes que incluir Blowfish en tu proyecto como un subdirectorio en `themes/blowfish/`**. Esto significa que no puedes usar fácilmente los módulos Hugo para instalar el tema y debes optar por la instalación por submódulo git (recomendado) o la instalación manual. Los [docs de instalación]({{< ref "installation" >}}) explican cómo instalar el tema usando cualquiera de estos métodos.
|
||||
|
||||
### Estructura del proyecto
|
||||
|
||||
Para aprovechar la configuración predeterminada, tu proyecto debería verse algo así...
|
||||
|
||||
```shell
|
||||
.
|
||||
├── assets
|
||||
│ └── css
|
||||
│ └── compiled
|
||||
│ └── main.css # este es el archivo que generaremos
|
||||
├── config # config del sitio
|
||||
│ └── _default
|
||||
├── content # contenido del sitio
|
||||
│ ├── _index.md
|
||||
│ ├── projects
|
||||
│ │ └── _index.md
|
||||
│ └── blog
|
||||
│ └── _index.md
|
||||
├── layouts # layouts personalizados para tu sitio
|
||||
│ ├── partials
|
||||
│ │ └── extend-article-link/simple.html
|
||||
│ ├── projects
|
||||
│ │ └── list.html
|
||||
│ └── shortcodes
|
||||
│ └── disclaimer.html
|
||||
└── themes
|
||||
└── blowfish # submódulo git o instalación manual del tema
|
||||
```
|
||||
|
||||
Esta estructura de ejemplo añade un nuevo tipo de contenido `projects` con su propio layout personalizado junto con un shortcode personalizado y partial extendido. Siempre que el proyecto siga esta estructura, todo lo que se requiere es recompilar el archivo `main.css`.
|
||||
|
||||
### Instalar dependencias
|
||||
|
||||
Para que esto funcione necesitarás cambiar al directorio `themes/blowfish/` e instalar las dependencias del proyecto. Necesitarás [npm](https://docs.npmjs.com/cli/v7/configuring-npm/install) en tu máquina local para este paso.
|
||||
|
||||
```shell
|
||||
cd themes/blowfish
|
||||
npm install
|
||||
```
|
||||
|
||||
### Ejecutar el compilador de Tailwind
|
||||
|
||||
Con las dependencias instaladas, todo lo que queda es usar [Tailwind CLI](https://tailwindcss.com/docs/installation/tailwind-cli) para invocar el compilador JIT. Navega de vuelta a la raíz de tu proyecto Hugo y ejecuta el siguiente comando:
|
||||
|
||||
```shell
|
||||
cd ../..
|
||||
./themes/blowfish/node_modules/@tailwindcss/cli/dist/index.mjs -c ./themes/blowfish/tailwind.config.js -i ./themes/blowfish/assets/css/main.css -o ./assets/css/compiled/main.css --jit
|
||||
```
|
||||
|
||||
Es un comando un poco feo debido a las rutas involucradas pero esencialmente estás llamando a Tailwind CLI y pasándole la ubicación del archivo de config de Tailwind (el que vimos arriba), dónde encontrar el archivo `main.css` del tema y luego dónde quieres que se coloque el archivo CSS compilado (va a la carpeta `assets/css/compiled/` de tu proyecto Hugo).
|
||||
|
||||
El archivo de config escaneará automáticamente todo el contenido y layouts en tu proyecto así como todos los del tema y construirá un nuevo archivo CSS que contiene todo el CSS requerido para tu sitio web. Debido a la forma en que Hugo maneja la jerarquía de archivos, este archivo en tu proyecto ahora anulará automáticamente el que viene con el tema.
|
||||
|
||||
Cada vez que hagas un cambio en tus layouts y necesites nuevos estilos de Tailwind CSS, simplemente puedes volver a ejecutar el comando y generar el nuevo archivo CSS. También puedes añadir `-w` al final del comando para ejecutar el compilador JIT en modo watch.
|
||||
|
||||
### Crear un script de build
|
||||
|
||||
Para completar completamente esta solución, puedes simplificar todo este proceso añadiendo alias para estos comandos, o hacer lo que yo hago y añadir un `package.json` a la raíz de tu proyecto que contenga los scripts necesarios...
|
||||
|
||||
```js
|
||||
// package.json
|
||||
|
||||
{
|
||||
"name": "my-website",
|
||||
"version": "1.0.0",
|
||||
"description": "",
|
||||
"scripts": {
|
||||
"server": "hugo server -b http://localhost -p 8000",
|
||||
"dev": "NODE_ENV=development ./themes/blowfish/node_modules/@tailwindcss/cli/dist/index.mjs -c ./themes/blowfish/tailwind.config.js -i ./themes/blowfish/assets/css/main.css -o ./assets/css/compiled/main.css --jit -w",
|
||||
"build": "NODE_ENV=production ./themes/blowfish/node_modules/@tailwindcss/cli/dist/index.mjs -c ./themes/blowfish/tailwind.config.js -i ./themes/blowfish/assets/css/main.css -o ./assets/css/compiled/main.css --jit"
|
||||
},
|
||||
// y más...
|
||||
}
|
||||
```
|
||||
|
||||
Ahora cuando quieras trabajar en el diseño de tu sitio, puedes invocar `npm run dev` y el compilador se ejecutará en modo watch. Cuando estés listo para desplegar, ejecuta `npm run build` y tendrás un build limpio de Tailwind CSS.
|
||||
|
||||
🙋♀️ Si necesitas ayuda, siéntete libre de hacer una pregunta en [GitHub Discussions](https://github.com/nunocoracao/blowfish/discussions).
|
||||
265
exampleSite/content/docs/advanced-customisation/index.fr.md
Normal file
265
exampleSite/content/docs/advanced-customisation/index.fr.md
Normal file
@@ -0,0 +1,265 @@
|
||||
---
|
||||
title: "Personnalisation avancée"
|
||||
weight: 13
|
||||
draft: false
|
||||
description: "Apprenez à construire Blowfish manuellement."
|
||||
slug: "advanced-customisation"
|
||||
tags: ["avancé", "css", "documentation"]
|
||||
series: ["Documentation"]
|
||||
series_order: 13
|
||||
---
|
||||
|
||||
Il existe de nombreuses façons d'apporter des modifications avancées à Blowfish. Lisez ci-dessous pour en savoir plus sur ce qui peut être personnalisé et la meilleure façon d'atteindre le résultat souhaité.
|
||||
|
||||
Si vous avez besoin de conseils supplémentaires, posez vos questions sur [GitHub Discussions](https://github.com/nunocoracao/blowfish/discussions).
|
||||
|
||||
## Structure du projet Hugo
|
||||
|
||||
Avant de se lancer, d'abord un petit mot sur la [structure du projet Hugo](https://gohugo.io/getting-started/directory-structure/) et les meilleures pratiques pour gérer votre contenu et les personnalisations de thème.
|
||||
|
||||
{{< alert >}}
|
||||
**En résumé :** Ne modifiez jamais directement les fichiers du thème. Faites uniquement des personnalisations dans les sous-répertoires de votre projet Hugo, pas dans le répertoire themes lui-même.
|
||||
{{< /alert >}}
|
||||
|
||||
Blowfish est construit pour tirer parti de toutes les pratiques standard de Hugo. Il est conçu pour permettre la personnalisation et le remplacement de tous les aspects du thème sans modifier aucun des fichiers du thème de base. Cela permet une expérience de mise à niveau transparente tout en vous donnant un contrôle total sur l'apparence et le comportement de votre site web.
|
||||
|
||||
Pour y parvenir, vous ne devriez jamais ajuster manuellement les fichiers du thème directement. Que vous installiez en utilisant les modules Hugo, comme un sous-module git ou que vous incluiez manuellement le thème dans votre répertoire `themes/`, vous devriez toujours laisser ces fichiers intacts.
|
||||
|
||||
La bonne façon d'ajuster le comportement du thème est de remplacer les fichiers en utilisant le puissant [ordre de recherche de fichiers](https://gohugo.io/templates/lookup-order/) de Hugo. En résumé, l'ordre de recherche garantit que tous les fichiers que vous incluez dans votre répertoire de projet auront automatiquement priorité sur les fichiers du thème.
|
||||
|
||||
Par exemple, si vous vouliez remplacer le template d'article principal dans Blowfish, vous pouvez simplement créer votre propre fichier `layouts/_default/single.html` et le placer à la racine de votre projet. Ce fichier remplacera alors le `single.html` du thème sans jamais modifier le thème lui-même. Cela fonctionne pour tous les fichiers du thème - templates HTML, partials, shortcodes, fichiers de configuration, données, assets, etc.
|
||||
|
||||
Tant que vous suivez cette pratique simple, vous pourrez toujours mettre à jour le thème (ou tester différentes versions du thème) sans vous soucier de perdre vos modifications personnalisées.
|
||||
|
||||
## Modifier les paramètres d'optimisation d'image
|
||||
|
||||
Hugo dispose de diverses méthodes intégrées pour redimensionner, recadrer et optimiser les images.
|
||||
|
||||
À titre d'exemple - dans `layouts/partials/article-link/card.html`, vous avez le code suivant :
|
||||
|
||||
```go
|
||||
{{ with .Resize "600x" }}
|
||||
<div class="w-full thumbnail_card nozoom" style="background-image:url({{ .RelPermalink }});"></div>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
Le comportement par défaut de Hugo ici est de redimensionner l'image à 600px en conservant le ratio.
|
||||
|
||||
Il est à noter que les configurations d'image par défaut telles que le [point d'ancrage](https://gohugo.io/content-management/image-processing/#anchor) peuvent également être définies dans votre [configuration de site](https://gohugo.io/content-management/image-processing/#processing-options) ainsi que dans le template lui-même.
|
||||
|
||||
Voir les [docs Hugo sur le traitement d'image](https://gohugo.io/content-management/image-processing/#image-processing-methods) pour plus d'infos.
|
||||
|
||||
## Schémas de couleurs
|
||||
|
||||
Blowfish est livré avec plusieurs schémas de couleurs prêts à l'emploi. Pour changer le schéma de couleurs de base, vous pouvez définir le paramètre de thème `colorScheme`. Référez-vous à la section [Premiers pas]({{< ref "getting-started#colour-schemes" >}}) pour en savoir plus sur les schémas intégrés.
|
||||
|
||||
En plus des schémas par défaut, vous pouvez également créer les vôtres et restyler l'ensemble du site web selon vos goûts. Les schémas sont créés en plaçant un fichier `<nom-du-schema>.css` dans le dossier `assets/css/schemes/`. Une fois le fichier créé, référencez-le simplement par son nom dans la configuration du thème.
|
||||
|
||||
{{< alert "github">}}
|
||||
**Note :** générer ces fichiers manuellement peut être difficile, j'ai créé un outil terminal `nodejs` pour aider avec cela, [Fugu](https://github.com/nunocoracao/fugu). En bref, vous passez les trois principales valeurs `hex` de votre palette de couleurs et le programme produira un fichier css qui peut être importé directement dans Blowfish.
|
||||
{{< /alert >}}
|
||||
|
||||
|
||||
Blowfish définit une palette de trois couleurs qui est utilisée tout au long du thème. Les trois couleurs sont définies comme variantes `neutral`, `primary` et `secondary`, chacune contenant dix nuances de couleur.
|
||||
|
||||
En raison de la façon dont Tailwind CSS 3.0 calcule les valeurs de couleur avec l'opacité, les couleurs spécifiées dans le schéma doivent [se conformer à un format particulier](https://github.com/adamwathan/tailwind-css-variable-text-opacity-demo) en fournissant les valeurs de couleur rouge, vert et bleu.
|
||||
|
||||
```css
|
||||
:root {
|
||||
--color-primary-500: 139, 92, 246;
|
||||
}
|
||||
```
|
||||
|
||||
Cet exemple définit une variable CSS pour la couleur `primary-500` avec une valeur rouge de `139`, une valeur verte de `92` et une valeur bleue de `246`.
|
||||
|
||||
Utilisez l'une des feuilles de style du thème existantes comme modèle. Vous êtes libre de définir vos propres couleurs, mais pour l'inspiration, consultez la [référence de palette de couleurs Tailwind](https://tailwindcss.com/docs/customizing-colors#color-palette-reference) officielle.
|
||||
|
||||
## Remplacer la feuille de style
|
||||
|
||||
Parfois vous devez ajouter un style personnalisé pour styliser vos propres éléments HTML. Blowfish prévoit ce scénario en vous permettant de remplacer les styles par défaut dans votre propre feuille de style CSS. Créez simplement un fichier `custom.css` dans le dossier `assets/css/` de votre projet.
|
||||
|
||||
Le fichier `custom.css` sera minifié par Hugo et chargé automatiquement après tous les autres styles du thème, ce qui signifie que tout dans votre fichier personnalisé aura priorité sur les valeurs par défaut.
|
||||
|
||||
### Utiliser des polices supplémentaires
|
||||
|
||||
Blowfish vous permet de changer facilement la police de votre site. Après avoir créé un fichier `custom.css` dans le dossier `assets/css/` de votre projet, placez votre fichier de police dans un dossier `fonts` dans le dossier racine `static`.
|
||||
|
||||
```shell
|
||||
.
|
||||
├── assets
|
||||
│ └── css
|
||||
│ └── custom.css
|
||||
...
|
||||
└─── static
|
||||
└── fonts
|
||||
└─── font.ttf
|
||||
|
||||
```
|
||||
|
||||
Cela rend la police disponible pour le site web. Maintenant, la police peut simplement être importée dans votre `custom.css` et remplacée où vous le jugez bon. L'exemple ci-dessous montre à quoi ressemblerait le remplacement de la police pour tout le `html`.
|
||||
|
||||
```css
|
||||
@font-face {
|
||||
font-family: font;
|
||||
src: url('/fonts/font.ttf');
|
||||
}
|
||||
|
||||
html {
|
||||
font-family: font;
|
||||
}
|
||||
```
|
||||
|
||||
### Ajuster la taille de police
|
||||
|
||||
Changer la taille de police de votre site web est un exemple de remplacement de la feuille de style par défaut. Blowfish rend cela simple car il utilise des tailles de police mises à l'échelle tout au long du thème qui sont dérivées de la taille de police HTML de base. Par défaut, Tailwind définit la taille par défaut à `12pt`, mais elle peut être changée selon votre préférence.
|
||||
|
||||
Créez un fichier `custom.css` en utilisant les [instructions ci-dessus]({{< ref "#overriding-the-stylesheet" >}}) et ajoutez la déclaration CSS suivante :
|
||||
|
||||
```css
|
||||
/* Augmenter la taille de police par défaut */
|
||||
html {
|
||||
font-size: 13pt;
|
||||
}
|
||||
```
|
||||
|
||||
Simplement en changeant cette seule valeur, toutes les tailles de police sur votre site web seront ajustées pour correspondre à cette nouvelle taille. Par conséquent, pour augmenter les tailles de police globales utilisées, faites la valeur plus grande que `12pt`. De même, pour diminuer les tailles de police, faites la valeur plus petite que `12pt`.
|
||||
|
||||
### Changer le thème de coloration syntaxique
|
||||
|
||||
Pour changer le thème de coloration syntaxique, créez `assets/css/custom.css` et ajoutez ce qui suit :
|
||||
|
||||
```css
|
||||
.chroma,
|
||||
.chroma *,
|
||||
.chroma:is(.dark *),
|
||||
.chroma:is(.dark *) * {
|
||||
color: unset;
|
||||
font-weight: unset;
|
||||
font-style: unset;
|
||||
}
|
||||
```
|
||||
|
||||
Cela efface les styles Chroma par défaut. L'étape suivante est d'incorporer les styles Chroma dans votre fichier CSS en utilisant la commande `hugo gen chromastyles` :
|
||||
|
||||
```sh
|
||||
# Mac/Linux
|
||||
(echo 'html:not(.dark) {'; hugo gen chromastyles --style=emacs; echo '}') >> assets/css/custom.css
|
||||
(echo 'html.dark {'; hugo gen chromastyles --style=evergarden; echo '}') >> assets/css/custom.css
|
||||
|
||||
# Windows PowerShell
|
||||
# Cette commande ne peut pas s'exécuter dans CMD ; elle doit s'exécuter dans PowerShell
|
||||
@("html:not(.dark) {"; (hugo gen chromastyles --style=emacs); "}") | Add-Content -Path "assets/css/custom.css"
|
||||
@("html.dark {"; (hugo gen chromastyles --style=evergarden); "}") | Add-Content -Path "assets/css/custom.css"
|
||||
```
|
||||
|
||||
Voir tous les styles disponibles dans la [documentation de Hugo](https://gohugo.io/quick-reference/syntax-highlighting-styles/#styles).
|
||||
|
||||
## Construire le CSS du thème depuis la source
|
||||
|
||||
Si vous souhaitez faire une modification majeure, vous pouvez tirer parti du compilateur JIT de Tailwind CSS et reconstruire tout le CSS du thème à partir de zéro. C'est utile si vous voulez ajuster la configuration Tailwind ou ajouter des classes Tailwind supplémentaires à la feuille de style principale.
|
||||
|
||||
{{< alert >}}
|
||||
**Note :** Construire le thème manuellement est destiné aux utilisateurs avancés.
|
||||
{{< /alert >}}
|
||||
|
||||
Voyons comment fonctionne la construction du Tailwind CSS.
|
||||
|
||||
### Configuration Tailwind
|
||||
|
||||
Pour générer un fichier CSS qui contient uniquement les classes Tailwind qui sont réellement utilisées, le compilateur JIT doit scanner tous les templates HTML et fichiers de contenu Markdown pour vérifier quels styles sont présents dans le markup. Le compilateur fait cela en regardant le fichier `tailwind.config.js` qui est inclus à la racine du répertoire du thème :
|
||||
|
||||
```js
|
||||
// themes/blowfish/tailwind.config.js
|
||||
|
||||
module.exports = {
|
||||
content: [
|
||||
"./layouts/**/*.html",
|
||||
"./content/**/*.{html,md}",
|
||||
"./themes/blowfish/layouts/**/*.html",
|
||||
"./themes/blowfish/content/**/*.{html,md}",
|
||||
],
|
||||
|
||||
// et plus...
|
||||
};
|
||||
```
|
||||
|
||||
Cette configuration par défaut a été incluse avec ces chemins de contenu afin que vous puissiez facilement générer votre propre fichier CSS sans avoir besoin de la modifier, à condition de suivre une structure de projet particulière. À savoir, **vous devez inclure Blowfish dans votre projet comme un sous-répertoire à `themes/blowfish/`**. Cela signifie que vous ne pouvez pas facilement utiliser les modules Hugo pour installer le thème et vous devez opter pour l'installation par sous-module git (recommandé) ou l'installation manuelle. Les [docs d'installation]({{< ref "installation" >}}) expliquent comment installer le thème en utilisant l'une de ces méthodes.
|
||||
|
||||
### Structure du projet
|
||||
|
||||
Pour tirer parti de la configuration par défaut, votre projet devrait ressembler à quelque chose comme ceci...
|
||||
|
||||
```shell
|
||||
.
|
||||
├── assets
|
||||
│ └── css
|
||||
│ └── compiled
|
||||
│ └── main.css # c'est le fichier que nous allons générer
|
||||
├── config # config du site
|
||||
│ └── _default
|
||||
├── content # contenu du site
|
||||
│ ├── _index.md
|
||||
│ ├── projects
|
||||
│ │ └── _index.md
|
||||
│ └── blog
|
||||
│ └── _index.md
|
||||
├── layouts # layouts personnalisés pour votre site
|
||||
│ ├── partials
|
||||
│ │ └── extend-article-link/simple.html
|
||||
│ ├── projects
|
||||
│ │ └── list.html
|
||||
│ └── shortcodes
|
||||
│ └── disclaimer.html
|
||||
└── themes
|
||||
└── blowfish # sous-module git ou installation manuelle du thème
|
||||
```
|
||||
|
||||
Cette structure d'exemple ajoute un nouveau type de contenu `projects` avec son propre layout personnalisé ainsi qu'un shortcode personnalisé et un partial étendu. Pourvu que le projet suive cette structure, tout ce qui est requis est de recompiler le fichier `main.css`.
|
||||
|
||||
### Installer les dépendances
|
||||
|
||||
Pour que cela fonctionne, vous devrez vous déplacer dans le répertoire `themes/blowfish/` et installer les dépendances du projet. Vous aurez besoin de [npm](https://docs.npmjs.com/cli/v7/configuring-npm/install) sur votre machine locale pour cette étape.
|
||||
|
||||
```shell
|
||||
cd themes/blowfish
|
||||
npm install
|
||||
```
|
||||
|
||||
### Exécuter le compilateur Tailwind
|
||||
|
||||
Avec les dépendances installées, il ne reste plus qu'à utiliser [Tailwind CLI](https://tailwindcss.com/docs/installation/tailwind-cli) pour invoquer le compilateur JIT. Retournez à la racine de votre projet Hugo et lancez la commande suivante :
|
||||
|
||||
```shell
|
||||
cd ../..
|
||||
./themes/blowfish/node_modules/@tailwindcss/cli/dist/index.mjs -c ./themes/blowfish/tailwind.config.js -i ./themes/blowfish/assets/css/main.css -o ./assets/css/compiled/main.css --jit
|
||||
```
|
||||
|
||||
C'est une commande un peu laide à cause des chemins impliqués mais essentiellement vous appelez Tailwind CLI et lui passez l'emplacement du fichier de config Tailwind (celui que nous avons regardé ci-dessus), où trouver le fichier `main.css` du thème et ensuite où vous voulez que le fichier CSS compilé soit placé (il va dans le dossier `assets/css/compiled/` de votre projet Hugo).
|
||||
|
||||
Le fichier de config scannera automatiquement tout le contenu et les layouts de votre projet ainsi que tous ceux du thème et construira un nouveau fichier CSS qui contient tout le CSS requis pour votre site web. En raison de la façon dont Hugo gère la hiérarchie des fichiers, ce fichier dans votre projet remplacera maintenant automatiquement celui qui vient avec le thème.
|
||||
|
||||
Chaque fois que vous faites un changement dans vos layouts et avez besoin de nouveaux styles Tailwind CSS, vous pouvez simplement relancer la commande et générer le nouveau fichier CSS. Vous pouvez aussi ajouter `-w` à la fin de la commande pour exécuter le compilateur JIT en mode watch.
|
||||
|
||||
### Créer un script de build
|
||||
|
||||
Pour compléter entièrement cette solution, vous pouvez simplifier tout ce processus en ajoutant des alias pour ces commandes, ou faire ce que je fais et ajouter un `package.json` à la racine de votre projet qui contient les scripts nécessaires...
|
||||
|
||||
```js
|
||||
// package.json
|
||||
|
||||
{
|
||||
"name": "my-website",
|
||||
"version": "1.0.0",
|
||||
"description": "",
|
||||
"scripts": {
|
||||
"server": "hugo server -b http://localhost -p 8000",
|
||||
"dev": "NODE_ENV=development ./themes/blowfish/node_modules/@tailwindcss/cli/dist/index.mjs -c ./themes/blowfish/tailwind.config.js -i ./themes/blowfish/assets/css/main.css -o ./assets/css/compiled/main.css --jit -w",
|
||||
"build": "NODE_ENV=production ./themes/blowfish/node_modules/@tailwindcss/cli/dist/index.mjs -c ./themes/blowfish/tailwind.config.js -i ./themes/blowfish/assets/css/main.css -o ./assets/css/compiled/main.css --jit"
|
||||
},
|
||||
// et plus...
|
||||
}
|
||||
```
|
||||
|
||||
Maintenant quand vous voulez travailler sur le design de votre site, vous pouvez invoquer `npm run dev` et le compilateur s'exécutera en mode watch. Quand vous êtes prêt à déployer, lancez `npm run build` et vous aurez un build Tailwind CSS propre.
|
||||
|
||||
🙋♀️ Si vous avez besoin d'aide, n'hésitez pas à poser une question sur [GitHub Discussions](https://github.com/nunocoracao/blowfish/discussions).
|
||||
265
exampleSite/content/docs/advanced-customisation/index.pt-br.md
Normal file
265
exampleSite/content/docs/advanced-customisation/index.pt-br.md
Normal file
@@ -0,0 +1,265 @@
|
||||
---
|
||||
title: "Personalização avançada"
|
||||
weight: 13
|
||||
draft: false
|
||||
description: "Aprenda como construir o Blowfish manualmente."
|
||||
slug: "advanced-customisation"
|
||||
tags: ["avançado", "css", "documentação"]
|
||||
series: ["Documentação"]
|
||||
series_order: 13
|
||||
---
|
||||
|
||||
Existem muitas maneiras de fazer alterações avançadas no Blowfish. Leia abaixo para saber mais sobre o que pode ser personalizado e a melhor forma de alcançar o resultado desejado.
|
||||
|
||||
Se precisar de mais orientação, poste suas perguntas nas [GitHub Discussions](https://github.com/nunocoracao/blowfish/discussions).
|
||||
|
||||
## Estrutura do projeto Hugo
|
||||
|
||||
Antes de começar, primeiro uma nota rápida sobre a [estrutura do projeto Hugo](https://gohugo.io/getting-started/directory-structure/) e as melhores práticas para gerenciar seu conteúdo e personalizações do tema.
|
||||
|
||||
{{< alert >}}
|
||||
**Em resumo:** Nunca edite diretamente os arquivos do tema. Apenas faça personalizações nos subdiretórios do seu projeto Hugo, não no diretório themes em si.
|
||||
{{< /alert >}}
|
||||
|
||||
O Blowfish foi construído para aproveitar todas as práticas padrão do Hugo. Ele é projetado para permitir que todos os aspectos do tema sejam personalizados e substituídos sem alterar nenhum dos arquivos principais do tema. Isso permite uma experiência de atualização perfeita enquanto oferece controle total sobre a aparência e o funcionamento do seu site.
|
||||
|
||||
Para conseguir isso, você nunca deve ajustar manualmente nenhum dos arquivos do tema diretamente. Seja instalando usando módulos Hugo, como um submódulo git ou incluindo manualmente o tema no seu diretório `themes/`, você deve sempre deixar esses arquivos intactos.
|
||||
|
||||
A maneira correta de ajustar qualquer comportamento do tema é substituindo arquivos usando a poderosa [ordem de busca de arquivos](https://gohugo.io/templates/lookup-order/) do Hugo. Em resumo, a ordem de busca garante que quaisquer arquivos que você incluir no diretório do seu projeto terão automaticamente precedência sobre quaisquer arquivos do tema.
|
||||
|
||||
Por exemplo, se você quisesse substituir o template principal de artigo no Blowfish, você pode simplesmente criar seu próprio arquivo `layouts/_default/single.html` e colocá-lo na raiz do seu projeto. Este arquivo então substituirá o `single.html` do tema sem nunca alterar o tema em si. Isso funciona para qualquer arquivo do tema - templates HTML, partials, shortcodes, arquivos de configuração, dados, assets, etc.
|
||||
|
||||
Enquanto você seguir esta prática simples, você sempre poderá atualizar o tema (ou testar diferentes versões do tema) sem se preocupar em perder nenhuma de suas alterações personalizadas.
|
||||
|
||||
## Alterar configurações de otimização de imagem
|
||||
|
||||
Hugo tem vários métodos integrados para redimensionar, cortar e otimizar imagens.
|
||||
|
||||
Como exemplo - em `layouts/partials/article-link/card.html`, você tem o seguinte código:
|
||||
|
||||
```go
|
||||
{{ with .Resize "600x" }}
|
||||
<div class="w-full thumbnail_card nozoom" style="background-image:url({{ .RelPermalink }});"></div>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
O comportamento padrão do Hugo aqui é redimensionar a imagem para 600px mantendo a proporção.
|
||||
|
||||
Vale notar que as configurações de imagem padrão como o [ponto de ancoragem](https://gohugo.io/content-management/image-processing/#anchor) também podem ser definidas na sua [configuração do site](https://gohugo.io/content-management/image-processing/#processing-options) assim como no próprio template.
|
||||
|
||||
Veja os [docs do Hugo sobre processamento de imagens](https://gohugo.io/content-management/image-processing/#image-processing-methods) para mais informações.
|
||||
|
||||
## Esquemas de cores
|
||||
|
||||
O Blowfish vem com vários esquemas de cores prontos para usar. Para alterar o esquema de cores básico, você pode definir o parâmetro do tema `colorScheme`. Consulte a seção [Primeiros passos]({{< ref "getting-started#colour-schemes" >}}) para saber mais sobre os esquemas integrados.
|
||||
|
||||
Além dos esquemas padrão, você também pode criar os seus próprios e re-estilizar todo o site ao seu gosto. Os esquemas são criados colocando um arquivo `<nome-do-esquema>.css` na pasta `assets/css/schemes/`. Uma vez criado o arquivo, simplesmente referencie-o pelo nome na configuração do tema.
|
||||
|
||||
{{< alert "github">}}
|
||||
**Nota:** gerar esses arquivos manualmente pode ser difícil, eu construí uma ferramenta de terminal `nodejs` para ajudar com isso, [Fugu](https://github.com/nunocoracao/fugu). Em resumo, você passa os três valores `hex` principais da sua paleta de cores e o programa produzirá um arquivo css que pode ser importado diretamente no Blowfish.
|
||||
{{< /alert >}}
|
||||
|
||||
|
||||
O Blowfish define uma paleta de três cores que é usada em todo o tema. As três cores são definidas como variantes `neutral`, `primary` e `secondary`, cada uma contendo dez tons de cor.
|
||||
|
||||
Devido à forma como o Tailwind CSS 3.0 calcula os valores de cor com opacidade, as cores especificadas no esquema precisam [conformar-se a um formato particular](https://github.com/adamwathan/tailwind-css-variable-text-opacity-demo) fornecendo os valores de cor vermelho, verde e azul.
|
||||
|
||||
```css
|
||||
:root {
|
||||
--color-primary-500: 139, 92, 246;
|
||||
}
|
||||
```
|
||||
|
||||
Este exemplo define uma variável CSS para a cor `primary-500` com um valor vermelho de `139`, valor verde de `92` e valor azul de `246`.
|
||||
|
||||
Use uma das folhas de estilo do tema existentes como modelo. Você é livre para definir suas próprias cores, mas para inspiração, confira a [referência da paleta de cores do Tailwind](https://tailwindcss.com/docs/customizing-colors#color-palette-reference) oficial.
|
||||
|
||||
## Substituir a folha de estilos
|
||||
|
||||
Às vezes você precisa adicionar um estilo personalizado para estilizar seus próprios elementos HTML. O Blowfish prevê este cenário permitindo que você substitua os estilos padrão na sua própria folha de estilos CSS. Simplesmente crie um arquivo `custom.css` na pasta `assets/css/` do seu projeto.
|
||||
|
||||
O arquivo `custom.css` será minificado pelo Hugo e carregado automaticamente após todos os outros estilos do tema, o que significa que qualquer coisa no seu arquivo personalizado terá precedência sobre os padrões.
|
||||
|
||||
### Usar fontes adicionais
|
||||
|
||||
O Blowfish permite que você altere facilmente a fonte do seu site. Após criar um arquivo `custom.css` na pasta `assets/css/` do seu projeto, coloque seu arquivo de fonte dentro de uma pasta `fonts` na pasta raiz `static`.
|
||||
|
||||
```shell
|
||||
.
|
||||
├── assets
|
||||
│ └── css
|
||||
│ └── custom.css
|
||||
...
|
||||
└─── static
|
||||
└── fonts
|
||||
└─── font.ttf
|
||||
|
||||
```
|
||||
|
||||
Isso torna a fonte disponível para o site. Agora, a fonte pode simplesmente ser importada no seu `custom.css` e substituída onde você achar melhor. O exemplo abaixo mostra como seria substituir a fonte para todo o `html`.
|
||||
|
||||
```css
|
||||
@font-face {
|
||||
font-family: font;
|
||||
src: url('/fonts/font.ttf');
|
||||
}
|
||||
|
||||
html {
|
||||
font-family: font;
|
||||
}
|
||||
```
|
||||
|
||||
### Ajustar o tamanho da fonte
|
||||
|
||||
Alterar o tamanho da fonte do seu site é um exemplo de substituição da folha de estilos padrão. O Blowfish torna isso simples pois usa tamanhos de fonte escalados em todo o tema que são derivados do tamanho da fonte HTML base. Por padrão, o Tailwind define o tamanho padrão como `12pt`, mas pode ser alterado para qualquer valor que você preferir.
|
||||
|
||||
Crie um arquivo `custom.css` usando as [instruções acima]({{< ref "#overriding-the-stylesheet" >}}) e adicione a seguinte declaração CSS:
|
||||
|
||||
```css
|
||||
/* Aumentar o tamanho de fonte padrão */
|
||||
html {
|
||||
font-size: 13pt;
|
||||
}
|
||||
```
|
||||
|
||||
Simplesmente alterando este único valor, todos os tamanhos de fonte no seu site serão ajustados para corresponder a este novo tamanho. Portanto, para aumentar os tamanhos de fonte gerais usados, faça o valor maior que `12pt`. Da mesma forma, para diminuir os tamanhos de fonte, faça o valor menor que `12pt`.
|
||||
|
||||
### Alterar o tema de destaque de sintaxe
|
||||
|
||||
Para alterar o tema de destaque de sintaxe, crie `assets/css/custom.css` e adicione o seguinte:
|
||||
|
||||
```css
|
||||
.chroma,
|
||||
.chroma *,
|
||||
.chroma:is(.dark *),
|
||||
.chroma:is(.dark *) * {
|
||||
color: unset;
|
||||
font-weight: unset;
|
||||
font-style: unset;
|
||||
}
|
||||
```
|
||||
|
||||
Isso limpa os estilos padrão do Chroma. O próximo passo é incorporar os estilos do Chroma no seu arquivo CSS usando o comando `hugo gen chromastyles`:
|
||||
|
||||
```sh
|
||||
# Mac/Linux
|
||||
(echo 'html:not(.dark) {'; hugo gen chromastyles --style=emacs; echo '}') >> assets/css/custom.css
|
||||
(echo 'html.dark {'; hugo gen chromastyles --style=evergarden; echo '}') >> assets/css/custom.css
|
||||
|
||||
# Windows PowerShell
|
||||
# Este comando não pode ser executado no CMD; deve ser executado no PowerShell
|
||||
@("html:not(.dark) {"; (hugo gen chromastyles --style=emacs); "}") | Add-Content -Path "assets/css/custom.css"
|
||||
@("html.dark {"; (hugo gen chromastyles --style=evergarden); "}") | Add-Content -Path "assets/css/custom.css"
|
||||
```
|
||||
|
||||
Veja todos os estilos disponíveis na [documentação do Hugo](https://gohugo.io/quick-reference/syntax-highlighting-styles/#styles).
|
||||
|
||||
## Construir o CSS do tema a partir da fonte
|
||||
|
||||
Se você quiser fazer uma alteração maior, pode aproveitar o compilador JIT do Tailwind CSS e reconstruir todo o CSS do tema do zero. Isso é útil se você quiser ajustar a configuração do Tailwind ou adicionar classes extras do Tailwind à folha de estilos principal.
|
||||
|
||||
{{< alert >}}
|
||||
**Nota:** Construir o tema manualmente é destinado a usuários avançados.
|
||||
{{< /alert >}}
|
||||
|
||||
Vamos ver como funciona a construção do Tailwind CSS.
|
||||
|
||||
### Configuração do Tailwind
|
||||
|
||||
Para gerar um arquivo CSS que contenha apenas as classes do Tailwind que estão realmente sendo usadas, o compilador JIT precisa escanear todos os templates HTML e arquivos de conteúdo Markdown para verificar quais estilos estão presentes no markup. O compilador faz isso olhando o arquivo `tailwind.config.js` que está incluído na raiz do diretório do tema:
|
||||
|
||||
```js
|
||||
// themes/blowfish/tailwind.config.js
|
||||
|
||||
module.exports = {
|
||||
content: [
|
||||
"./layouts/**/*.html",
|
||||
"./content/**/*.{html,md}",
|
||||
"./themes/blowfish/layouts/**/*.html",
|
||||
"./themes/blowfish/content/**/*.{html,md}",
|
||||
],
|
||||
|
||||
// e mais...
|
||||
};
|
||||
```
|
||||
|
||||
Esta configuração padrão foi incluída com esses caminhos de conteúdo para que você possa facilmente gerar seu próprio arquivo CSS sem precisar modificá-la, desde que siga uma estrutura de projeto particular. Ou seja, **você tem que incluir o Blowfish no seu projeto como um subdiretório em `themes/blowfish/`**. Isso significa que você não pode facilmente usar os módulos Hugo para instalar o tema e deve optar pela instalação por submódulo git (recomendado) ou instalação manual. Os [docs de instalação]({{< ref "installation" >}}) explicam como instalar o tema usando qualquer um desses métodos.
|
||||
|
||||
### Estrutura do projeto
|
||||
|
||||
Para aproveitar a configuração padrão, seu projeto deve se parecer com algo assim...
|
||||
|
||||
```shell
|
||||
.
|
||||
├── assets
|
||||
│ └── css
|
||||
│ └── compiled
|
||||
│ └── main.css # este é o arquivo que vamos gerar
|
||||
├── config # config do site
|
||||
│ └── _default
|
||||
├── content # conteúdo do site
|
||||
│ ├── _index.md
|
||||
│ ├── projects
|
||||
│ │ └── _index.md
|
||||
│ └── blog
|
||||
│ └── _index.md
|
||||
├── layouts # layouts personalizados para seu site
|
||||
│ ├── partials
|
||||
│ │ └── extend-article-link/simple.html
|
||||
│ ├── projects
|
||||
│ │ └── list.html
|
||||
│ └── shortcodes
|
||||
│ └── disclaimer.html
|
||||
└── themes
|
||||
└── blowfish # submódulo git ou instalação manual do tema
|
||||
```
|
||||
|
||||
Esta estrutura de exemplo adiciona um novo tipo de conteúdo `projects` com seu próprio layout personalizado junto com um shortcode personalizado e partial estendido. Desde que o projeto siga esta estrutura, tudo o que é necessário é recompilar o arquivo `main.css`.
|
||||
|
||||
### Instalar dependências
|
||||
|
||||
Para que isso funcione, você precisará mudar para o diretório `themes/blowfish/` e instalar as dependências do projeto. Você precisará do [npm](https://docs.npmjs.com/cli/v7/configuring-npm/install) na sua máquina local para esta etapa.
|
||||
|
||||
```shell
|
||||
cd themes/blowfish
|
||||
npm install
|
||||
```
|
||||
|
||||
### Executar o compilador do Tailwind
|
||||
|
||||
Com as dependências instaladas, tudo o que resta é usar o [Tailwind CLI](https://tailwindcss.com/docs/installation/tailwind-cli) para invocar o compilador JIT. Navegue de volta para a raiz do seu projeto Hugo e execute o seguinte comando:
|
||||
|
||||
```shell
|
||||
cd ../..
|
||||
./themes/blowfish/node_modules/@tailwindcss/cli/dist/index.mjs -c ./themes/blowfish/tailwind.config.js -i ./themes/blowfish/assets/css/main.css -o ./assets/css/compiled/main.css --jit
|
||||
```
|
||||
|
||||
É um comando um pouco feio devido aos caminhos envolvidos, mas essencialmente você está chamando o Tailwind CLI e passando a localização do arquivo de config do Tailwind (o que vimos acima), onde encontrar o arquivo `main.css` do tema e então onde você quer que o arquivo CSS compilado seja colocado (ele vai para a pasta `assets/css/compiled/` do seu projeto Hugo).
|
||||
|
||||
O arquivo de config escaneará automaticamente todo o conteúdo e layouts no seu projeto assim como todos os do tema e construirá um novo arquivo CSS que contém todo o CSS necessário para seu site. Devido à forma como o Hugo lida com a hierarquia de arquivos, este arquivo no seu projeto agora substituirá automaticamente o que vem com o tema.
|
||||
|
||||
Cada vez que você fizer uma alteração nos seus layouts e precisar de novos estilos do Tailwind CSS, você pode simplesmente executar o comando novamente e gerar o novo arquivo CSS. Você também pode adicionar `-w` ao final do comando para executar o compilador JIT em modo watch.
|
||||
|
||||
### Criar um script de build
|
||||
|
||||
Para completar totalmente esta solução, você pode simplificar todo este processo adicionando aliases para estes comandos, ou fazer o que eu faço e adicionar um `package.json` à raiz do seu projeto que contenha os scripts necessários...
|
||||
|
||||
```js
|
||||
// package.json
|
||||
|
||||
{
|
||||
"name": "my-website",
|
||||
"version": "1.0.0",
|
||||
"description": "",
|
||||
"scripts": {
|
||||
"server": "hugo server -b http://localhost -p 8000",
|
||||
"dev": "NODE_ENV=development ./themes/blowfish/node_modules/@tailwindcss/cli/dist/index.mjs -c ./themes/blowfish/tailwind.config.js -i ./themes/blowfish/assets/css/main.css -o ./assets/css/compiled/main.css --jit -w",
|
||||
"build": "NODE_ENV=production ./themes/blowfish/node_modules/@tailwindcss/cli/dist/index.mjs -c ./themes/blowfish/tailwind.config.js -i ./themes/blowfish/assets/css/main.css -o ./assets/css/compiled/main.css --jit"
|
||||
},
|
||||
// e mais...
|
||||
}
|
||||
```
|
||||
|
||||
Agora quando você quiser trabalhar no design do seu site, pode invocar `npm run dev` e o compilador será executado em modo watch. Quando estiver pronto para implantar, execute `npm run build` e você terá um build limpo do Tailwind CSS.
|
||||
|
||||
🙋♀️ Se precisar de ajuda, sinta-se à vontade para fazer uma pergunta nas [GitHub Discussions](https://github.com/nunocoracao/blowfish/discussions).
|
||||
265
exampleSite/content/docs/advanced-customisation/index.pt-pt.md
Normal file
265
exampleSite/content/docs/advanced-customisation/index.pt-pt.md
Normal file
@@ -0,0 +1,265 @@
|
||||
---
|
||||
title: "Personalização avançada"
|
||||
weight: 13
|
||||
draft: false
|
||||
description: "Aprenda como construir o Blowfish manualmente."
|
||||
slug: "advanced-customisation"
|
||||
tags: ["avançado", "css", "documentação"]
|
||||
series: ["Documentação"]
|
||||
series_order: 13
|
||||
---
|
||||
|
||||
Existem muitas formas de fazer alterações avançadas ao Blowfish. Leia abaixo para saber mais sobre o que pode ser personalizado e a melhor forma de alcançar o resultado desejado.
|
||||
|
||||
Se precisar de mais orientação, publique as suas perguntas nas [GitHub Discussions](https://github.com/nunocoracao/blowfish/discussions).
|
||||
|
||||
## Estrutura do projeto Hugo
|
||||
|
||||
Antes de começar, primeiro uma nota rápida sobre a [estrutura do projeto Hugo](https://gohugo.io/getting-started/directory-structure/) e as melhores práticas para gerir o seu conteúdo e personalizações do tema.
|
||||
|
||||
{{< alert >}}
|
||||
**Em resumo:** Nunca edite diretamente os ficheiros do tema. Apenas faça personalizações nos subdiretórios do seu projeto Hugo, não no diretório themes em si.
|
||||
{{< /alert >}}
|
||||
|
||||
O Blowfish foi construído para aproveitar todas as práticas padrão do Hugo. Está concebido para permitir que todos os aspetos do tema sejam personalizados e substituídos sem alterar nenhum dos ficheiros principais do tema. Isto permite uma experiência de atualização perfeita enquanto oferece controlo total sobre a aparência e o funcionamento do seu website.
|
||||
|
||||
Para conseguir isto, nunca deve ajustar manualmente nenhum dos ficheiros do tema diretamente. Quer instale utilizando módulos Hugo, como um submódulo git ou incluindo manualmente o tema no seu diretório `themes/`, deve sempre deixar estes ficheiros intactos.
|
||||
|
||||
A forma correta de ajustar qualquer comportamento do tema é substituindo ficheiros utilizando a poderosa [ordem de pesquisa de ficheiros](https://gohugo.io/templates/lookup-order/) do Hugo. Em resumo, a ordem de pesquisa garante que quaisquer ficheiros que inclua no diretório do seu projeto terão automaticamente precedência sobre quaisquer ficheiros do tema.
|
||||
|
||||
Por exemplo, se quisesse substituir o template principal de artigo no Blowfish, pode simplesmente criar o seu próprio ficheiro `layouts/_default/single.html` e colocá-lo na raiz do seu projeto. Este ficheiro então substituirá o `single.html` do tema sem nunca alterar o tema em si. Isto funciona para qualquer ficheiro do tema - templates HTML, partials, shortcodes, ficheiros de configuração, dados, assets, etc.
|
||||
|
||||
Enquanto seguir esta prática simples, poderá sempre atualizar o tema (ou testar diferentes versões do tema) sem se preocupar em perder nenhuma das suas alterações personalizadas.
|
||||
|
||||
## Alterar definições de otimização de imagem
|
||||
|
||||
O Hugo tem vários métodos integrados para redimensionar, cortar e otimizar imagens.
|
||||
|
||||
Como exemplo - em `layouts/partials/article-link/card.html`, tem o seguinte código:
|
||||
|
||||
```go
|
||||
{{ with .Resize "600x" }}
|
||||
<div class="w-full thumbnail_card nozoom" style="background-image:url({{ .RelPermalink }});"></div>
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
O comportamento predefinido do Hugo aqui é redimensionar a imagem para 600px mantendo a proporção.
|
||||
|
||||
Vale notar que as configurações de imagem predefinidas como o [ponto de ancoragem](https://gohugo.io/content-management/image-processing/#anchor) também podem ser definidas na sua [configuração do site](https://gohugo.io/content-management/image-processing/#processing-options) assim como no próprio template.
|
||||
|
||||
Veja os [docs do Hugo sobre processamento de imagens](https://gohugo.io/content-management/image-processing/#image-processing-methods) para mais informações.
|
||||
|
||||
## Esquemas de cores
|
||||
|
||||
O Blowfish vem com vários esquemas de cores prontos a utilizar. Para alterar o esquema de cores básico, pode definir o parâmetro do tema `colorScheme`. Consulte a secção [Primeiros passos]({{< ref "getting-started#colour-schemes" >}}) para saber mais sobre os esquemas integrados.
|
||||
|
||||
Além dos esquemas predefinidos, também pode criar os seus próprios e re-estilizar todo o website ao seu gosto. Os esquemas são criados colocando um ficheiro `<nome-do-esquema>.css` na pasta `assets/css/schemes/`. Uma vez criado o ficheiro, simplesmente referencie-o pelo nome na configuração do tema.
|
||||
|
||||
{{< alert "github">}}
|
||||
**Nota:** gerar estes ficheiros manualmente pode ser difícil, eu construí uma ferramenta de terminal `nodejs` para ajudar com isso, [Fugu](https://github.com/nunocoracao/fugu). Em resumo, passa os três valores `hex` principais da sua paleta de cores e o programa produzirá um ficheiro css que pode ser importado diretamente no Blowfish.
|
||||
{{< /alert >}}
|
||||
|
||||
|
||||
O Blowfish define uma paleta de três cores que é utilizada em todo o tema. As três cores são definidas como variantes `neutral`, `primary` e `secondary`, cada uma contendo dez tons de cor.
|
||||
|
||||
Devido à forma como o Tailwind CSS 3.0 calcula os valores de cor com opacidade, as cores especificadas no esquema precisam de [conformar-se a um formato particular](https://github.com/adamwathan/tailwind-css-variable-text-opacity-demo) fornecendo os valores de cor vermelho, verde e azul.
|
||||
|
||||
```css
|
||||
:root {
|
||||
--color-primary-500: 139, 92, 246;
|
||||
}
|
||||
```
|
||||
|
||||
Este exemplo define uma variável CSS para a cor `primary-500` com um valor vermelho de `139`, valor verde de `92` e valor azul de `246`.
|
||||
|
||||
Utilize uma das folhas de estilo do tema existentes como modelo. É livre de definir as suas próprias cores, mas para inspiração, consulte a [referência da paleta de cores do Tailwind](https://tailwindcss.com/docs/customizing-colors#color-palette-reference) oficial.
|
||||
|
||||
## Substituir a folha de estilos
|
||||
|
||||
Por vezes precisa de adicionar um estilo personalizado para estilizar os seus próprios elementos HTML. O Blowfish prevê este cenário permitindo que substitua os estilos predefinidos na sua própria folha de estilos CSS. Simplesmente crie um ficheiro `custom.css` na pasta `assets/css/` do seu projeto.
|
||||
|
||||
O ficheiro `custom.css` será minificado pelo Hugo e carregado automaticamente após todos os outros estilos do tema, o que significa que qualquer coisa no seu ficheiro personalizado terá precedência sobre os valores predefinidos.
|
||||
|
||||
### Utilizar tipos de letra adicionais
|
||||
|
||||
O Blowfish permite que altere facilmente o tipo de letra do seu site. Após criar um ficheiro `custom.css` na pasta `assets/css/` do seu projeto, coloque o seu ficheiro de tipo de letra dentro de uma pasta `fonts` na pasta raiz `static`.
|
||||
|
||||
```shell
|
||||
.
|
||||
├── assets
|
||||
│ └── css
|
||||
│ └── custom.css
|
||||
...
|
||||
└─── static
|
||||
└── fonts
|
||||
└─── font.ttf
|
||||
|
||||
```
|
||||
|
||||
Isto torna o tipo de letra disponível para o website. Agora, o tipo de letra pode simplesmente ser importado no seu `custom.css` e substituído onde achar melhor. O exemplo abaixo mostra como seria substituir o tipo de letra para todo o `html`.
|
||||
|
||||
```css
|
||||
@font-face {
|
||||
font-family: font;
|
||||
src: url('/fonts/font.ttf');
|
||||
}
|
||||
|
||||
html {
|
||||
font-family: font;
|
||||
}
|
||||
```
|
||||
|
||||
### Ajustar o tamanho do tipo de letra
|
||||
|
||||
Alterar o tamanho do tipo de letra do seu website é um exemplo de substituição da folha de estilos predefinida. O Blowfish torna isto simples pois utiliza tamanhos de tipo de letra escalados em todo o tema que são derivados do tamanho do tipo de letra HTML base. Por predefinição, o Tailwind define o tamanho predefinido como `12pt`, mas pode ser alterado para qualquer valor que preferir.
|
||||
|
||||
Crie um ficheiro `custom.css` utilizando as [instruções acima]({{< ref "#overriding-the-stylesheet" >}}) e adicione a seguinte declaração CSS:
|
||||
|
||||
```css
|
||||
/* Aumentar o tamanho de tipo de letra predefinido */
|
||||
html {
|
||||
font-size: 13pt;
|
||||
}
|
||||
```
|
||||
|
||||
Simplesmente alterando este único valor, todos os tamanhos de tipo de letra no seu website serão ajustados para corresponder a este novo tamanho. Portanto, para aumentar os tamanhos de tipo de letra gerais utilizados, faça o valor maior que `12pt`. Da mesma forma, para diminuir os tamanhos de tipo de letra, faça o valor menor que `12pt`.
|
||||
|
||||
### Alterar o tema de destaque de sintaxe
|
||||
|
||||
Para alterar o tema de destaque de sintaxe, crie `assets/css/custom.css` e adicione o seguinte:
|
||||
|
||||
```css
|
||||
.chroma,
|
||||
.chroma *,
|
||||
.chroma:is(.dark *),
|
||||
.chroma:is(.dark *) * {
|
||||
color: unset;
|
||||
font-weight: unset;
|
||||
font-style: unset;
|
||||
}
|
||||
```
|
||||
|
||||
Isto limpa os estilos predefinidos do Chroma. O próximo passo é incorporar os estilos do Chroma no seu ficheiro CSS utilizando o comando `hugo gen chromastyles`:
|
||||
|
||||
```sh
|
||||
# Mac/Linux
|
||||
(echo 'html:not(.dark) {'; hugo gen chromastyles --style=emacs; echo '}') >> assets/css/custom.css
|
||||
(echo 'html.dark {'; hugo gen chromastyles --style=evergarden; echo '}') >> assets/css/custom.css
|
||||
|
||||
# Windows PowerShell
|
||||
# Este comando não pode ser executado no CMD; deve ser executado no PowerShell
|
||||
@("html:not(.dark) {"; (hugo gen chromastyles --style=emacs); "}") | Add-Content -Path "assets/css/custom.css"
|
||||
@("html.dark {"; (hugo gen chromastyles --style=evergarden); "}") | Add-Content -Path "assets/css/custom.css"
|
||||
```
|
||||
|
||||
Veja todos os estilos disponíveis na [documentação do Hugo](https://gohugo.io/quick-reference/syntax-highlighting-styles/#styles).
|
||||
|
||||
## Construir o CSS do tema a partir da fonte
|
||||
|
||||
Se quiser fazer uma alteração maior, pode aproveitar o compilador JIT do Tailwind CSS e reconstruir todo o CSS do tema do zero. Isto é útil se quiser ajustar a configuração do Tailwind ou adicionar classes extra do Tailwind à folha de estilos principal.
|
||||
|
||||
{{< alert >}}
|
||||
**Nota:** Construir o tema manualmente destina-se a utilizadores avançados.
|
||||
{{< /alert >}}
|
||||
|
||||
Vamos ver como funciona a construção do Tailwind CSS.
|
||||
|
||||
### Configuração do Tailwind
|
||||
|
||||
Para gerar um ficheiro CSS que contenha apenas as classes do Tailwind que estão realmente a ser utilizadas, o compilador JIT precisa de analisar todos os templates HTML e ficheiros de conteúdo Markdown para verificar quais estilos estão presentes no markup. O compilador faz isto olhando para o ficheiro `tailwind.config.js` que está incluído na raiz do diretório do tema:
|
||||
|
||||
```js
|
||||
// themes/blowfish/tailwind.config.js
|
||||
|
||||
module.exports = {
|
||||
content: [
|
||||
"./layouts/**/*.html",
|
||||
"./content/**/*.{html,md}",
|
||||
"./themes/blowfish/layouts/**/*.html",
|
||||
"./themes/blowfish/content/**/*.{html,md}",
|
||||
],
|
||||
|
||||
// e mais...
|
||||
};
|
||||
```
|
||||
|
||||
Esta configuração predefinida foi incluída com estes caminhos de conteúdo para que possa facilmente gerar o seu próprio ficheiro CSS sem precisar de modificá-la, desde que siga uma estrutura de projeto particular. Ou seja, **tem de incluir o Blowfish no seu projeto como um subdiretório em `themes/blowfish/`**. Isto significa que não pode facilmente utilizar os módulos Hugo para instalar o tema e deve optar pela instalação por submódulo git (recomendado) ou instalação manual. Os [docs de instalação]({{< ref "installation" >}}) explicam como instalar o tema utilizando qualquer um destes métodos.
|
||||
|
||||
### Estrutura do projeto
|
||||
|
||||
Para aproveitar a configuração predefinida, o seu projeto deve parecer-se com algo assim...
|
||||
|
||||
```shell
|
||||
.
|
||||
├── assets
|
||||
│ └── css
|
||||
│ └── compiled
|
||||
│ └── main.css # este é o ficheiro que vamos gerar
|
||||
├── config # config do site
|
||||
│ └── _default
|
||||
├── content # conteúdo do site
|
||||
│ ├── _index.md
|
||||
│ ├── projects
|
||||
│ │ └── _index.md
|
||||
│ └── blog
|
||||
│ └── _index.md
|
||||
├── layouts # layouts personalizados para o seu site
|
||||
│ ├── partials
|
||||
│ │ └── extend-article-link/simple.html
|
||||
│ ├── projects
|
||||
│ │ └── list.html
|
||||
│ └── shortcodes
|
||||
│ └── disclaimer.html
|
||||
└── themes
|
||||
└── blowfish # submódulo git ou instalação manual do tema
|
||||
```
|
||||
|
||||
Esta estrutura de exemplo adiciona um novo tipo de conteúdo `projects` com o seu próprio layout personalizado juntamente com um shortcode personalizado e partial estendido. Desde que o projeto siga esta estrutura, tudo o que é necessário é recompilar o ficheiro `main.css`.
|
||||
|
||||
### Instalar dependências
|
||||
|
||||
Para que isto funcione, precisará de mudar para o diretório `themes/blowfish/` e instalar as dependências do projeto. Precisará do [npm](https://docs.npmjs.com/cli/v7/configuring-npm/install) na sua máquina local para esta etapa.
|
||||
|
||||
```shell
|
||||
cd themes/blowfish
|
||||
npm install
|
||||
```
|
||||
|
||||
### Executar o compilador do Tailwind
|
||||
|
||||
Com as dependências instaladas, tudo o que resta é utilizar o [Tailwind CLI](https://tailwindcss.com/docs/installation/tailwind-cli) para invocar o compilador JIT. Navegue de volta para a raiz do seu projeto Hugo e execute o seguinte comando:
|
||||
|
||||
```shell
|
||||
cd ../..
|
||||
./themes/blowfish/node_modules/@tailwindcss/cli/dist/index.mjs -c ./themes/blowfish/tailwind.config.js -i ./themes/blowfish/assets/css/main.css -o ./assets/css/compiled/main.css --jit
|
||||
```
|
||||
|
||||
É um comando um pouco feio devido aos caminhos envolvidos, mas essencialmente está a chamar o Tailwind CLI e a passar-lhe a localização do ficheiro de config do Tailwind (o que vimos acima), onde encontrar o ficheiro `main.css` do tema e depois onde quer que o ficheiro CSS compilado seja colocado (vai para a pasta `assets/css/compiled/` do seu projeto Hugo).
|
||||
|
||||
O ficheiro de config analisará automaticamente todo o conteúdo e layouts no seu projeto assim como todos os do tema e construirá um novo ficheiro CSS que contém todo o CSS necessário para o seu website. Devido à forma como o Hugo lida com a hierarquia de ficheiros, este ficheiro no seu projeto agora substituirá automaticamente o que vem com o tema.
|
||||
|
||||
Cada vez que fizer uma alteração nos seus layouts e precisar de novos estilos do Tailwind CSS, pode simplesmente executar o comando novamente e gerar o novo ficheiro CSS. Também pode adicionar `-w` ao final do comando para executar o compilador JIT em modo watch.
|
||||
|
||||
### Criar um script de build
|
||||
|
||||
Para completar totalmente esta solução, pode simplificar todo este processo adicionando aliases para estes comandos, ou fazer o que eu faço e adicionar um `package.json` à raiz do seu projeto que contenha os scripts necessários...
|
||||
|
||||
```js
|
||||
// package.json
|
||||
|
||||
{
|
||||
"name": "my-website",
|
||||
"version": "1.0.0",
|
||||
"description": "",
|
||||
"scripts": {
|
||||
"server": "hugo server -b http://localhost -p 8000",
|
||||
"dev": "NODE_ENV=development ./themes/blowfish/node_modules/@tailwindcss/cli/dist/index.mjs -c ./themes/blowfish/tailwind.config.js -i ./themes/blowfish/assets/css/main.css -o ./assets/css/compiled/main.css --jit -w",
|
||||
"build": "NODE_ENV=production ./themes/blowfish/node_modules/@tailwindcss/cli/dist/index.mjs -c ./themes/blowfish/tailwind.config.js -i ./themes/blowfish/assets/css/main.css -o ./assets/css/compiled/main.css --jit"
|
||||
},
|
||||
// e mais...
|
||||
}
|
||||
```
|
||||
|
||||
Agora quando quiser trabalhar no design do seu site, pode invocar `npm run dev` e o compilador será executado em modo watch. Quando estiver pronto para implementar, execute `npm run build` e terá um build limpo do Tailwind CSS.
|
||||
|
||||
🙋♀️ Se precisar de ajuda, sinta-se à vontade para fazer uma pergunta nas [GitHub Discussions](https://github.com/nunocoracao/blowfish/discussions).
|
||||
Reference in New Issue
Block a user