Blowfish Hugo Theme

Blowfish supports multilingual sites and Right-to-Left (RTL) languages.

• Multilingual: The site will render all available translations if content is provided in multiple languages.
• RTL: RTL support is controlled automatically based on the language. When an RTL language is detected, the entire site layout flips to support right-to-left reading. You can mix RTL and LTR content within the same project, and the theme will respond to the language of the specific content.

Update the theme based on your installation method:

Git Submodule: Run the following in your project root:

git submodule update --remote --merge

Hugo Modules: Run the following in your project root:

hugo mod get -u

Manual Installation:

1. Download the latest source from GitHub Releases.
2. Extract and rename the folder to blowfish.
3. Replace the existing themes/blowfish directory with the new one. Note: Local customizations in the theme folder will be lost.

To use custom fonts, follow these steps:

1. Place your font files (e.g., .ttf) in static/fonts/.
2. Reference them in your assets/css/custom.css using @font-face.

Directory Structure:

.
├── assets
│   └── css
│       └── custom.css
...
└─── static
    └── fonts
        └─── font.ttf

Example CSS implementation:

@font-face {
    font-family: font;
    src: url('/fonts/font.ttf');
}

html {
    font-family: font;
}

Blowfish provides additional front matter parameters to customize the presentation of individual articles. These parameters inherit their default values from the theme's base configuration, so you only need to specify them in your article's front matter when you want to override the default behavior.

Commonly used parameters include:

• title: The name of the article.
• description: Text description used in HTML metadata.
• externalUrl: If provided, prevents a local content page from being generated and links directly to the third-party URL instead.
• featureimage: Link for the feature image.
• heroStyle: Controls the hero image display style. Valid options: basic, big, background, thumbAndBackground.
• series: An array of series the article belongs to.
• excludeFromSearch: Set to true to exclude the article from both the sitemap and the search index.

Blowfish 2.0 automatically resizes images used in Markdown content to optimize performance. It uses Hugo Pipes to generate multiple output sizes and serves them via the HTML srcset attribute.

To use this feature, simply use standard Markdown image syntax. The theme handles the resizing and generation of optimized files automatically. For more control, you can use the rewritten figure shortcode which also supports these resizing benefits.

<!-- Markdown: ![My image](image.jpg) -->
<img
  srcset="
    /image_320x0_resize_q75_box.jpg 320w,
    /image_635x0_resize_q75_box.jpg 635w,
    /image_1024x0_resize_q75_box.jpg 1024w"
  src="/image_635x0_resize_q75_box.jpg"
  alt="My image"
/>

If you prefer using git submodules to manage the theme, follow these steps.

Prerequisites:

• Git
• Hugo
• An existing Hugo project

Steps:

1. Initialize git in your project directory:

   git init

2. Add Blowfish as a submodule:

   git submodule add -b main https://github.com/nunocoracao/blowfish.git themes/blowfish

3. Configuration:
   • Delete the hugo.toml file generated by Hugo in your website root.
   • Copy the theme's *.toml configuration files into a config/_default/ folder. You can download these files from the latest release.

Blowfish Tools is a CLI tool (currently in beta) that automates the creation of a new Hugo project, installs the theme, and sets up configuration files.

To install the CLI globally using npm:

npm i -g blowfish-tools

Or run it directly using npx:

npx blowfish-tools

Usage:

• Run blowfish-tools to start an interactive setup process.
• Run blowfish-tools new <site-name> to create a new Hugo project and install the theme in one step.

npx blowfish-tools
# OR
npm i -g blowfish-tools
# THEN
blowfish-tools
# OR
blowfish-tools new mynewsite

Blowfish 2.0 uses Hugo Pipes to automatically scale Markdown images into different output sizes using the HTML srcset attribute. This optimizes file sizes for visitors without requiring manual changes to your Markdown syntax.

To use it, simply use standard Markdown image syntax: ![alt text](image.jpg)

The theme will automatically generate and serve optimized versions (e.g., image_320x0_resize_q75_box.jpg).

If you require more control, use the rewritten figure shortcode, which provides the same automatic resizing benefits.

<!-- Standard Markdown syntax is automatically resized -->
![Mi imagen](image.jpg)

<!-- The resulting HTML will look similar to this -->
<img
  srcset="
    /image_320x0_resize_q75_box.jpg 320w,
    /image_635x0_resize_q75_box.jpg 635w,
    /image_1024x0_resize_q75_box.jpg 1024w"
  src="/image_635x0_resize_q75_box.jpg"
  alt="Mi imagen"
/>

Use this method if you prefer managing the theme as a git submodule within your Hugo project.

Prerequisites:

• Git
• Hugo
• An existing Hugo project

Steps:

1. Initialize git in your project directory:

   git init

2. Add Blowfish as a submodule to the `themes/blowfish` directory:
   ```shell
git submodule add -b main https://github.com/nunocoracao/blowfish.git themes/blowfish

3. Remove the default hugo.toml generated by Hugo.
4. Copy the theme's configuration files (*.toml) to your config/_default/ directory. You can find these in the Hugo cache or download them here.

Once authors are defined in ./data/authors, you can assign them to specific articles using the authors front matter parameter. This allows you to list one or multiple authors for a single post.

This feature works independently of the default site author. You can control the visibility of the default author using the showAuthor parameter.

---
title: "Multi-author Post"
date: 2020-08-10
draft: false
description: "A post with multiple authors."
slug: "multi-author"
tags: ["authors", "config"]
showAuthor: true
authors:
  - "nunocoracao"
showAuthorsBadges: false 
---

To add additional authors beyond the default site author, create a new directory at ./data/authors. Inside this directory, add a .json file for each author. The filename (without the extension) serves as the unique key used to reference that author in your articles.

Each JSON file supports the following parameters:

• name: The author's display name.
• image: Path to the author's avatar image.
• bio: A short biography.
• social: An array of objects containing social media links. The key in each object (e.g., twitter, github) must match a supported theme icon.

{
    "name": "Nuno Coração",
    "image" : "img/nuno_avatar.jpg",
    "bio": "Theme Creator",
    "social": [
        { "linkedin": "https://linkedin.com/in/nunocoracao" },
        { "twitter": "https://twitter.com/twitter/nunocoracao" },
        { "github": "https://github.com/nunocoracao" }
    ]
}