From e77051ccc4b47951bfa4fde2be436b1bb2fb113b Mon Sep 17 00:00:00 2001 From: Christoph Cullmann Date: Sun, 28 Apr 2024 17:33:09 +0200 Subject: use https://github.com/nunocoracao/blowfish.git --- .../content/docs/installation/background.svg | 574 ++++++++++ .../content/docs/installation/featured.svg | 1100 ++++++++++++++++++++ .../content/docs/installation/index.it.md | 209 ++++ .../content/docs/installation/index.ja.md | 210 ++++ .../exampleSite/content/docs/installation/index.md | 210 ++++ .../content/docs/installation/index.zh-cn.md | 209 ++++ .../exampleSite/content/docs/installation/old.svg | 10 + 7 files changed, 2522 insertions(+) create mode 100644 themes/blowfish/exampleSite/content/docs/installation/background.svg create mode 100644 themes/blowfish/exampleSite/content/docs/installation/featured.svg create mode 100644 themes/blowfish/exampleSite/content/docs/installation/index.it.md create mode 100644 themes/blowfish/exampleSite/content/docs/installation/index.ja.md create mode 100644 themes/blowfish/exampleSite/content/docs/installation/index.md create mode 100644 themes/blowfish/exampleSite/content/docs/installation/index.zh-cn.md create mode 100644 themes/blowfish/exampleSite/content/docs/installation/old.svg (limited to 'themes/blowfish/exampleSite/content/docs/installation') diff --git a/themes/blowfish/exampleSite/content/docs/installation/background.svg b/themes/blowfish/exampleSite/content/docs/installation/background.svg new file mode 100644 index 0000000..a3dc3e7 --- /dev/null +++ b/themes/blowfish/exampleSite/content/docs/installation/background.svg @@ -0,0 +1,574 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/themes/blowfish/exampleSite/content/docs/installation/featured.svg b/themes/blowfish/exampleSite/content/docs/installation/featured.svg new file mode 100644 index 0000000..116289b --- /dev/null +++ b/themes/blowfish/exampleSite/content/docs/installation/featured.svg @@ -0,0 +1,1100 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/themes/blowfish/exampleSite/content/docs/installation/index.it.md b/themes/blowfish/exampleSite/content/docs/installation/index.it.md new file mode 100644 index 0000000..abc878a --- /dev/null +++ b/themes/blowfish/exampleSite/content/docs/installation/index.it.md @@ -0,0 +1,209 @@ +--- +title: "Installazione" +date: 2020-08-16 +draft: false +description: "Come installare il tema Blowfish." +slug: "installation" +tags: ["installazione", "documenti"] +series: ["Documentazione"] +series_order: 2 +--- + +Segui semplicemente la procedura standard [Avvio Rapido](https://gohugo.io/getting-started/quick-start/) di Hugo per iniziare subito. + +Sono riportate le istruzioni dettagliate per l'installazione. Sono disponibili anche le istruzioni per [aggiornare il tema](#installazione-aggiornamenti). + +## Installazione + +Queste istruzioni ti consentiranno di iniziare a utilizzare Hugo e Blowfish partendo da uno stato completamente vuoto. La maggior parte delle dipendenze menzionate in questa guida possono essere installate utilizzando il gestore pacchetti corretti per la tua piattaforma. + +### Installare Hugo + +Se non hai mai utilizzato Hugo prima, dovrai [installarlo nella tua local machine] (https://gohugo.io/getting-started/installing). +Puoi verificare se hai già installato Hugo utilizzando il comando `hugo version`. + +{{< alert >}} +Assicurati di usare la **versione 0.87.0 di Hugo** o successiva, poiché il tema sfrutta alcune delle ultime caratteristiche di Hugo. +{{< /alert >}} + +Puoi trovare le istruzioni dettagliate sull'installazione per la propria piattaforma in [Documenti Hugo](https://gohugo.io/getting-started/installing). + +### Strumenti Blowfish (raccomandato) + +Abbiamo appena lanciato un nuovo strumento CLI per aiutarti a iniziare con Blowfish. Questo ti permette di creare un nuovo progetto Hugo, di installare il tema e di impostare i file di configurazione del tema per te. È ancora in fase beta, quindi per favore [segnala qualsiasi problema che riscontri] (https://github.com/nunocoracao/blowfish-tools). + +Installa globalmente lo strumento CLI usando npm (o altri gestori di pacchetti): +```shell +npx blowfish-tools +``` +oppure + +```shell +npm i -g blowfish-tools +``` + +Poi esegui il comando `blowfish-tools` per avviare un'esecuzione interattiva che ti guiderà attraverso la creazione e la configurazione dei casi d'uso. +```shell +blowfish-tools +``` +È anche possibile eseguire il comando `blowfish-tools new` per creare un nuovo progetto Hugo e installare il tema in una sola volta. Per ulteriori informazioni, consulta la guida del CLI. +```shell +blowfish-tools new mynewsite +``` +Ecco un rapido video che ti mostra quanto sia veloce iniziare a utilizzare Blowfish con lo strumento CLI: + + + +### Installazione senza CLI + +#### Crea un novo sito + +Esegui il comando `hugo new site mywebsite` per creare un nuovo sito di Hugo in una cartella chiamata `mywebsite`. + +La cartella del progetto può essere chiamata come si vuole, ma le istruzioni che seguono presuppongono che si chiami `mywebsite`. Se si usa un nome diverso, sostituiscilo di conseguenza. + +#### Scaricare il tema Blowfish + +Esistono diversi modi per installare il tema Blowfish nel proprio sito web Hugo. Dal più facile al più difficile da installare e mantenere, sono: + +- [Git submodule](#install-using-git) (recommended) +- [Hugo module](#install-using-hugo) +- [Copia manuale dei file](#install-manually) + +Se non sei sicuro, scegli il metodo Git submodule. + +#### Installazione usando Git + +Questo è il metodo piu facile e veloce per mantere il tema aggiornato. Oltre **Hugo** e **Go**, dovrai assicurarti di avere **Git** installato nel tuo local machine. + +cambia la directory del tuo sito web Hugo (che hai creato sopra), inizializza un nuovo repository `git` e aggiungi Blowfish come sottomodulo. + +```bash +cd mywebsite +git init +git submodule add -b main https://github.com/nunocoracao/blowfish.git themes/blowfish +``` + +poi continua a [impostare i file di configurazione del tema](#set-up-theme-configuration-files). + +#### Installazione usando Hugo + +Per questo metodo utilizzerai Hugo per gestire i tuoi temi. Hugo utilizza **Go** per inizializzare e gestire i moduli, quindi assicurati di aver installato `go` prima di procedere. + +1. [Scarica](https://golang.org/dl/) e installa Go. Puoi verificare se l'hai già installato utilizzando il comando `go version`. + + {{< alert >}} + Assicurati di usare la **versione Go 1.12** o successive poiché Hugo lo richiede affinché i moduli funzionino correttamente. + {{< /alert >}} + +2. Dalla directory del tuo progetto Hugo (che hai creato sopra), inizializza i moduli per il tuo sito web: + + ```shell + # Se gestisci il tuo progetto su GitHub + Hugo mod init github.com// + + # Se gestisci il tuo progetto localmente + Hugo mod init my-project + ``` + +3. Aggiungi il tema alla tua configurazione creando un nuovo file `config/_default/module.toml` e aggiungendo quanto segue: + + ```toml + [[imports]] + path = "github.com/nunocoracao/blowfish/v2" + ``` + +4. Avvia il tuo server utilizzando `hugo server` e il tema verrà scaricato automaticamente. +5. Continua con [impostare i file di configurazione del tema](#set-up-theme-configuration-files). + +#### Installazione manuale +1. Scarica l'ultima versione del codice sorgente del tema. + + {{< button href="https://github.com/nunocoracao/blowfish/releases/latest" target="_blank" >}}Scarica da Github{{< /button >}} + + "blowfish" e "themes/" +2. Estrai l'archivio, rinomina la cartella in `blowfish` spostala nella directory `themes/` all'interno della cartella principale del tuo progetto Hugo. +3. Continua con [impostare i file di configurazione del tema](#set-up-theme-configuration-files). + +#### Imposta i file di configurazione del tema + +Nella cartella principale del tuo sito web, elimina il file `hugo.toml` generato da Hugo. Copia i file di configurazione `*.toml` dal tema nella tua cartella `config/_default/`. Ciò ti garantirà di avere tutte le impostazioni corrette del tema e ti consentirà di personalizzare facilmente il tema in base alle tue esigenze. + +{{< alert >}} +**Note:** Non dovresti sovrascrivere il file `module.toml` se ne esiste già uno nel tuo progetto! +{{< /alert >}} + +A seconda di come hai installato il tema, troverai i file di configurazione del tema in posti diversi: + +- **Hugo modules:** Nella directory della cache di Hugo o [scarica una copia](https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/nunocoracao/blowfish/ tree/main/config/_default) da GitHub +- **Git submodule o installazione manuale:** `themes/blowfish/config/_default` + +Una volta che hai copiato i file, la tua cartella delle configurazioni dovrebbe essere cosi: + +```shell +config/_default/ +├─ hugo.toml +├─ languages.en.toml +├─ markup.toml +├─ menus.en.toml +├─ module.toml # se hai usato Hugo modules come installazione +└─ params.toml +``` + +{{< alert >}} +**Importante:** Se non hai utilizzato Hugo Modules per installare Blowfish, devi aggiungere la riga `theme = "blowfish"` all'inizio del tuo file `hugo.toml`. +{{< /alert >}} + +### Passo successivo + +L'installazione di base di Blowfish è ora completa. Continua alla sezione [Per iniziare]({{< ref "getting-started" >}}) per ulteriori informazioni sulla configurazione del tema. + +--- + +## Installazione degli aggiornamenti + +Di tanto in tanto verranno pubblicate [nuove versioni](https://github.com/nunocoracao/blowfish/releases) che applicano correzioni e aggiungono nuove funzionalità al tema. Per sfruttare questi cambiamenti, dovrai aggiornare i file del tema sul tuo sito web. + +Il modo in cui procedere dipenderà dal metodo di installazione scelto al momento dell'installazione originale del tema. Le istruzioni per ciascun metodo sono disponibili di seguito. + +- [Git submodule](#update-using-git) +- [Hugo module](#update-using-hugo) +- [Copia manuale del file](#aggiornamento-manuale) + +### Aggiornamento utilizzando Git + +I sottomoduli Git possono essere aggiornati utilizzando il comando `git`. Esegui semplicemente il comando seguente e l'ultima versione del tema verrà scaricata nel tuo repository locale: + +```shell +git submodule update --remote --merge +``` + +Una volta aggiornato il sottomodulo, riavvia il tuo sito e verifica che tutto funzioni come previsto. + +### Aggiornamento utilizzando Hugo + +Hugo rende l'aggiornamento dei moduli estremamente semplice. Basta passare alla directory del progetto ed eseguire il seguente comando: + +```shell +hugo mod get -u +``` + +Hugo aggiornerà automaticamente tutti i moduli richiesti per il tuo progetto. Lo fa controllando i file `module.toml` e `go.mod`. In caso di problemi con l'aggiornamento, assicurati che questi file siano ancora configurati correttamente. + +Quindi riavvia semplicemente il tuo sito e verifica che tutto funzioni come previsto. + +### Aggiornamenti manuali + +L'aggiornamento manuale di Blowfish richiede il download dell'ultima copia del tema e la sostituzione della vecchia versione nel progetto. + +{{< alert >}} +Tieni presente che ogni personalizzazione locale apportata ai file del tema andranno perse durante questo processo. +{{< /alert >}} + +1. Scarica l'ultima versione del codice sorgente del tema. + + {{< button href="https://github.com/nunocoracao/blowfish/releases/latest" target="_blank" >}}Scarica da Github{{< /button >}} + +2. Estrai l'archivio, rinomina la cartella in "blowfish" e spostala nella directory "themes/" all'interno della cartella principale del tuo progetto Hugo. Dovrai sovrascrivere la directory esistente per sostituire tutti i file del tema. + +3. Riavvia il tuo sito e verifica che tutto funzioni come previsto. diff --git a/themes/blowfish/exampleSite/content/docs/installation/index.ja.md b/themes/blowfish/exampleSite/content/docs/installation/index.ja.md new file mode 100644 index 0000000..433ae24 --- /dev/null +++ b/themes/blowfish/exampleSite/content/docs/installation/index.ja.md @@ -0,0 +1,210 @@ +--- +title: "Installation" +date: 2020-08-16 +draft: false +description: "How to install the Blowfish theme." +slug: "installation" +tags: ["installation", "docs"] +series: ["Documentation"] +series_order: 2 +--- + +Simply follow the standard Hugo [Quick Start](https://gohugo.io/getting-started/quick-start/) procedure to get up and running quickly. + +Detailed installation instructions can be found below. Instructions for [updating the theme](#installing-updates) are also available. + +## Installation + +These instructions will get you up and running using Hugo and Blowfish from a completely blank state. Most of the dependencies mentioned in this guide can be installed using the package manager of choice for your platform. + +### Install Hugo + +If you haven't used Hugo before, you will need to [install it onto your local machine](https://gohugo.io/getting-started/installing). You can check if it's already installed by running the command `hugo version`. + +{{< alert >}} +Make sure you are using **Hugo version 0.87.0** or later as the theme takes advantage of some of the latest Hugo features. +{{< /alert >}} + +You can find detailed installation instructions for your platform in the [Hugo docs](https://gohugo.io/getting-started/installing). + +### Blowfish Tools (recommended) + +We just launched a new CLI tool to help you get started with Blowfish. It will create a new Hugo project, install the theme and set up the theme configuration files for you. It's still in beta so please [report any issues you find](https://github.com/nunocoracao/blowfish-tools). + +Install the CLI tool globally using npm (or other package manager): +```shell +npx blowfish-tools +``` +or + +```shell +npm i -g blowfish-tools +``` + +Then run the command `blowfish-tools` to start an interactive run which will guide you through creation and configuration use-cases. +```shell +blowfish-tools +``` + +You can also run the command `blowfish-tools new` to create a new Hugo project and install the theme in one go. Check the CLI help for more information. +```shell +blowfish-tools new mynewsite +``` + +Here's a quick video of how fast it is to get started with Blowfish using the CLI tool: + + + +### Install without CLI + +#### Create a new site + +Run the command `hugo new site mywebsite` to create a new Hugo site in a directory named `mywebsite`. + +Note that you can name the project directory whatever you choose, but the instructions below will assume it's named `mywebsite`. If you use a different name, be sure to substitute it accordingly. + +#### Download the Blowfish theme + +There several different ways to install the Blowfish theme into your Hugo website. From easiest to most difficult to install and maintain, they are: + +- [Git submodule](#install-using-git) (recommended) +- [Hugo module](#install-using-hugo) +- [Manual file copy](#install-manually) + +If you're unsure, choose the Git submodule method. + +#### Install using git + +This method is the quickest and easiest for keeping the theme up-to-date. Besides **Hugo** and **Go**, you'll also need to ensure you have **Git** installed on your local machine. + +Change into the directory for your Hugo website (that you created above), initialise a new `git` repository and add Blowfish as a submodule. + +```bash +cd mywebsite +git init +git submodule add -b main https://github.com/nunocoracao/blowfish.git themes/blowfish +``` + +Then continue to [set up the theme configuration files](#set-up-theme-configuration-files). + +#### Install using Hugo + +For this method you'll use Hugo to manage your themes. Hugo uses **Go** to initialise and manage modules so you need to ensure you have `go` installed before proceeding. + +1. [Download](https://golang.org/dl/) and install Go. You can check if it's already installed by using the command `go version`. + + {{< alert >}} + Make sure you are using **Go version 1.12** or later as Hugo requires this for modules to work correctly. + {{< /alert >}} + +2. From your Hugo project directory (that you created above), initialise modules for your website: + + ```shell + # If you're managing your project on GitHub + hugo mod init github.com// + + # If you're managing your project locally + hugo mod init my-project + ``` + +3. Add the theme to your configuration by creating a new file `config/_default/module.toml` and adding the following: + + ```toml + [[imports]] + path = "github.com/nunocoracao/blowfish/v2" + ``` + +4. Start your server using `hugo server` and the theme will be downloaded automatically. +5. Continue to [set up the theme configuration files](#set-up-theme-configuration-files). + +#### Install manually + +1. Download the latest release of the theme source code. + + {{< button href="https://github.com/nunocoracao/blowfish/releases/latest" target="_blank" >}}Download from Github{{< /button >}} + +2. Extract the archive, rename the folder to `blowfish` and move it to the `themes/` directory inside your Hugo project's root folder. +3. Continue to [set up the theme configuration files](#set-up-theme-configuration-files). + +#### Set up theme configuration files + +In the root folder of your website, delete the `hugo.toml` file that was generated by Hugo. Copy the `*.toml` config files from the theme into your `config/_default/` folder. This will ensure you have all the correct theme settings and will enable you to easily customise the theme to your needs. + +{{< alert >}} +**Note:** You should not overwrite the `module.toml` file if one already exists in your project! +{{< /alert >}} + +Depending on how you installed the theme you will find the theme config files in different places: + +- **Hugo Modules:** In the Hugo cache directory, or [download a copy](https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/nunocoracao/blowfish/tree/main/config/_default) from GitHub +- **Git submodule or Manual install:** `themes/blowfish/config/_default` + +Once you've copied the files, your config folder should look like this: + +```shell +config/_default/ +├─ hugo.toml +├─ languages.en.toml +├─ markup.toml +├─ menus.en.toml +├─ module.toml # if you installed using Hugo Modules +└─ params.toml +``` + +{{< alert >}} +**Important:** If you didn't use Hugo Modules to install Blowfish, you must add the line `theme = "blowfish"` to the top of your `hugo.toml` file. +{{< /alert >}} + +### Next steps + +The basic Blowfish installation is now complete. Continue to the [Getting Started]({{< ref "getting-started" >}}) section to learn more about configuring the theme. + +--- + +## Installing updates + +From time to time there will be [new releases](https://github.com/nunocoracao/blowfish/releases) posted that apply fixes and add new functionality to the theme. In order to take advantage of these changes, you will need to update the theme files on your website. + +How you go about this will depend on the installation method you chose when the theme was originally installed. Instructions for each method can be found below. + +- [Git submodule](#update-using-git) +- [Hugo module](#update-using-hugo) +- [Manual file copy](#update-manually) + +### Update using git + +Git submodules can be updated using the `git` command. Simply execute the following command and the latest version of the theme will be downloaded into your local repository: + +```shell +git submodule update --remote --merge +``` + +Once the submodule has been updated, rebuild your site and check everything works as expected. + +### Update using Hugo + +Hugo makes updating modules super easy. Simply change into your project directory and execute the following command: + +```shell +hugo mod get -u +``` + +Hugo will automatically update any modules that are required for your project. It does this by inspecting your `module.toml` and `go.mod` files. If you have any issues with the update, check to ensure these files are still configured correctly. + +Then simply rebuild your site and check everything works as expected. + +### Update manually + +Updating Blowfish manually requires you to download the latest copy of the theme and replace the old version in your project. + +{{< alert >}} +Note that any local customisations you have made to the theme files will be lost during this process. +{{< /alert >}} + +1. Download the latest release of the theme source code. + + {{< button href="https://github.com/nunocoracao/blowfish/releases/latest" target="_blank" >}}Download from Github{{< /button >}} + +2. Extract the archive, rename the folder to `blowfish` and move it to the `themes/` directory inside your Hugo project's root folder. You will need to overwrite the existing directory to replace all the theme files. + +3. Rebuild your site and check everything works as expected. diff --git a/themes/blowfish/exampleSite/content/docs/installation/index.md b/themes/blowfish/exampleSite/content/docs/installation/index.md new file mode 100644 index 0000000..433ae24 --- /dev/null +++ b/themes/blowfish/exampleSite/content/docs/installation/index.md @@ -0,0 +1,210 @@ +--- +title: "Installation" +date: 2020-08-16 +draft: false +description: "How to install the Blowfish theme." +slug: "installation" +tags: ["installation", "docs"] +series: ["Documentation"] +series_order: 2 +--- + +Simply follow the standard Hugo [Quick Start](https://gohugo.io/getting-started/quick-start/) procedure to get up and running quickly. + +Detailed installation instructions can be found below. Instructions for [updating the theme](#installing-updates) are also available. + +## Installation + +These instructions will get you up and running using Hugo and Blowfish from a completely blank state. Most of the dependencies mentioned in this guide can be installed using the package manager of choice for your platform. + +### Install Hugo + +If you haven't used Hugo before, you will need to [install it onto your local machine](https://gohugo.io/getting-started/installing). You can check if it's already installed by running the command `hugo version`. + +{{< alert >}} +Make sure you are using **Hugo version 0.87.0** or later as the theme takes advantage of some of the latest Hugo features. +{{< /alert >}} + +You can find detailed installation instructions for your platform in the [Hugo docs](https://gohugo.io/getting-started/installing). + +### Blowfish Tools (recommended) + +We just launched a new CLI tool to help you get started with Blowfish. It will create a new Hugo project, install the theme and set up the theme configuration files for you. It's still in beta so please [report any issues you find](https://github.com/nunocoracao/blowfish-tools). + +Install the CLI tool globally using npm (or other package manager): +```shell +npx blowfish-tools +``` +or + +```shell +npm i -g blowfish-tools +``` + +Then run the command `blowfish-tools` to start an interactive run which will guide you through creation and configuration use-cases. +```shell +blowfish-tools +``` + +You can also run the command `blowfish-tools new` to create a new Hugo project and install the theme in one go. Check the CLI help for more information. +```shell +blowfish-tools new mynewsite +``` + +Here's a quick video of how fast it is to get started with Blowfish using the CLI tool: + + + +### Install without CLI + +#### Create a new site + +Run the command `hugo new site mywebsite` to create a new Hugo site in a directory named `mywebsite`. + +Note that you can name the project directory whatever you choose, but the instructions below will assume it's named `mywebsite`. If you use a different name, be sure to substitute it accordingly. + +#### Download the Blowfish theme + +There several different ways to install the Blowfish theme into your Hugo website. From easiest to most difficult to install and maintain, they are: + +- [Git submodule](#install-using-git) (recommended) +- [Hugo module](#install-using-hugo) +- [Manual file copy](#install-manually) + +If you're unsure, choose the Git submodule method. + +#### Install using git + +This method is the quickest and easiest for keeping the theme up-to-date. Besides **Hugo** and **Go**, you'll also need to ensure you have **Git** installed on your local machine. + +Change into the directory for your Hugo website (that you created above), initialise a new `git` repository and add Blowfish as a submodule. + +```bash +cd mywebsite +git init +git submodule add -b main https://github.com/nunocoracao/blowfish.git themes/blowfish +``` + +Then continue to [set up the theme configuration files](#set-up-theme-configuration-files). + +#### Install using Hugo + +For this method you'll use Hugo to manage your themes. Hugo uses **Go** to initialise and manage modules so you need to ensure you have `go` installed before proceeding. + +1. [Download](https://golang.org/dl/) and install Go. You can check if it's already installed by using the command `go version`. + + {{< alert >}} + Make sure you are using **Go version 1.12** or later as Hugo requires this for modules to work correctly. + {{< /alert >}} + +2. From your Hugo project directory (that you created above), initialise modules for your website: + + ```shell + # If you're managing your project on GitHub + hugo mod init github.com// + + # If you're managing your project locally + hugo mod init my-project + ``` + +3. Add the theme to your configuration by creating a new file `config/_default/module.toml` and adding the following: + + ```toml + [[imports]] + path = "github.com/nunocoracao/blowfish/v2" + ``` + +4. Start your server using `hugo server` and the theme will be downloaded automatically. +5. Continue to [set up the theme configuration files](#set-up-theme-configuration-files). + +#### Install manually + +1. Download the latest release of the theme source code. + + {{< button href="https://github.com/nunocoracao/blowfish/releases/latest" target="_blank" >}}Download from Github{{< /button >}} + +2. Extract the archive, rename the folder to `blowfish` and move it to the `themes/` directory inside your Hugo project's root folder. +3. Continue to [set up the theme configuration files](#set-up-theme-configuration-files). + +#### Set up theme configuration files + +In the root folder of your website, delete the `hugo.toml` file that was generated by Hugo. Copy the `*.toml` config files from the theme into your `config/_default/` folder. This will ensure you have all the correct theme settings and will enable you to easily customise the theme to your needs. + +{{< alert >}} +**Note:** You should not overwrite the `module.toml` file if one already exists in your project! +{{< /alert >}} + +Depending on how you installed the theme you will find the theme config files in different places: + +- **Hugo Modules:** In the Hugo cache directory, or [download a copy](https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/nunocoracao/blowfish/tree/main/config/_default) from GitHub +- **Git submodule or Manual install:** `themes/blowfish/config/_default` + +Once you've copied the files, your config folder should look like this: + +```shell +config/_default/ +├─ hugo.toml +├─ languages.en.toml +├─ markup.toml +├─ menus.en.toml +├─ module.toml # if you installed using Hugo Modules +└─ params.toml +``` + +{{< alert >}} +**Important:** If you didn't use Hugo Modules to install Blowfish, you must add the line `theme = "blowfish"` to the top of your `hugo.toml` file. +{{< /alert >}} + +### Next steps + +The basic Blowfish installation is now complete. Continue to the [Getting Started]({{< ref "getting-started" >}}) section to learn more about configuring the theme. + +--- + +## Installing updates + +From time to time there will be [new releases](https://github.com/nunocoracao/blowfish/releases) posted that apply fixes and add new functionality to the theme. In order to take advantage of these changes, you will need to update the theme files on your website. + +How you go about this will depend on the installation method you chose when the theme was originally installed. Instructions for each method can be found below. + +- [Git submodule](#update-using-git) +- [Hugo module](#update-using-hugo) +- [Manual file copy](#update-manually) + +### Update using git + +Git submodules can be updated using the `git` command. Simply execute the following command and the latest version of the theme will be downloaded into your local repository: + +```shell +git submodule update --remote --merge +``` + +Once the submodule has been updated, rebuild your site and check everything works as expected. + +### Update using Hugo + +Hugo makes updating modules super easy. Simply change into your project directory and execute the following command: + +```shell +hugo mod get -u +``` + +Hugo will automatically update any modules that are required for your project. It does this by inspecting your `module.toml` and `go.mod` files. If you have any issues with the update, check to ensure these files are still configured correctly. + +Then simply rebuild your site and check everything works as expected. + +### Update manually + +Updating Blowfish manually requires you to download the latest copy of the theme and replace the old version in your project. + +{{< alert >}} +Note that any local customisations you have made to the theme files will be lost during this process. +{{< /alert >}} + +1. Download the latest release of the theme source code. + + {{< button href="https://github.com/nunocoracao/blowfish/releases/latest" target="_blank" >}}Download from Github{{< /button >}} + +2. Extract the archive, rename the folder to `blowfish` and move it to the `themes/` directory inside your Hugo project's root folder. You will need to overwrite the existing directory to replace all the theme files. + +3. Rebuild your site and check everything works as expected. diff --git a/themes/blowfish/exampleSite/content/docs/installation/index.zh-cn.md b/themes/blowfish/exampleSite/content/docs/installation/index.zh-cn.md new file mode 100644 index 0000000..eb09443 --- /dev/null +++ b/themes/blowfish/exampleSite/content/docs/installation/index.zh-cn.md @@ -0,0 +1,209 @@ +--- +title: "安装和配置" +date: 2020-08-16 +draft: false +description: "如何安装 Blowfish 主题。" +slug: "installation" +tags: ["安装", "文档"] +series: ["部署教程"] +series_order: 2 +--- + +如果想快速上手，可以按照标准的 Hugo [快速启动](https://gohugo.io/getting-started/quick-start/) 文档。 + +更详细的安装如下，[更新主题](#installing-updates)的教程也可以看此文档。 + +## 前言 + +本文将一步一步指导你学会使用 Hugo 和 Blowfish。本文中提到的大多数依赖项都可以在任意你想使用的平台中使用和安装。 + +### 安装 Hugo + +如果你之前没有使用过 Hugo，你首先需要了解[在本地机器安装 Hugo](https://gohugo.io/getting-started/installing)。你可以通过运行命令 `hugo version` 来检查是否安装完成。 + +{{< alert >}} +确保你使用 **Hugo 0.87.0** 或更高的版本，Blowfish 主题中使用了最新的 Hugo 特性。 +{{< /alert >}} + +你可以在 [Hugo 文档](https://gohugo.io/getting-started/installing) 中找到不同平台更加详细的安装指南。 + +### 使用 Blowfish-Tools 工具安装 (推荐) + +我们刚刚推出了一个 CLI 工具，帮助你首次使用 Blowfish。该工具将会为你创建一个新的 Hugo 项目、安装 Blowfish 主题并设置配置文件。但目前该工具仍处于测试阶段，如果遇到任何问题，请随时[提交 issues](https://github.com/nunocoracao/blowfish-tools)。 + +使用 `npm` 包或其他的包管理器，在全局环境中安装 CLI： +```shell +npx blowfish-tools +``` +或者 +```shell +npm i -g blowfish-tools +``` + +然后运行 `blowfish-tools` 命令，它将引导你完成创建和配置用例。 +```shell +blowfish-tools +``` + +你也可以运行 `blowfish-tools new` 命令来创建一个新的 Hugo 项目，并且一次性地安装主题。查看 CLI 帮助以获取更多信息。 +```shell +blowfish-tools new mynewsite +``` + +下面是一个简短的视频，介绍了如何使用 CLI 工具快速构建 Blowfish： + + + +### 无需 CLI 的安装 + +#### 创建新站点 + +运行 `hugo new site mywebsite` 命令，可以在`mywebsite`目录下创建一个新的 Hugo 站点。 + +下面会以 `mywebsite` 为例展开说明。当然你完全可以使用任何你喜欢的目录名称，但在阅读下面的内容时，请记得将`mywebsite`替换为此。 + +#### 下载 Blowfish 主题 + +有多种方法可以将 Blowfish 主题安装在 Hugo 站点中。下面我们由易到难逐一介绍： + +- [使用 Git 子模块安装](#install-using-git) (推荐) +- [使用 Hugo 模块安装](#install-using-hugo) +- [手动文件复制](#install-manually) + +如果你不确定用哪一个，请直接选择 Git 子模块的方式。 + +#### 使用 Git 子模块安装 + +这个方法可以保证主题简单且快速地安装和更新。除了 **Hugo** 和 **Go**，你还需要确保本地机器安装了 **Git**。 + +进入你刚才创建的网站目录 `mywebsite`，初始化一个新的 `git` 仓库并将 Blowfish 添加为子模块。 + +```bash +cd mywebsite +git init +git submodule add -b main https://github.com/nunocoracao/blowfish.git themes/blowfish +``` + +然后 [设置主题的配置文件](#set-up-theme-configuration-files)。 + +#### 使用 Hugo 模板安装 + +这种方法是使用 Hugo 来管理你的主题，Hugo 使用 **Go** 来初始化和管理模块，所以首先需要确保已经安装了`go`。 + +1. [下载](https://golang.org/dl/) 并安装 Go。你可以使用 `go version` 命令来检查是否安装。 + + {{< alert >}} + 确保你使用 **Go 1.12** 或 更高的版本，Hugo 需要这个版本才能加载模块。 + {{< /alert >}} + +2. 在你刚才创建的网站目录 `mywebsite`下，为你的网站初始化模块： + + ```shell + # 如果你在 Github 上管理你的项目 + hugo mod init github.com// + + # 如果你在本地管理你的项目 + hugo mod init my-project + ``` + +3. 创建一个新文件 `config/_default/module.toml`，并添加下面的内容来配置主题： + + ```toml + [[imports]] + path = "github.com/nunocoracao/blowfish/v2" + ``` + +4. 使用`hugo server` 命令后，主题将会自动下载。 +5. 然后 [设置主题的配置文件](#set-up-theme-configuration-files). + +#### 手动复制文件 + +1. 下载最新的主题源码。 + + {{< button href="https://github.com/nunocoracao/blowfish/releases/latest" target="_blank" >}}从 Github 下载{{< /button >}} + +2. 解压缩, 并将文件夹重命名为 `blowfish`，将其移动到你的 Hugo 项目根目录下的 `themes/` 目录中。 +3. 然后 [设置主题的配置文件](#set-up-theme-configuration-files). + +#### 设置主题的配置文件 + +在你的网站根目录中，删除 Hugo 自动生成的 `hugo.toml` 文件。从主题中复制 `*.toml` 文件，粘贴到 `config/_default/` 目录中。这将确保你的主题设置准确无误，在此基础上你能够轻松地自定义主题。 + +{{< alert >}} +**注意:** 如果项目中已经存在 `module.toml` 文件，请不要覆盖它！ +{{< /alert >}} + +根据你安装主题的不同方式，你可以在以下地方找到主题的配置文件： + +- **Hugo 模块:** 在 Hugo 的缓存目录, 或者从 Github [下载副本](https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/nunocoracao/blowfish/tree/main/config/_default) from GitHub +- **Git 子模块 或 本地复制文件:** `themes/blowfish/config/_default` + +一旦你复制了这些文件，你的 config 目录看起来应该是这样： + +```shell +config/_default/ +├─ hugo.toml +├─ languages.en.toml +├─ markup.toml +├─ menus.en.toml +├─ module.toml # 通过 Hugo 模块安装 +└─ params.toml +``` + +{{< alert >}} +**重要:** 如果你没有使用 Hugo 模块安装 Blowfish，那么你必须在 `hugo.toml` 文件中添加 `theme = "blowfish"`。 +{{< /alert >}} + +### 下一步 + +基本的 Blowfish 安装已经完成。继续阅读 [入门指南]({{< ref "getting-started" >}})，了解更多关于主题配置的内容。 + +--- + +## 更新主题 + +经常会有 [新版本](https://github.com/nunocoracao/blowfish/releases) 的主题发布，这些版本主要是修复 bug 和添加新功能。如果想要用到新版本的功能，那么你需要更新网站的主题。 + +如何更新主题取决于最初安装主题时选择的安装方式，具体如下： + +- [使用 Git 子模块安装](#update-using-git) +- [使用 Hugo 模块安装](#update-using-hugo) +- [手动文件复制](#update-manually) + +### 利用 git 更新 + +Git 子模块的方式，可以使用 `git` 命令更新。只需执行以下命令，最新版的主题将会下载到你的本地仓库中： + +```shell +git submodule update --remote --merge +``` + +一旦子模块更新完毕，请检查你的确实是否一切正常。 + +### Update using Hugo + +Hugo 更新也十分容易。只需要进入网站根目录，并执行以下命令即可： + +```shell +hugo mod get -u +``` + +Hugo 将自动更新项目中所需的任何模块。它通过检查 `module.toml` 和 `go.mod` 来实现的。如果你在更新过程中遇到任何问题，请确保这两个文件是正常配置的。 + +重建完毕后，请检查网站是否一切正常。 + +### 手动更新 + +手动更新 Blowfish 需要下载主题的最新副本，并替换项目中的旧版本。 + +{{< alert >}} +注意：在手动替换过程中，你对主题文件中所做的任何修改都会丢失。 +{{< /alert >}} + +1. 下载主题最新版本的源码。 + + {{< button href="https://github.com/nunocoracao/blowfish/releases/latest" target="_blank" >}}从 Github 下载{{< /button >}} + +2. 解压缩, 将文件夹重命名为 `blowfish`，并移动到根目录 `themes/` 目录下。你需要覆盖旧版以替换所有的主题文件。 + +3. 重建站点，并检查网站是否一切正常。 diff --git a/themes/blowfish/exampleSite/content/docs/installation/old.svg b/themes/blowfish/exampleSite/content/docs/installation/old.svg new file mode 100644 index 0000000..e4db6eb --- /dev/null +++ b/themes/blowfish/exampleSite/content/docs/installation/old.svg @@ -0,0 +1,10 @@ + + + + + + + + + + \ No newline at end of file -- cgit v1.2.3