blowfish

themes/blowfish/exampleSite/content/guides/202310-blowfish-tutorial/index.it.md

@@ -0,0 +1,410 @@
+---
+title: "Build your homepage using Blowfish and Hugo"
+summary: "Just one year ago, I created Blowfish, a Hugo theme crafted to build my unique vision for my personal homepage. I also decided to make it an open-source project. Fast-forward to today, and Blowfish has transformed into a thriving open-source project with over 600 stars on GitHub and a user base of hundreds. In this tutorial, I’ll show you how to get started and have your website running in a couple of minutes."
+description: "Just one year ago, I created Blowfish, a Hugo theme crafted to build my unique vision for my personal homepage. I also decided to make it an open-source project. Fast-forward to today, and Blowfish has transformed into a thriving open-source project with over 600 stars on GitHub and a user base of hundreds. In this tutorial, I’ll show you how to get started and have your website running in a couple of minutes."
+categories: ["Open-Source", "Blowfish"]
+tags: ["tutorial", "blowfish", "hugo"]
+externalUrl: "https://nunocoracao.com/posts/202310-blowfish-tutorial/"
+date: 2023-10-04
+draft: false
+showauthor: false
+authors:
+  - nunocoracao
+---
+
+Just one year ago, I created[Blowfish](https://blowfish.page/), a [Hugo](https://gohugo.io/) theme crafted to build my unique vision for my personal homepage. I also decided to make it an open-source project. Fast-forward to today, and Blowfish has transformed into a thriving open-source project with over 600 stars on GitHub and a user base of hundreds. In this tutorial, I’ll show you how to get started and have your website running in a couple of minutes.
+
+{{< github repo="nunocoracao/blowfish" >}}
+
+## TL;DR
+
+The goal of this guide is to walk a newcomer to Hugo on how to install, manage, and publish your own website. The final version of the code is available in this [repo](https://github.com/nunocoracao/blowfish-tutorial/tree/main) - for those that would like to jump to the end. 
+
+![Tutorial example](img/01.png)
+
+The visual style is just one of the many possibilities available in Blowfish. Users are encouraged to check the [documentation page](https://blowfish.page/) and learn how to customize the theme to their needs. Additionally, there are already [great examples](https://blowfish.page/users/) of the theme from other users available for inspiration. Blowfish also offers several extra features in the form of `shortcodes` available out of the box in the theme - check them out [here](https://blowfish.page/docs/shortcodes/) and get inspired. 
+
+## Setup your environment
+
+Let’s begin by installing all the tools you need. This guide will cover the steps for Mac so these instructions might not apply to your hardware and OS. If you are on Windows or Linux, please consult the guides on how to [install Hugo](https://gohugo.io/installation/), and [GitHub’s CLI](https://cli.github.com/) for your OS.
+
+Anyway, if you are using MacOS let’s install `brew` - a package manager for mac - as that will help installing and managing the other tools.
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+Once `brew` is installed let’s install Git, Hugo and GitHub’s CLI.
+```bash
+brew install git
+brew install hugo
+brew install gh
+```
+
+Create a folder for your code and open a terminal session into it (I chose _blowfish-tutorial_ in the commands below, feel free to call the folder whatever you want).
+```bash
+mkdir blowfish-tutorial
+cd blowfish-tutorial
+```
+
+Once inside the folder, the next step is to initialize your local `git`  repo.
+```bash
+git init -b main
+```
+
+Now, let’s create and sync the local repo to a GitHub repo so that your code is stored remotely.
+```bash
+gh auth login
+gh repo create
+git push --set-upstream origin main
+```
+
+Check the image below for the options I selected for this guide, again feel free to change names and description to your use-case.
+
+![gh repo create example](img/ghcreate.png)
+
+
+Finally, create a **.gitignore** file which allows you to exclude certain files from your repo automatically. I would start with something like the example below.
+
+```bash
+#others
+node_modules
+.hugo_build.lock
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+
+# Hugo
+public
+```
+
+The last step is to save all the changes to the repo.
+```bash
+git add .
+git commit -m “initial commit”
+git push
+```
+
+
+## Create site and configure it
+
+With all the tools ready, creating and configuring your site will be easy. Still within the folder you created in the last section, let’s create an empty Hugo website (_with no theme_).
+
+```bash
+hugo new site --force .
+```
+
+Once the scaffolding finishes, try the command below to run your page. Open a browser on _[https://localhost:1313](https://localhost:1313)_ to see your site…
+ 
+```bash
+hugo server
+```
+
+ Ups… Page not found – right? 
+This was expected, even though you created a website, Hugo doesn’t give any default experience – aka your site doesn’t have any page to show.  
+
+Next step, let's install Blowfish using `git submodules` which will make it easier to manage and upgrade to new versions in the future.
+ 
+```bash
+git submodule add -b main https://github.com/nunocoracao/blowfish.git themes/blowfish
+```
+
+Next, create the following folder structure at the root of your code directory - `config/_default/`. Now you will need to download [these files](https://github.com/nunocoracao/blowfish/releases/latest/download/config-default.zip) and place them in _\_default_ folder you just created. The final structure should look something like this.
+
+```md
+config/_default/
+├─ config.toml
+├─ languages.en.toml
+├─ markup.toml
+├─ menus.en.toml
+└─ params.toml
+`
+```
+
+
+Open the **config.toml** and uncomment the line **theme = "blowfish”** and you are ready to go. Try the running the site again and check the result at _[https://localhost:1313](https://localhost:1313)_
+
+```bash
+hugo server
+```
+
+You should see something like the image below. Not much yet as we didn’t add any content, but the main skeleton for Blowfish is already in place - just requires configuration. 
+
+![blowfish empty site](img/blowfishempty.png)
+
+Now let’s configure the theme. 
+
+{{< alert  d>}}
+**FYI** This guide will not cover in detail what each parameter available in Blowfish does – for everything available and how to use it, check [Blowfish documentation](https://blowfish.page/docs/configuration/#theme-parameters) for every option in every file.
+{{< /alert >}}
+
+### menus.en.toml
+This file defines your menu structure, for the top banner and the footer. For this guide, let’s create two menu sections: one for _Posts_ and one for _Tags_. 
+- **Posts** - will display the full list of entries
+- **Tags** - automatically generated based on tags placed on each article
+
+To achieve this, make sure the following entries exist in the **menus.en.toml** file. Once the changes are done, you should see the menus appearing by re-running **hugo server**.
+
+```toml
+[[main]]
+  name = "Posts"
+  pageRef = "posts"
+  weight = 10
+
+[[main]]
+  name = "Tags"
+  pageRef = "tags"
+  weight = 30
+```
+
+
+### languages.en.toml
+
+This file will configure your main details as the author of the website. Change the section below to reflect your details.
+
+```bash
+[author]
+   name = "Your name here"
+   image = "profile.jpg"
+   headline = "I'm only human"
+   bio = "A little bit about you" # appears in author card for each article
+```
+
+The images for the website should be placed in the _assets_ folder. For this step, please add a profile picture to that folder named _profile.jpg_ or change the configuration above to the filename you chose. If you don’t have a profile image available, you can use the one below for the tutorial.
+
+![profile](img/profile.jpg "assets/profile.jpg")
+
+The last step is configuring your links – social media, GitHub, etc. The file includes all the supported options, but they are commented. You are welcome to uncomment everything and delete the ones you would rather not use. Replace the right links on the ones you decided to keep. You can also change the order.
+
+
+
+### params.toml
+
+This is the main configuration file for Blowfish. Most of the visual options or customization available can be configured using it, and it covers several areas of the theme. For this tutorial, I decided to use a **background** layout - [check other layouts for Blowfish’s landing page](https://blowfish.page/) - with the **Neon** color scheme - you can pick a different color scheme if you want to - check [this list](https://blowfish.page/docs/getting-started/#colour-schemes) or [create your own](https://blowfish.page/docs/advanced-customisation/#colour-schemes).
+
+Add an **image.jpg** to the assets folder which will be the background for the site. You can also download the examples I am using in this tutorial.
+
+![background](img/background.jpg "assets/image.jpg")
+
+Now let’s jump into the _params.toml_ and start configuring the file. I will focus only on the values that need to be changed, don’t delete the rest of the file without reading the docs. Let’s begin by making sure that we have the right color scheme, that image optimization is on, and configure the default background image.
+
+```bash
+colorScheme = "neon"
+disableImageOptimization = false
+defaultBackgroundImage = "image.jpg" # used as default for background images 
+```
+
+Next, let's configure our homepage. We’re going with the _background_ layout, configuring the homepage image and recent items. Furthermore, we are using the **card view** for items in the recent category. Finally, let’s configure the header to be fixed.
+
+```bash
+[homepage]
+  layout = "background" # valid options: page, profile, hero, card, background, custom
+  homepageImage = "image.jpg" # used in: hero, and card
+  showRecent = true
+  showRecentItems = 6
+  showMoreLink = true
+  showMoreLinkDest = "/posts/"
+  cardView = true
+  cardViewScreenWidth = false
+  layoutBackgroundBlur = true # only used when layout equals background
+
+[header]
+  layout = "fixed"
+```
+
+Now configure how the article and list pages will look. Here are the configurations for those. 
+
+```bash
+[article]
+  showHero = true
+  heroStyle = "background" 
+  showSummary = true
+  showTableOfContents = true
+  showRelatedContent = true
+  relatedContentLimit = 3
+
+[list]
+  showCards = true
+  groupByYear = false
+  cardView = true
+```
+
+
+If you run **hugo server** again, you should see something like the image below.
+
+
+![blowfish no articles](img/blowfishnoarticles.png)
+
+
+
+## Adding content to your site
+
+Create a folder to place your posts in  `/content/posts`. This was also the directory configured in your menu to list all the articles. Within that folder, let’s create a new directory and give it the name **myfirstpost**. Within it create an **index.md** file – your article and place a featured.jpg or .png for in the same directory as the thumbnail for the article. Use the example below to get started. The first lines in the file are the Front Matter, which tell Hugo what the look and experience of the article will be – different themes support different params for this. Check the [docs](https://blowfish.page/docs/front-matter/) for more info.
+
+```md
+---
+title: "My first post"
+date: 2023-08-14
+draft: false
+summary: "This is my first post on my site"
+tags: ["space"]
+---
+
+## A sub-title
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi nibh nisl, vulputate eu lacus vitae, maximus molestie libero. Vestibulum laoreet, odio et sollicitudin sollicitudin, quam ligula tempus urna, sed sagittis eros eros ac felis. In tristique tortor vitae lacinia commodo. Mauris venenatis ultrices purus nec fermentum. Nunc sit amet aliquet metus. Morbi nisl felis, gravida ac consequat vitae, blandit eu libero. Curabitur porta est in dui elementum porttitor. Maecenas fermentum, tortor ac feugiat fringilla, orci sem sagittis massa, a congue risus ipsum vel massa. Aliquam sit amet nunc vulputate, facilisis neque in, faucibus nisl.
+```
+
+You can create additional articles to see what your site will look like once there is content in it. Your site should look like the images below. The main page shows the recent articles, each article is connected through others automatically via related section, you have tag aggregation, and full-text search. 
+
+{{< gallery >}}
+  <img src="img/blowfishrecent.png" class="grid-w50" />
+  <img src="img/article.png" class="grid-w50" />
+  <img src="img/search.png" class="grid-w50" />
+  <img src="img/tag.png" class="grid-w50" />
+{{< /gallery >}}
+
+
+## Ship it
+
+The only thing missing is to ship your site. I will be using [Firebase](https://firebase.google.com/) for hosting - it’s a free alternative and provides more advanced features if you are creating something more complex. Go to firebase and create a new project. Once that is done, let’s switch to the CLI as it will make it easier to configure everything.
+
+Let’s install firebase’s CLI - if not on Mac check [install instructions on Firebase](https://firebase.google.com/docs/cli).
+```bash
+brew install firebase
+```
+
+Now log in and init firebase hosting for the project.
+
+```bash
+firebase login
+firebase init
+```
+
+Select hosting and proceed.
+
+![firebase init](img/firebasecli.png)
+
+Follow the image below for the options I recommend. Make sure to set up the workflow files for GitHub actions. These will guarantee that your code will be deployed once there is a change to the repo.
+
+![firebase options](img/firebaseoptions.png)
+
+However, those files will not work out-of-box, as Hugo requires extra steps for the build to work. Please copy and paste the code blocks below to the respective files within the **.github** folder, but keep the original **projectId** in the files generated by firebase.
+
+### firebase-hosting-merge.yml
+```yaml
+# This file was auto-generated by the Firebase CLI
+# https://github.com/firebase/firebase-tools
+
+name: Deploy to Firebase Hosting on merge
+'on':
+  push:
+    branches:
+      - main
+jobs:
+  build_and_deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Hugo setup
+        uses: peaceiris/actions-hugo@v2.6.0
+        env:
+          ACTIONS_ALLOW_UNSECURE_COMMANDS: 'true'
+
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@v4
+        with:
+          submodules: true  # Fetch Hugo themes (true OR recursive)
+          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod
+
+      - name: Build with Hugo
+        env:
+          # For maximum backward compatibility with Hugo modules
+          HUGO_ENVIRONMENT: production
+          HUGO_ENV: production
+        run: hugo -E -F --minify -d public
+
+      - name: Deploy Production
+        uses: FirebaseExtended/action-hosting-deploy@v0
+        with:
+          repoToken: '${{ secrets.GITHUB_TOKEN }}'
+          firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT_BLOWFISH_TUTORIAL }}'
+          channelId: live
+          projectId: blowfish-tutorial
+
+```
+
+
+### firebase-hosting-pull-request.yml
+```yaml
+# This file was auto-generated by the Firebase CLI
+# https://github.com/firebase/firebase-tools
+
+name: Deploy to Firebase Hosting on PR
+'on': pull_request
+jobs:
+  build_and_preview:
+    if: '${{ github.event.pull_request.head.repo.full_name == github.repository }}'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Hugo setup
+        uses: peaceiris/actions-hugo@v2.6.0
+        env:
+          ACTIONS_ALLOW_UNSECURE_COMMANDS: 'true'
+
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@v4
+        with:
+          submodules: true  # Fetch Hugo themes (true OR recursive)
+          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod
+
+      - name: Build with Hugo
+        env:
+          # For maximum backward compatibility with Hugo modules
+          HUGO_ENVIRONMENT: production
+          HUGO_ENV: production
+        run:  hugo -E -F --minify -d public
+
+      - name: Deploy preview
+        uses: FirebaseExtended/action-hosting-deploy@v0
+        with:
+          repoToken: '${{ secrets.GITHUB_TOKEN }}'
+          firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT_BLOWFISH_TUTORIAL }}'
+          expires: 30d
+          channelId: preview-${{ github.event.number }}
+          projectId: blowfish-tutorial
+```
+
+
+The last step is committing your code to GitHub and let the workflows you created take care of deploying your site. Since we configured GitHub actions, this will trigger a job that will configure and deploy your site automatically.
+
+```bash
+git add .
+git commit -m "add github actions workflows"  
+git push  
+```
+
+If the actions tab for your repo, you should see something like this.
+
+![gh actions](img/githubactions.png)
+
+Once all the steps finish, your Firebase console should show something like the image below - including the links to see your app – I got a version of this tutorial running on [https://blowfish-tutorial.web.app/](https://blowfish-tutorial.web.app/).
+
+![firebase console](img/firebaseconsole.png)
+
+
+## Conclusion and Next Steps
+
+Now you have your first version of your homepage. You can make changes locally and once you commit your code they will automatically be reflected online. What shall you do next? I’ll leave you with some useful links to get you inspired and learn more about Blowfish and Hugo. 
+
+- https://blowfish.page/docs/
+- https://blowfish.page/docs/configuration/
+- https://blowfish.page/docs/shortcodes/
+- https://blowfish.page/examples/
+- https://blowfish.page/users/
+- https://gohugo.io/documentation/
+
+![blowfish final](img/01.png)

themes/blowfish/exampleSite/content/guides/202310-blowfish-tutorial/index.ja.md

@@ -0,0 +1,410 @@
+---
+title: "Build your homepage using Blowfish and Hugo"
+summary: "Just one year ago, I created Blowfish, a Hugo theme crafted to build my unique vision for my personal homepage. I also decided to make it an open-source project. Fast-forward to today, and Blowfish has transformed into a thriving open-source project with over 600 stars on GitHub and a user base of hundreds. In this tutorial, I’ll show you how to get started and have your website running in a couple of minutes."
+description: "Just one year ago, I created Blowfish, a Hugo theme crafted to build my unique vision for my personal homepage. I also decided to make it an open-source project. Fast-forward to today, and Blowfish has transformed into a thriving open-source project with over 600 stars on GitHub and a user base of hundreds. In this tutorial, I’ll show you how to get started and have your website running in a couple of minutes."
+categories: ["Open-Source", "Blowfish"]
+tags: ["tutorial", "blowfish", "hugo"]
+externalUrl: "https://nunocoracao.com/posts/202310-blowfish-tutorial/"
+date: 2023-10-04
+draft: false
+showauthor: false
+authors:
+  - nunocoracao
+---
+
+Just one year ago, I created[Blowfish](https://blowfish.page/), a [Hugo](https://gohugo.io/) theme crafted to build my unique vision for my personal homepage. I also decided to make it an open-source project. Fast-forward to today, and Blowfish has transformed into a thriving open-source project with over 600 stars on GitHub and a user base of hundreds. In this tutorial, I’ll show you how to get started and have your website running in a couple of minutes.
+
+{{< github repo="nunocoracao/blowfish" >}}
+
+## TL;DR
+
+The goal of this guide is to walk a newcomer to Hugo on how to install, manage, and publish your own website. The final version of the code is available in this [repo](https://github.com/nunocoracao/blowfish-tutorial/tree/main) - for those that would like to jump to the end. 
+
+![Tutorial example](img/01.png)
+
+The visual style is just one of the many possibilities available in Blowfish. Users are encouraged to check the [documentation page](https://blowfish.page/) and learn how to customize the theme to their needs. Additionally, there are already [great examples](https://blowfish.page/users/) of the theme from other users available for inspiration. Blowfish also offers several extra features in the form of `shortcodes` available out of the box in the theme - check them out [here](https://blowfish.page/docs/shortcodes/) and get inspired. 
+
+## Setup your environment
+
+Let’s begin by installing all the tools you need. This guide will cover the steps for Mac so these instructions might not apply to your hardware and OS. If you are on Windows or Linux, please consult the guides on how to [install Hugo](https://gohugo.io/installation/), and [GitHub’s CLI](https://cli.github.com/) for your OS.
+
+Anyway, if you are using MacOS let’s install `brew` - a package manager for mac - as that will help installing and managing the other tools.
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+Once `brew` is installed let’s install Git, Hugo and GitHub’s CLI.
+```bash
+brew install git
+brew install hugo
+brew install gh
+```
+
+Create a folder for your code and open a terminal session into it (I chose _blowfish-tutorial_ in the commands below, feel free to call the folder whatever you want).
+```bash
+mkdir blowfish-tutorial
+cd blowfish-tutorial
+```
+
+Once inside the folder, the next step is to initialize your local `git`  repo.
+```bash
+git init -b main
+```
+
+Now, let’s create and sync the local repo to a GitHub repo so that your code is stored remotely.
+```bash
+gh auth login
+gh repo create
+git push --set-upstream origin main
+```
+
+Check the image below for the options I selected for this guide, again feel free to change names and description to your use-case.
+
+![gh repo create example](img/ghcreate.png)
+
+
+Finally, create a **.gitignore** file which allows you to exclude certain files from your repo automatically. I would start with something like the example below.
+
+```bash
+#others
+node_modules
+.hugo_build.lock
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+
+# Hugo
+public
+```
+
+The last step is to save all the changes to the repo.
+```bash
+git add .
+git commit -m “initial commit”
+git push
+```
+
+
+## Create site and configure it
+
+With all the tools ready, creating and configuring your site will be easy. Still within the folder you created in the last section, let’s create an empty Hugo website (_with no theme_).
+
+```bash
+hugo new site --force .
+```
+
+Once the scaffolding finishes, try the command below to run your page. Open a browser on _[https://localhost:1313](https://localhost:1313)_ to see your site…
+ 
+```bash
+hugo server
+```
+
+ Ups… Page not found – right? 
+This was expected, even though you created a website, Hugo doesn’t give any default experience – aka your site doesn’t have any page to show.  
+
+Next step, let's install Blowfish using `git submodules` which will make it easier to manage and upgrade to new versions in the future.
+ 
+```bash
+git submodule add -b main https://github.com/nunocoracao/blowfish.git themes/blowfish
+```
+
+Next, create the following folder structure at the root of your code directory - `config/_default/`. Now you will need to download [these files](https://github.com/nunocoracao/blowfish/releases/latest/download/config-default.zip) and place them in _\_default_ folder you just created. The final structure should look something like this.
+
+```md
+config/_default/
+├─ config.toml
+├─ languages.en.toml
+├─ markup.toml
+├─ menus.en.toml
+└─ params.toml
+`
+```
+
+
+Open the **config.toml** and uncomment the line **theme = "blowfish”** and you are ready to go. Try the running the site again and check the result at _[https://localhost:1313](https://localhost:1313)_
+
+```bash
+hugo server
+```
+
+You should see something like the image below. Not much yet as we didn’t add any content, but the main skeleton for Blowfish is already in place - just requires configuration. 
+
+![blowfish empty site](img/blowfishempty.png)
+
+Now let’s configure the theme. 
+
+{{< alert  d>}}
+**FYI** This guide will not cover in detail what each parameter available in Blowfish does – for everything available and how to use it, check [Blowfish documentation](https://blowfish.page/docs/configuration/#theme-parameters) for every option in every file.
+{{< /alert >}}
+
+### menus.en.toml
+This file defines your menu structure, for the top banner and the footer. For this guide, let’s create two menu sections: one for _Posts_ and one for _Tags_. 
+- **Posts** - will display the full list of entries
+- **Tags** - automatically generated based on tags placed on each article
+
+To achieve this, make sure the following entries exist in the **menus.en.toml** file. Once the changes are done, you should see the menus appearing by re-running **hugo server**.
+
+```toml
+[[main]]
+  name = "Posts"
+  pageRef = "posts"
+  weight = 10
+
+[[main]]
+  name = "Tags"
+  pageRef = "tags"
+  weight = 30
+```
+
+
+### languages.en.toml
+
+This file will configure your main details as the author of the website. Change the section below to reflect your details.
+
+```bash
+[author]
+   name = "Your name here"
+   image = "profile.jpg"
+   headline = "I'm only human"
+   bio = "A little bit about you" # appears in author card for each article
+```
+
+The images for the website should be placed in the _assets_ folder. For this step, please add a profile picture to that folder named _profile.jpg_ or change the configuration above to the filename you chose. If you don’t have a profile image available, you can use the one below for the tutorial.
+
+![profile](img/profile.jpg "assets/profile.jpg")
+
+The last step is configuring your links – social media, GitHub, etc. The file includes all the supported options, but they are commented. You are welcome to uncomment everything and delete the ones you would rather not use. Replace the right links on the ones you decided to keep. You can also change the order.
+
+
+
+### params.toml
+
+This is the main configuration file for Blowfish. Most of the visual options or customization available can be configured using it, and it covers several areas of the theme. For this tutorial, I decided to use a **background** layout - [check other layouts for Blowfish’s landing page](https://blowfish.page/) - with the **Neon** color scheme - you can pick a different color scheme if you want to - check [this list](https://blowfish.page/docs/getting-started/#colour-schemes) or [create your own](https://blowfish.page/docs/advanced-customisation/#colour-schemes).
+
+Add an **image.jpg** to the assets folder which will be the background for the site. You can also download the examples I am using in this tutorial.
+
+![background](img/background.jpg "assets/image.jpg")
+
+Now let’s jump into the _params.toml_ and start configuring the file. I will focus only on the values that need to be changed, don’t delete the rest of the file without reading the docs. Let’s begin by making sure that we have the right color scheme, that image optimization is on, and configure the default background image.
+
+```bash
+colorScheme = "neon"
+disableImageOptimization = false
+defaultBackgroundImage = "image.jpg" # used as default for background images 
+```
+
+Next, let's configure our homepage. We’re going with the _background_ layout, configuring the homepage image and recent items. Furthermore, we are using the **card view** for items in the recent category. Finally, let’s configure the header to be fixed.
+
+```bash
+[homepage]
+  layout = "background" # valid options: page, profile, hero, card, background, custom
+  homepageImage = "image.jpg" # used in: hero, and card
+  showRecent = true
+  showRecentItems = 6
+  showMoreLink = true
+  showMoreLinkDest = "/posts/"
+  cardView = true
+  cardViewScreenWidth = false
+  layoutBackgroundBlur = true # only used when layout equals background
+
+[header]
+  layout = "fixed"
+```
+
+Now configure how the article and list pages will look. Here are the configurations for those. 
+
+```bash
+[article]
+  showHero = true
+  heroStyle = "background" 
+  showSummary = true
+  showTableOfContents = true
+  showRelatedContent = true
+  relatedContentLimit = 3
+
+[list]
+  showCards = true
+  groupByYear = false
+  cardView = true
+```
+
+
+If you run **hugo server** again, you should see something like the image below.
+
+
+![blowfish no articles](img/blowfishnoarticles.png)
+
+
+
+## Adding content to your site
+
+Create a folder to place your posts in  `/content/posts`. This was also the directory configured in your menu to list all the articles. Within that folder, let’s create a new directory and give it the name **myfirstpost**. Within it create an **index.md** file – your article and place a featured.jpg or .png for in the same directory as the thumbnail for the article. Use the example below to get started. The first lines in the file are the Front Matter, which tell Hugo what the look and experience of the article will be – different themes support different params for this. Check the [docs](https://blowfish.page/docs/front-matter/) for more info.
+
+```md
+---
+title: "My first post"
+date: 2023-08-14
+draft: false
+summary: "This is my first post on my site"
+tags: ["space"]
+---
+
+## A sub-title
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi nibh nisl, vulputate eu lacus vitae, maximus molestie libero. Vestibulum laoreet, odio et sollicitudin sollicitudin, quam ligula tempus urna, sed sagittis eros eros ac felis. In tristique tortor vitae lacinia commodo. Mauris venenatis ultrices purus nec fermentum. Nunc sit amet aliquet metus. Morbi nisl felis, gravida ac consequat vitae, blandit eu libero. Curabitur porta est in dui elementum porttitor. Maecenas fermentum, tortor ac feugiat fringilla, orci sem sagittis massa, a congue risus ipsum vel massa. Aliquam sit amet nunc vulputate, facilisis neque in, faucibus nisl.
+```
+
+You can create additional articles to see what your site will look like once there is content in it. Your site should look like the images below. The main page shows the recent articles, each article is connected through others automatically via related section, you have tag aggregation, and full-text search. 
+
+{{< gallery >}}
+  <img src="img/blowfishrecent.png" class="grid-w50" />
+  <img src="img/article.png" class="grid-w50" />
+  <img src="img/search.png" class="grid-w50" />
+  <img src="img/tag.png" class="grid-w50" />
+{{< /gallery >}}
+
+
+## Ship it
+
+The only thing missing is to ship your site. I will be using [Firebase](https://firebase.google.com/) for hosting - it’s a free alternative and provides more advanced features if you are creating something more complex. Go to firebase and create a new project. Once that is done, let’s switch to the CLI as it will make it easier to configure everything.
+
+Let’s install firebase’s CLI - if not on Mac check [install instructions on Firebase](https://firebase.google.com/docs/cli).
+```bash
+brew install firebase
+```
+
+Now log in and init firebase hosting for the project.
+
+```bash
+firebase login
+firebase init
+```
+
+Select hosting and proceed.
+
+![firebase init](img/firebasecli.png)
+
+Follow the image below for the options I recommend. Make sure to set up the workflow files for GitHub actions. These will guarantee that your code will be deployed once there is a change to the repo.
+
+![firebase options](img/firebaseoptions.png)
+
+However, those files will not work out-of-box, as Hugo requires extra steps for the build to work. Please copy and paste the code blocks below to the respective files within the **.github** folder, but keep the original **projectId** in the files generated by firebase.
+
+### firebase-hosting-merge.yml
+```yaml
+# This file was auto-generated by the Firebase CLI
+# https://github.com/firebase/firebase-tools
+
+name: Deploy to Firebase Hosting on merge
+'on':
+  push:
+    branches:
+      - main
+jobs:
+  build_and_deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Hugo setup
+        uses: peaceiris/actions-hugo@v2.6.0
+        env:
+          ACTIONS_ALLOW_UNSECURE_COMMANDS: 'true'
+
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@v4
+        with:
+          submodules: true  # Fetch Hugo themes (true OR recursive)
+          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod
+
+      - name: Build with Hugo
+        env:
+          # For maximum backward compatibility with Hugo modules
+          HUGO_ENVIRONMENT: production
+          HUGO_ENV: production
+        run: hugo -E -F --minify -d public
+
+      - name: Deploy Production
+        uses: FirebaseExtended/action-hosting-deploy@v0
+        with:
+          repoToken: '${{ secrets.GITHUB_TOKEN }}'
+          firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT_BLOWFISH_TUTORIAL }}'
+          channelId: live
+          projectId: blowfish-tutorial
+
+```
+
+
+### firebase-hosting-pull-request.yml
+```yaml
+# This file was auto-generated by the Firebase CLI
+# https://github.com/firebase/firebase-tools
+
+name: Deploy to Firebase Hosting on PR
+'on': pull_request
+jobs:
+  build_and_preview:
+    if: '${{ github.event.pull_request.head.repo.full_name == github.repository }}'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Hugo setup
+        uses: peaceiris/actions-hugo@v2.6.0
+        env:
+          ACTIONS_ALLOW_UNSECURE_COMMANDS: 'true'
+
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@v4
+        with:
+          submodules: true  # Fetch Hugo themes (true OR recursive)
+          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod
+
+      - name: Build with Hugo
+        env:
+          # For maximum backward compatibility with Hugo modules
+          HUGO_ENVIRONMENT: production
+          HUGO_ENV: production
+        run:  hugo -E -F --minify -d public
+
+      - name: Deploy preview
+        uses: FirebaseExtended/action-hosting-deploy@v0
+        with:
+          repoToken: '${{ secrets.GITHUB_TOKEN }}'
+          firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT_BLOWFISH_TUTORIAL }}'
+          expires: 30d
+          channelId: preview-${{ github.event.number }}
+          projectId: blowfish-tutorial
+```
+
+
+The last step is committing your code to GitHub and let the workflows you created take care of deploying your site. Since we configured GitHub actions, this will trigger a job that will configure and deploy your site automatically.
+
+```bash
+git add .
+git commit -m "add github actions workflows"  
+git push  
+```
+
+If the actions tab for your repo, you should see something like this.
+
+![gh actions](img/githubactions.png)
+
+Once all the steps finish, your Firebase console should show something like the image below - including the links to see your app – I got a version of this tutorial running on [https://blowfish-tutorial.web.app/](https://blowfish-tutorial.web.app/).
+
+![firebase console](img/firebaseconsole.png)
+
+
+## Conclusion and Next Steps
+
+Now you have your first version of your homepage. You can make changes locally and once you commit your code they will automatically be reflected online. What shall you do next? I’ll leave you with some useful links to get you inspired and learn more about Blowfish and Hugo. 
+
+- https://blowfish.page/docs/
+- https://blowfish.page/docs/configuration/
+- https://blowfish.page/docs/shortcodes/
+- https://blowfish.page/examples/
+- https://blowfish.page/users/
+- https://gohugo.io/documentation/
+
+![blowfish final](img/01.png)

themes/blowfish/exampleSite/content/guides/202310-blowfish-tutorial/index.md

@@ -0,0 +1,410 @@
+---
+title: "Build your homepage using Blowfish and Hugo"
+summary: "Just one year ago, I created Blowfish, a Hugo theme crafted to build my unique vision for my personal homepage. I also decided to make it an open-source project. Fast-forward to today, and Blowfish has transformed into a thriving open-source project with over 600 stars on GitHub and a user base of hundreds. In this tutorial, I’ll show you how to get started and have your website running in a couple of minutes."
+description: "Just one year ago, I created Blowfish, a Hugo theme crafted to build my unique vision for my personal homepage. I also decided to make it an open-source project. Fast-forward to today, and Blowfish has transformed into a thriving open-source project with over 600 stars on GitHub and a user base of hundreds. In this tutorial, I’ll show you how to get started and have your website running in a couple of minutes."
+categories: ["Open-Source", "Blowfish"]
+tags: ["tutorial", "blowfish", "hugo"]
+externalUrl: "https://nunocoracao.com/posts/202310-blowfish-tutorial/"
+date: 2023-10-04
+draft: false
+showauthor: false
+authors:
+  - nunocoracao
+---
+
+Just one year ago, I created[Blowfish](https://blowfish.page/), a [Hugo](https://gohugo.io/) theme crafted to build my unique vision for my personal homepage. I also decided to make it an open-source project. Fast-forward to today, and Blowfish has transformed into a thriving open-source project with over 600 stars on GitHub and a user base of hundreds. In this tutorial, I’ll show you how to get started and have your website running in a couple of minutes.
+
+{{< github repo="nunocoracao/blowfish" >}}
+
+## TL;DR
+
+The goal of this guide is to walk a newcomer to Hugo on how to install, manage, and publish your own website. The final version of the code is available in this [repo](https://github.com/nunocoracao/blowfish-tutorial/tree/main) - for those that would like to jump to the end. 
+
+![Tutorial example](img/01.png)
+
+The visual style is just one of the many possibilities available in Blowfish. Users are encouraged to check the [documentation page](https://blowfish.page/) and learn how to customize the theme to their needs. Additionally, there are already [great examples](https://blowfish.page/users/) of the theme from other users available for inspiration. Blowfish also offers several extra features in the form of `shortcodes` available out of the box in the theme - check them out [here](https://blowfish.page/docs/shortcodes/) and get inspired. 
+
+## Setup your environment
+
+Let’s begin by installing all the tools you need. This guide will cover the steps for Mac so these instructions might not apply to your hardware and OS. If you are on Windows or Linux, please consult the guides on how to [install Hugo](https://gohugo.io/installation/), and [GitHub’s CLI](https://cli.github.com/) for your OS.
+
+Anyway, if you are using MacOS let’s install `brew` - a package manager for mac - as that will help installing and managing the other tools.
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+Once `brew` is installed let’s install Git, Hugo and GitHub’s CLI.
+```bash
+brew install git
+brew install hugo
+brew install gh
+```
+
+Create a folder for your code and open a terminal session into it (I chose _blowfish-tutorial_ in the commands below, feel free to call the folder whatever you want).
+```bash
+mkdir blowfish-tutorial
+cd blowfish-tutorial
+```
+
+Once inside the folder, the next step is to initialize your local `git`  repo.
+```bash
+git init -b main
+```
+
+Now, let’s create and sync the local repo to a GitHub repo so that your code is stored remotely.
+```bash
+gh auth login
+gh repo create
+git push --set-upstream origin main
+```
+
+Check the image below for the options I selected for this guide, again feel free to change names and description to your use-case.
+
+![gh repo create example](img/ghcreate.png)
+
+
+Finally, create a **.gitignore** file which allows you to exclude certain files from your repo automatically. I would start with something like the example below.
+
+```bash
+#others
+node_modules
+.hugo_build.lock
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+
+# Hugo
+public
+```
+
+The last step is to save all the changes to the repo.
+```bash
+git add .
+git commit -m “initial commit”
+git push
+```
+
+
+## Create site and configure it
+
+With all the tools ready, creating and configuring your site will be easy. Still within the folder you created in the last section, let’s create an empty Hugo website (_with no theme_).
+
+```bash
+hugo new site --force .
+```
+
+Once the scaffolding finishes, try the command below to run your page. Open a browser on _[https://localhost:1313](https://localhost:1313)_ to see your site…
+ 
+```bash
+hugo server
+```
+
+ Ups… Page not found – right? 
+This was expected, even though you created a website, Hugo doesn’t give any default experience – aka your site doesn’t have any page to show.  
+
+Next step, let's install Blowfish using `git submodules` which will make it easier to manage and upgrade to new versions in the future.
+ 
+```bash
+git submodule add -b main https://github.com/nunocoracao/blowfish.git themes/blowfish
+```
+
+Next, create the following folder structure at the root of your code directory - `config/_default/`. Now you will need to download [these files](https://github.com/nunocoracao/blowfish/releases/latest/download/config-default.zip) and place them in _\_default_ folder you just created. The final structure should look something like this.
+
+```md
+config/_default/
+├─ config.toml
+├─ languages.en.toml
+├─ markup.toml
+├─ menus.en.toml
+└─ params.toml
+`
+```
+
+
+Open the **config.toml** and uncomment the line **theme = "blowfish”** and you are ready to go. Try the running the site again and check the result at _[https://localhost:1313](https://localhost:1313)_
+
+```bash
+hugo server
+```
+
+You should see something like the image below. Not much yet as we didn’t add any content, but the main skeleton for Blowfish is already in place - just requires configuration. 
+
+![blowfish empty site](img/blowfishempty.png)
+
+Now let’s configure the theme. 
+
+{{< alert  d>}}
+**FYI** This guide will not cover in detail what each parameter available in Blowfish does – for everything available and how to use it, check [Blowfish documentation](https://blowfish.page/docs/configuration/#theme-parameters) for every option in every file.
+{{< /alert >}}
+
+### menus.en.toml
+This file defines your menu structure, for the top banner and the footer. For this guide, let’s create two menu sections: one for _Posts_ and one for _Tags_. 
+- **Posts** - will display the full list of entries
+- **Tags** - automatically generated based on tags placed on each article
+
+To achieve this, make sure the following entries exist in the **menus.en.toml** file. Once the changes are done, you should see the menus appearing by re-running **hugo server**.
+
+```toml
+[[main]]
+  name = "Posts"
+  pageRef = "posts"
+  weight = 10
+
+[[main]]
+  name = "Tags"
+  pageRef = "tags"
+  weight = 30
+```
+
+
+### languages.en.toml
+
+This file will configure your main details as the author of the website. Change the section below to reflect your details.
+
+```bash
+[author]
+   name = "Your name here"
+   image = "profile.jpg"
+   headline = "I'm only human"
+   bio = "A little bit about you" # appears in author card for each article
+```
+
+The images for the website should be placed in the _assets_ folder. For this step, please add a profile picture to that folder named _profile.jpg_ or change the configuration above to the filename you chose. If you don’t have a profile image available, you can use the one below for the tutorial.
+
+![profile](img/profile.jpg "assets/profile.jpg")
+
+The last step is configuring your links – social media, GitHub, etc. The file includes all the supported options, but they are commented. You are welcome to uncomment everything and delete the ones you would rather not use. Replace the right links on the ones you decided to keep. You can also change the order.
+
+
+
+### params.toml
+
+This is the main configuration file for Blowfish. Most of the visual options or customization available can be configured using it, and it covers several areas of the theme. For this tutorial, I decided to use a **background** layout - [check other layouts for Blowfish’s landing page](https://blowfish.page/) - with the **Neon** color scheme - you can pick a different color scheme if you want to - check [this list](https://blowfish.page/docs/getting-started/#colour-schemes) or [create your own](https://blowfish.page/docs/advanced-customisation/#colour-schemes).
+
+Add an **image.jpg** to the assets folder which will be the background for the site. You can also download the examples I am using in this tutorial.
+
+![background](img/background.jpg "assets/image.jpg")
+
+Now let’s jump into the _params.toml_ and start configuring the file. I will focus only on the values that need to be changed, don’t delete the rest of the file without reading the docs. Let’s begin by making sure that we have the right color scheme, that image optimization is on, and configure the default background image.
+
+```bash
+colorScheme = "neon"
+disableImageOptimization = false
+defaultBackgroundImage = "image.jpg" # used as default for background images 
+```
+
+Next, let's configure our homepage. We’re going with the _background_ layout, configuring the homepage image and recent items. Furthermore, we are using the **card view** for items in the recent category. Finally, let’s configure the header to be fixed.
+
+```bash
+[homepage]
+  layout = "background" # valid options: page, profile, hero, card, background, custom
+  homepageImage = "image.jpg" # used in: hero, and card
+  showRecent = true
+  showRecentItems = 6
+  showMoreLink = true
+  showMoreLinkDest = "/posts/"
+  cardView = true
+  cardViewScreenWidth = false
+  layoutBackgroundBlur = true # only used when layout equals background
+
+[header]
+  layout = "fixed"
+```
+
+Now configure how the article and list pages will look. Here are the configurations for those. 
+
+```bash
+[article]
+  showHero = true
+  heroStyle = "background" 
+  showSummary = true
+  showTableOfContents = true
+  showRelatedContent = true
+  relatedContentLimit = 3
+
+[list]
+  showCards = true
+  groupByYear = false
+  cardView = true
+```
+
+
+If you run **hugo server** again, you should see something like the image below.
+
+
+![blowfish no articles](img/blowfishnoarticles.png)
+
+
+
+## Adding content to your site
+
+Create a folder to place your posts in  `/content/posts`. This was also the directory configured in your menu to list all the articles. Within that folder, let’s create a new directory and give it the name **myfirstpost**. Within it create an **index.md** file – your article and place a featured.jpg or .png for in the same directory as the thumbnail for the article. Use the example below to get started. The first lines in the file are the Front Matter, which tell Hugo what the look and experience of the article will be – different themes support different params for this. Check the [docs](https://blowfish.page/docs/front-matter/) for more info.
+
+```md
+---
+title: "My first post"
+date: 2023-08-14
+draft: false
+summary: "This is my first post on my site"
+tags: ["space"]
+---
+
+## A sub-title
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi nibh nisl, vulputate eu lacus vitae, maximus molestie libero. Vestibulum laoreet, odio et sollicitudin sollicitudin, quam ligula tempus urna, sed sagittis eros eros ac felis. In tristique tortor vitae lacinia commodo. Mauris venenatis ultrices purus nec fermentum. Nunc sit amet aliquet metus. Morbi nisl felis, gravida ac consequat vitae, blandit eu libero. Curabitur porta est in dui elementum porttitor. Maecenas fermentum, tortor ac feugiat fringilla, orci sem sagittis massa, a congue risus ipsum vel massa. Aliquam sit amet nunc vulputate, facilisis neque in, faucibus nisl.
+```
+
+You can create additional articles to see what your site will look like once there is content in it. Your site should look like the images below. The main page shows the recent articles, each article is connected through others automatically via related section, you have tag aggregation, and full-text search. 
+
+{{< gallery >}}
+  <img src="img/blowfishrecent.png" class="grid-w50" />
+  <img src="img/article.png" class="grid-w50" />
+  <img src="img/search.png" class="grid-w50" />
+  <img src="img/tag.png" class="grid-w50" />
+{{< /gallery >}}
+
+
+## Ship it
+
+The only thing missing is to ship your site. I will be using [Firebase](https://firebase.google.com/) for hosting - it’s a free alternative and provides more advanced features if you are creating something more complex. Go to firebase and create a new project. Once that is done, let’s switch to the CLI as it will make it easier to configure everything.
+
+Let’s install firebase’s CLI - if not on Mac check [install instructions on Firebase](https://firebase.google.com/docs/cli).
+```bash
+brew install firebase
+```
+
+Now log in and init firebase hosting for the project.
+
+```bash
+firebase login
+firebase init
+```
+
+Select hosting and proceed.
+
+![firebase init](img/firebasecli.png)
+
+Follow the image below for the options I recommend. Make sure to set up the workflow files for GitHub actions. These will guarantee that your code will be deployed once there is a change to the repo.
+
+![firebase options](img/firebaseoptions.png)
+
+However, those files will not work out-of-box, as Hugo requires extra steps for the build to work. Please copy and paste the code blocks below to the respective files within the **.github** folder, but keep the original **projectId** in the files generated by firebase.
+
+### firebase-hosting-merge.yml
+```yaml
+# This file was auto-generated by the Firebase CLI
+# https://github.com/firebase/firebase-tools
+
+name: Deploy to Firebase Hosting on merge
+'on':
+  push:
+    branches:
+      - main
+jobs:
+  build_and_deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Hugo setup
+        uses: peaceiris/actions-hugo@v2.6.0
+        env:
+          ACTIONS_ALLOW_UNSECURE_COMMANDS: 'true'
+
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@v4
+        with:
+          submodules: true  # Fetch Hugo themes (true OR recursive)
+          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod
+
+      - name: Build with Hugo
+        env:
+          # For maximum backward compatibility with Hugo modules
+          HUGO_ENVIRONMENT: production
+          HUGO_ENV: production
+        run: hugo -E -F --minify -d public
+
+      - name: Deploy Production
+        uses: FirebaseExtended/action-hosting-deploy@v0
+        with:
+          repoToken: '${{ secrets.GITHUB_TOKEN }}'
+          firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT_BLOWFISH_TUTORIAL }}'
+          channelId: live
+          projectId: blowfish-tutorial
+
+```
+
+
+### firebase-hosting-pull-request.yml
+```yaml
+# This file was auto-generated by the Firebase CLI
+# https://github.com/firebase/firebase-tools
+
+name: Deploy to Firebase Hosting on PR
+'on': pull_request
+jobs:
+  build_and_preview:
+    if: '${{ github.event.pull_request.head.repo.full_name == github.repository }}'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Hugo setup
+        uses: peaceiris/actions-hugo@v2.6.0
+        env:
+          ACTIONS_ALLOW_UNSECURE_COMMANDS: 'true'
+
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@v4
+        with:
+          submodules: true  # Fetch Hugo themes (true OR recursive)
+          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod
+
+      - name: Build with Hugo
+        env:
+          # For maximum backward compatibility with Hugo modules
+          HUGO_ENVIRONMENT: production
+          HUGO_ENV: production
+        run:  hugo -E -F --minify -d public
+
+      - name: Deploy preview
+        uses: FirebaseExtended/action-hosting-deploy@v0
+        with:
+          repoToken: '${{ secrets.GITHUB_TOKEN }}'
+          firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT_BLOWFISH_TUTORIAL }}'
+          expires: 30d
+          channelId: preview-${{ github.event.number }}
+          projectId: blowfish-tutorial
+```
+
+
+The last step is committing your code to GitHub and let the workflows you created take care of deploying your site. Since we configured GitHub actions, this will trigger a job that will configure and deploy your site automatically.
+
+```bash
+git add .
+git commit -m "add github actions workflows"  
+git push  
+```
+
+If the actions tab for your repo, you should see something like this.
+
+![gh actions](img/githubactions.png)
+
+Once all the steps finish, your Firebase console should show something like the image below - including the links to see your app – I got a version of this tutorial running on [https://blowfish-tutorial.web.app/](https://blowfish-tutorial.web.app/).
+
+![firebase console](img/firebaseconsole.png)
+
+
+## Conclusion and Next Steps
+
+Now you have your first version of your homepage. You can make changes locally and once you commit your code they will automatically be reflected online. What shall you do next? I’ll leave you with some useful links to get you inspired and learn more about Blowfish and Hugo. 
+
+- https://blowfish.page/docs/
+- https://blowfish.page/docs/configuration/
+- https://blowfish.page/docs/shortcodes/
+- https://blowfish.page/examples/
+- https://blowfish.page/users/
+- https://gohugo.io/documentation/
+
+![blowfish final](img/01.png)

themes/blowfish/exampleSite/content/guides/202310-blowfish-tutorial/index.zh-cn.md

@@ -0,0 +1,415 @@
+---
+title: "使用 Blowfish和 Hugo 构建你的主页"
+summary: "一年前我创建了 Blowfish，这是一个为了打造我的个人主页而精心设计的 Hugo 主题。我决定将其作为一个开源项目。直到今天，Blowfish 已经变成了一个蓬勃发展的开源项目，在 GitHub 上拥有超过900个 star 和数百名用户。在本教程中，我将向你展示如何搭建并在几分钟内让你的网站运行起来。"
+description: "一年前我创建了 Blowfish，这是一个为了打造我的个人主页而精心设计的 Hugo 主题。我决定将其作为一个开源项目。直到今天，Blowfish 已经变成了一个蓬勃发展的开源项目，在 GitHub 上拥有超过900个 star 和数百名用户。在本教程中，我向像你展示如何搭建并在几分钟内让你的网站运行起来。"
+categories: ["开源", "Blowfish"]
+tags: ["指南", "blowfish", "hugo"]
+externalUrl: "https://nunocoracao.com/posts/202310-blowfish-tutorial/"
+date: 2023-10-04
+draft: false
+showauthor: false
+authors:
+  - nunocoracao
+---
+
+一年前我创建了 [Blowfish](https://blowfish.page/)，这是一个为了打造我的个人主页而精心设计的 [Hugo](https://gohugo.io/) 主题。我决定将其作为一个开源项目。直到今天，Blowfish 已经变成了一个蓬勃发展的开源项目，在 GitHub 上拥有超过900个 star 和数百名用户。在本教程中，我将向你展示如何搭建并在几分钟内让你的网站运行起来。
+
+{{< github repo="nunocoracao/blowfish" >}}
+
+## TL;DR
+
+本指南的目标是指导新用户如何使用 Hugo 快速安装、管理和发布自己的网站。最终的版本可以看这个[代码库](https://github.com/nunocoracao/blowfish-tutorial/tree/main)——如果你想直接跳到结尾的话可以直接看这里。
+
+![指南示例](img/01.png)
+
+视觉风格只是 Blowfish 提供的众多特性之一。想要了解更多，我们鼓励你浏览[文档](https://blowfish.page/)，学习如何根据自己的需求自定义主题。另外，已经有许多其他用户使用该主题并提供了十分优秀的[示例](https://blowfish.page/users/)，来为你提供灵感。Blowfish 还提供了一些额外的基于 `短代码` 的功能——你可以在[这里](https://blowfish.page/docs/shortcodes/)查看它们以获取更多灵感。
+
+## 设置你的环境
+
+让我们从安装工具开始。本指南涵盖了在 Mac 操作系统下的步骤，这些命令可能不适用于你的硬件和操作系统。如果你使用的是 Windows 或 Linux，请参考文档：[安装 Hugo](https://gohugo.io/installation/) 和[GitHub CLI](https://cli.github.com/)。
+
+无论如何，如果你使用的是 MacOS，那么首先需要安装 `brew` ——一个专为 MacOS 的包管理器，这将有助于安装和管理其他工具。
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+安装完成 `brew` 后，让我们安装 Git, Hugo 和 GitHub CLI。
+```bash
+brew install git
+brew install hugo
+brew install gh
+```
+
+为你的网站代码创建一个文件夹，并在终端中打开（我在下面创建了 _blowfish-tutorial_ 文件夹，当然你可以将其重命名为任何名称）。
+```bash
+mkdir blowfish-tutorial
+cd blowfish-tutorial
+```
+
+进入文件夹后的下一步，就是初始化你本地的 `git` 仓库。
+```bash
+git init -b main
+```
+
+现在，让我们创建并同步本地仓库到 GitHub 仓库，这样你的代码就可以在远程存储。
+```bash
+gh auth login
+gh repo create
+git push --set-upstream origin main
+```
+
+查看下面的图片，这是我的远程仓库的地址。同样地，你也可以随意更改以适应你自己的 GitHub 仓库。
+
+![gh repo 创建示例](img/ghcreate.png)
+
+最后，创建一个 **.gitignore** 文件，它会自动排除某些文件，以防止这些文件传到远程仓库。下面的例子是我在 **.gitignore** 文件中添加的文件和文件夹。
+
+```bash
+#others
+node_modules
+.hugo_build.lock
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+
+# Hugo
+public
+```
+
+最后一步是保存所有更改，并推送到你的远程仓库中。
+The last step is to save all the changes to the repo.
+```bash
+git add .
+git commit -m “initial commit”
+git push
+```
+
+
+## 创建并配置站点
+
+所有的准备工作就绪后，创建和配置你的站点将会很容易。继续在上一部分你创建的文件夹内，让我们首先创建一个空的 Hugo 网站（_不关联任何主题_）。
+
+```bash
+hugo new site --force .
+```
+
+执行完成后，尝试用下面的命令来运行你的网站。打开浏览器并访问 _[https://localhost:1313](https://localhost:1313)_ 即可查看你的网站。
+ 
+```bash
+hugo server
+```
+
+emmmm… 页面未找到404了，是吧？
+这是预期内的，你创建了一个空白网站，Hugo 不会添加任何默认的页面——换句话说，你的网站还没有任何页面可以显示。
+
+下一步，让我门使用 `git submodules` 来安装 Blowfish。通过 `git submodules` 安装可以让以后管理和升级 Blowfish 主题更加方便。
+ 
+```bash
+git submodule add -b main https://github.com/nunocoracao/blowfish.git themes/blowfish
+```
+
+接下来，在你的代码根目录下创建 `config/_default/` 文件夹。现在你需要下载[这些文件](https://github.com/nunocoracao/blowfish/releases/latest/download/config-default.zip)，并把它们放在刚刚创建的 _\_default_ 文件夹内。最终的文件结构看起来应该是这样的。
+
+```md
+config/_default/
+├─ config.toml
+├─ languages.en.toml
+├─ markup.toml
+├─ menus.en.toml
+└─ params.toml
+`
+```
+
+打开 **config.toml** 并把 **theme = "blowfish”** 这一样的注释取消掉，目前为止你已经准备好了。再次尝试运行网站，并打开浏览器在_[https://localhost:1313](https://localhost:1313)_查看效果。
+
+```bash
+hugo server
+```
+
+你应该能看到下面这样。目前我们还没有添加任何内容，所以还没有页面，但是 Blowfish 主题已经准备就绪，下面只需要配置。
+
+![blowfish 空站点](img/blowfishempty.png)
+
+现在我们来配置主题。
+
+{{< alert  d>}}
+**仅供参考** 本指南不会详细介绍 Blowfish 中的所有特性和参数——如果想要了解所有的功能特性和参数，以及如何使用它们，请参考[Blowfish 文档](https://blowfish.page/docs/configuration/#theme-parameters)。
+{{< /alert >}}
+
+### menus.en.toml
+这个文件定义了你的顶部（banner）和底部（footer）的菜单结构。对于本指南，我们只使用菜单的这两部分：_Posts_ 和 _Tags_。
+- **Posts** - 用于展示网站中的所有内容条目的完整列表
+- **Tags** - 自动生成每篇文章的标签
+
+为了实现这一点，请确保 **menus.en.toml** 文件中设置了以下参数。完成修改后，重新运行**hugo server**，你将会看到顶部菜单。
+
+```toml
+[[main]]
+  name = "Posts"
+  pageRef = "posts"
+  weight = 10
+
+[[main]]
+  name = "Tags"
+  pageRef = "tags"
+  weight = 30
+```
+
+
+### languages.en.toml
+
+这个文件配置了网站作者的详细信息。修改下面的内容来定义你自己的信息。
+
+```bash
+[author]
+   name = "名字在这"
+   image = "profile.jpg"
+   headline = "我是个好人"
+   bio = "关于我的二三事" # 出现在每篇文章的作者卡片中
+```
+
+网站的图片需要防止在 _assets_ 文件夹内。针对这一步，请将一张你的个人图片添加到这个文件夹，并命名为 _profile.jpg_。
+你可以修改这个文件名，确保文件名和上面个人信息中 `image` 的参数值对应就行。如果你没有个人图片可用，你可以使用下面的图片继续教程。
+
+![profile](img/profile.jpg "assets/profile.jpg")
+
+最后一步是配置你的链接——社交媒体、GitHub 等等。该文件包含了所有支持的链接选项，不过他们被注释掉了。你可以将你希望展示的个人链接的配置项接触注释，也可以替换他们的展示顺序。
+
+### params.toml
+
+这个文件是 Blowfish 的配置文件。大部分的视觉选项或自定义的选项可以通过它进行配置，它涵盖了 Blowfish 主题的多个功能特性。
+对于本指南，我决定使用 **background** 布局，你也可以[查看Blowfish主题其他的主页布局](https://blowfish.page/)；同时使用了 **Neon** 颜色方案，你可以查看[完整的颜色方案列表](https://blowfish.page/docs/getting-started/#colour-schemes)或者[创建自己的颜色方案](https://blowfish.page/docs/advanced-customisation/#colour-schemes)。
+
+将 **image.jpg** 文件添加到 assets 文件夹，它将会作为网站的背景。你可以挑选自己喜欢的，当然也可以用本指南中使用的这张图。
+
+![background](img/background.jpg "assets/image.jpg")
+
+现在让我们打开 _params.toml_ 并开始配置。在这里我只会关注需要修改的值，不要再没看文档的情况下，删除此文件的其余部分。
+
+首先让我们确保上面提到的正确的颜色方案，开启图片优化，并设置默认背景图片。
+
+```bash
+colorScheme = "neon"
+disableImageOptimization = false
+defaultBackgroundImage = "image.jpg" # used as default for background images 
+```
+
+接下来，让我们配置首页。我们选择了 _background_ 布局，配置首页图片和最近文章。此外，可以使用 **card view** 卡片展示的方式来展现最新文章。最后让我们配置头部固定。
+
+```bash
+[homepage]
+  layout = "background" # valid options: page, profile, hero, card, background, custom
+  homepageImage = "image.jpg" # used in: hero, and card
+  showRecent = true
+  showRecentItems = 6
+  showMoreLink = true
+  showMoreLinkDest = "/posts/"
+  cardView = true
+  cardViewScreenWidth = false
+  layoutBackgroundBlur = true # only used when layout equals background
+
+[header]
+  layout = "fixed"
+```
+
+现在配置文章和列表页面的展示。下面是他们的配置。
+
+```bash
+[article]
+  showHero = true
+  heroStyle = "background" 
+  showSummary = true
+  showTableOfContents = true
+  showRelatedContent = true
+  relatedContentLimit = 3
+
+[list]
+  showCards = true
+  groupByYear = false
+  cardView = true
+```
+
+如果你再次运行**hugo server**，你会看到类似下面这张图的效果。
+If you run **hugo server** again, you should see something like the image below.
+
+
+![blowfish 没有文章](img/blowfishnoarticles.png)
+
+
+
+## 在你的网站中添加内容
+
+创建一个文件夹`/content/posts`，在这个文件夹下添加你的帖子或文章。这也是你在菜单所配置的所有文章的根目录。在这个文件夹内，让我们创建一个新目录并命名为 **myfirstpost**。在这个目录中创建一个**index.md**文件作为你的文章，同样也在这个目录中添加**featured.jpg**或**featured.png**作为文章的缩略图。
+参考下面这个示例。文件中的前几行是扉页参数（Front Matter），它定义了 Hugo 如何展示文章，更多的参数可以参考[这里](https://blowfish.page/docs/front-matter/)。
+
+```md
+---
+title: "我的第一篇帖子"
+date: 2023-08-14
+draft: false
+summary: "这是网站的第一篇你帖子"
+tags: ["space"]
+---
+
+## 一个副标题
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Morbi nibh nisl, vulputate eu lacus vitae, maximus molestie libero. Vestibulum laoreet, odio et sollicitudin sollicitudin, quam ligula tempus urna, sed sagittis eros eros ac felis. In tristique tortor vitae lacinia commodo. Mauris venenatis ultrices purus nec fermentum. Nunc sit amet aliquet metus. Morbi nisl felis, gravida ac consequat vitae, blandit eu libero. Curabitur porta est in dui elementum porttitor. Maecenas fermentum, tortor ac feugiat fringilla, orci sem sagittis massa, a congue risus ipsum vel massa. Aliquam sit amet nunc vulputate, facilisis neque in, faucibus nisl.
+```
+
+你可以创建其他文章，来查看和验证站点的效果。你的网站应该像下面的图片一样。
+主页显示最近的文章，每篇文章通过相关部分自动关联其他文章，有标签聚合和全文搜索。
+
+{{< gallery >}}
+  <img src="img/blowfishrecent.png" class="grid-w50" />
+  <img src="img/article.png" class="grid-w50" />
+  <img src="img/search.png" class="grid-w50" />
+  <img src="img/tag.png" class="grid-w50" />
+{{< /gallery >}}
+
+
+## 发布它
+
+现在只剩下发布你的网站了。我将会使用 [Firebase](https://firebase.google.com/) 作为托管服务——这是一个免费的替代方案，如果你创建了更复杂的东西，它提供了高级功能。前往 [Firebase](https://firebase.google.com/) 创建一个新项目，然后我们切换到 CLI 终端，这将是配置 [Firebase](https://firebase.google.com/) 更加简单。
+
+让我们安装 [Firebase](https://firebase.google.com/) CLI 工具 —— 如果你不是 MacOS，请查看 [Firebase安装指南](https://firebase.google.com/docs/cli)。
+```bash
+brew install firebase
+```
+
+现在登录并为你的项目初始化firebase托管服务。
+
+```bash
+firebase login
+firebase init
+```
+
+选择托管并继续。
+
+![firebase 初始化](img/firebasecli.png)
+
+按照下面的图片进行，这是我推荐的方式。确保设置了 GitHub actions 工作流文件。这将保证你的 GitHub 仓库一旦有变化，就会立刻同步部署。
+
+![firebase 选项](img/firebaseoptions.png)
+
+然而，这些文件不会立刻开始运行，因为 Hugo 需要额外的步骤来提前构建。将下面的代码复制并粘贴到 **.github** 文件夹，同时保留文件中 firebase 生成的**projectId**。
+
+### firebase-hosting-merge.yml
+```yaml
+# This file was auto-generated by the Firebase CLI
+# https://github.com/firebase/firebase-tools
+
+name: Deploy to Firebase Hosting on merge
+'on':
+  push:
+    branches:
+      - main
+jobs:
+  build_and_deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Hugo setup
+        uses: peaceiris/actions-hugo@v2.6.0
+        env:
+          ACTIONS_ALLOW_UNSECURE_COMMANDS: 'true'
+
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@v4
+        with:
+          submodules: true  # Fetch Hugo themes (true OR recursive)
+          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod
+
+      - name: Build with Hugo
+        env:
+          # For maximum backward compatibility with Hugo modules
+          HUGO_ENVIRONMENT: production
+          HUGO_ENV: production
+        run: hugo -E -F --minify -d public
+
+      - name: Deploy Production
+        uses: FirebaseExtended/action-hosting-deploy@v0
+        with:
+          repoToken: '${{ secrets.GITHUB_TOKEN }}'
+          firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT_BLOWFISH_TUTORIAL }}'
+          channelId: live
+          projectId: blowfish-tutorial
+
+```
+
+
+### firebase-hosting-pull-request.yml
+```yaml
+# This file was auto-generated by the Firebase CLI
+# https://github.com/firebase/firebase-tools
+
+name: Deploy to Firebase Hosting on PR
+'on': pull_request
+jobs:
+  build_and_preview:
+    if: '${{ github.event.pull_request.head.repo.full_name == github.repository }}'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Hugo setup
+        uses: peaceiris/actions-hugo@v2.6.0
+        env:
+          ACTIONS_ALLOW_UNSECURE_COMMANDS: 'true'
+
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@v4
+        with:
+          submodules: true  # Fetch Hugo themes (true OR recursive)
+          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod
+
+      - name: Build with Hugo
+        env:
+          # For maximum backward compatibility with Hugo modules
+          HUGO_ENVIRONMENT: production
+          HUGO_ENV: production
+        run:  hugo -E -F --minify -d public
+
+      - name: Deploy preview
+        uses: FirebaseExtended/action-hosting-deploy@v0
+        with:
+          repoToken: '${{ secrets.GITHUB_TOKEN }}'
+          firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT_BLOWFISH_TUTORIAL }}'
+          expires: 30d
+          channelId: preview-${{ github.event.number }}
+          projectId: blowfish-tutorial
+```
+
+最后一步是将你的代码提交到 GitHub，提交成功后 GitHub actions 工作流将会自动触发，并构建和部署你的网站。
+
+```bash
+git add .
+git commit -m "add github actions workflows"  
+git push  
+```
+
+你的 GitHub 仓库中的 actions 模块，将会显示类似下图的内容。
+
+![gh actions](img/githubactions.png)
+
+当所有步骤完成之后，你的 Firebase 控制台将会显示类似下图的内容，包括一个可以查看网站的链接。我在[https://blowfish-tutorial.web.app/](https://blowfish-tutorial.web.app/)中运行了这个教程。
+Once all the steps finish, your Firebase console should show something like the image below - including the links to see your app – I got a version of this tutorial running on [https://blowfish-tutorial.web.app/](https://blowfish-tutorial.web.app/).
+
+![firebase console](img/firebaseconsole.png)
+
+
+## 结论和下一步
+
+现在你有了主页的第一个版本。你可以在本地进行更改，只要你提交代码，将会自动展示在你的网站中。
+那么接下来要做什么呢？我给你留了一下链接，相信会对你有所帮你，其它这些链接会让你获得灵感并了解更多 Blowfish 和 Hugo 的内容。
+Now you have your first version of your homepage. You can make changes locally and once you commit your code they will automatically be reflected online. What shall you do next? I’ll leave you with some useful links to get you inspired and learn more about Blowfish and Hugo. 
+
+- https://blowfish.page/docs/
+- https://blowfish.page/docs/configuration/
+- https://blowfish.page/docs/shortcodes/
+- https://blowfish.page/examples/
+- https://blowfish.page/users/
+- https://gohugo.io/documentation/
+
+![blowfish final](img/01.png)

themes/blowfish/exampleSite/content/guides/_index.it.md

@@ -0,0 +1,19 @@
+---
+title: "Recipes"
+description: "Recipes, guides, and tutorials for Blowfish"
+
+cascade:
+  showDate: false
+  showAuthor: false
+  invertPagination: true
+---
+
+{{< lead >}}
+Recipes, guides, and tutorials for Blowfish
+{{< /lead >}}
+
+**Blowfish user?** To add your guide to this list, [check the template](/guides/template/).
+
+This section contains guides for a variety of scenarios on how to configure your theme. If you're new, check out the [Installation]({{< ref "docs/installation" >}}) guide to begin or visit the [Samples]({{< ref "samples" >}}) section to see what Blowfish can do.
+
+---

themes/blowfish/exampleSite/content/guides/_index.ja.md

@@ -0,0 +1,19 @@
+---
+title: "レシピ"
+description: "Blowfish のためのレシピ、ガイド、チュートリアル"
+
+cascade:
+  showDate: false
+  showAuthor: false
+  invertPagination: true
+---
+
+{{< lead >}}
+Blowfish のためのレシピ、ガイド、チュートリアル
+{{< /lead >}}
+
+**Blowfish ユーザーですか?** この一覧にあなたのガイドを加える際は、[テンプレートを確認](/guides/template/)してください。
+
+このセクションではあなたのテーマの設定方法する様々なシナリオを含んでいます。新しく作成する場合は、開始するために[インストール]({{< ref "docs/installation" >}})ガイド、または Blowfish が何が出来るか[サンプル]({{< ref "samples" >}})セクションに訪れてください。
+
+---

themes/blowfish/exampleSite/content/guides/_index.md

@@ -0,0 +1,19 @@
+---
+title: "Recipes"
+description: "Recipes, guides, and tutorials for Blowfish"
+
+cascade:
+  showDate: false
+  showAuthor: false
+  invertPagination: true
+---
+
+{{< lead >}}
+Recipes, guides, and tutorials for Blowfish
+{{< /lead >}}
+
+**Blowfish user?** To add your guide to this list, [check the template](/guides/template/).
+
+This section contains guides for a variety of scenarios on how to configure your theme. If you're new, check out the [Installation]({{< ref "docs/installation" >}}) guide to begin or visit the [Samples]({{< ref "samples" >}}) section to see what Blowfish can do.
+
+---

themes/blowfish/exampleSite/content/guides/_index.zh-cn.md

@@ -0,0 +1,19 @@
+---
+title: "使用指南"
+description: "Blowfish 的使用指南和教程"
+
+cascade:
+  showDate: false
+  showAuthor: false
+  invertPagination: true
+---
+
+{{< lead >}}
+Blowfish 的使用指南和教程
+{{< /lead >}}
+
+**您是 Blowfish 的用户吗?** 要将您自己编写的指南添加到此列表，请查看[参考模板](/guides/template/)。
+
+本部分包含有关如何配置主题的各种指南。如果您是新用户，请查看 [安装]({{< ref "docs/installation" >}}) 指南或查看 [示例]({{< ref "samples" >}}) 部分来了解 Blowfish 能做出什么效果的网页。
+
+---

themes/blowfish/exampleSite/content/guides/template/index.it.md

@@ -0,0 +1,36 @@
+---
+title: "Recipe Template"
+date: 1987-12-22
+draft: false
+description: "Template for creating a recipe for Blowfish theme"
+tags: ["template"]
+---
+
+Thank you for wanting to contribute to Blowfish's community.
+
+## How to start?
+This is a template article that will explain how to create a new article for Blowfish's guide section.
+
+## Clone Blowfish
+Clone this repo with the following command:
+
+```bash
+git clone https://github.com/nunocoracao/blowfish.git
+```
+
+## Setup your files
+Copy and paste the entire folder where this `.md` file is.
+
+Name it using the following convention `YYYYMM-title`, no white spaces are allowed.
+
+## Write your guide
+Write your guide :)
+
+Use the `img` folder to place your images and use them:
+
+![]()
+
+![Example](img/example.jpg "Image caption")
+
+## Open a PR
+Open a PR and thanks in advance for your contribution.

themes/blowfish/exampleSite/content/guides/template/index.ja.md

@@ -0,0 +1,36 @@
+---
+title: "レシピテンプレート"
+date: 1987-12-22
+draft: false
+description: "Blowfish テーマのレシピを作成するためのテンプレート"
+tags: ["template"]
+---
+
+Blowfish コミュニティーのコントリビュートに興味を持っていただきありがとうございます。
+
+## 開始方法
+こちらは Blowfish のガイドセクションに新しい記事を作成する方法を説明するテンプレート記事です。
+
+## Blowfish をクローンする
+こちらのコマンドでこのレポジトリをクローンします:
+
+```bash
+git clone https://github.com/nunocoracao/blowfish.git
+```
+
+## ファイルを準備する
+この `.md` ファイルが入っているフォルダ全体をコピーし、貼り付けます。
+
+フォルダ名に利用する名前は `YYYYMM-title` のようにスペースが利用できない規約となっています。
+
+## ガイドを書く
+あなたのガイドを書きます ('v')
+
+`img` フォルダーを利用して画像を配置でき、このようになります:
+
+![]()
+
+![例](img/example.jpg "画像のキャプション")
+
+## PR を開く
+PR を開くことやコントリビューションにあらかじめ感謝の言葉を述べます。

themes/blowfish/exampleSite/content/guides/template/index.md

@@ -0,0 +1,36 @@
+---
+title: "Recipe Template"
+date: 1987-12-22
+draft: false
+description: "Template for creating a recipe for Blowfish theme"
+tags: ["template"]
+---
+
+Thank you for wanting to contribute to Blowfish's community.
+
+## How to start?
+This is a template article that will explain how to create a new article for Blowfish's guide section.
+
+## Clone Blowfish
+Clone this repo with the following command:
+
+```bash
+git clone https://github.com/nunocoracao/blowfish.git
+```
+
+## Setup your files
+Copy and paste the entire folder where this `.md` file is.
+
+Name it using the following convention `YYYYMM-title`, no white spaces are allowed.
+
+## Write your guide
+Write your guide :)
+
+Use the `img` folder to place your images and use them:
+
+![]()
+
+![Example](img/example.jpg "Image caption")
+
+## Open a PR
+Open a PR and thanks in advance for your contribution.

themes/blowfish/exampleSite/content/guides/template/index.zh-cn.md

@@ -0,0 +1,37 @@
+---
+title: "使用指南模板"
+date: 1987-12-22
+draft: false
+description: "用于创建 Blowfish 主题使用指南的模板"
+tags: ["模板"]
+---
+
+感谢您愿意为 Blowfish 社区做出贡献。
+
+## 如何开始？
+这是一篇模板文章，将解释如何为 Blowfish 的指南部分创建新文章。
+
+## Clone Blowfish 仓库
+使用以下命令 clone 此仓库：
+
+```bash
+git clone https://github.com/nunocoracao/blowfish.git
+```
+
+## 配置您的文档
+复制并粘贴您要创建的 `.md` 文档所在的整个文件夹。
+使用 `YYYYMM-<英文标题>` 的格式（例如：`200601-tutorial`）命名文档，不允许有空格。
+
+## 编写您的指南
+编写您的指南 :)
+
+在 `img` 文件夹中储存图像并按下述格式引用它们：
+
+``` md
+![]()
+```
+
+![Example](img/example.jpg "Image caption")
+
+## 提交 PR
+提交您的 PR ，Blowfish 团队在这里提前感谢您对我们这个项目的贡献。