Blowfish

https://github.com/Spleenftw/bludit-blowfish

https://github.com/nunocoracao/blowfish/blob/main/README.zh-cn.md

A clean, minimal theme for Bludit inspired by the
Blowfish Hugo theme.

Features

• Five-theme swatch picker — Light, Dark, Nord, Dracula, Catppuccin. Choice persists via localStorage + cookie (no flash on next load); falls back to OS preference.
• Monochrome base design — restrained grayscale palette with crisp Inter typography (self-hosted, no Google Fonts).
• Profile hero — circular avatar, site title, slogan and social links on the homepage.
• Sticky Table of Contents — articles with h2/h3/h4 headings get a left sidebar ToC that sticks while scrolling and highlights the active section. Layout switches to 3-column with a wider container. A floating button opens a drawer on mobile.
• Smart right sidebar — shows only About / Categories / Hit Counter on the homepage; full plugin set on article pages.
• Client-side search overlay — / key or navbar button; searches titles, descriptions and tags client-side.
• Keyboard shortcuts — / (search), g h (go home), t (back to top), Esc (close overlay).
• Randomized navigation — the Navigation/Pages plugin list is shuffled on every load.
• Reading time & dates shown on the post list and single posts.
• Post-list excerpts & thumbnails — the page description renders as a 2-line excerpt with the cover image as a right-side thumbnail; tags are capped at 5 with a +N badge.
• Older / newer post navigation — chronological links under every article, above the related posts.
• Social icons in the navbar and hero (SVG files in img/).
• Tags & categories rendered as pill badges.
• Image lightbox — clicking any article image opens it full-screen with a dark overlay and zoom hint.
• Image carousel — ```carousel fenced block, one image per line (markdown syntax or bare URL with optional | caption).
• Tabbed code blocks — ```tabs fenced block with [Tab Name] or @tab Name headers.
• Code block header bar — language label + copy-to-clipboard button on every code block.
• Callout/admonition boxes — > [!NOTE], > [!TIP], > [!WARNING], > [!DANGER], > [!IMPORTANT]; optionally collapsible with a custom title.
• Mermaid diagrams — ```mermaid fenced block. The library is self-hosted and loaded only on pages that contain a diagram; colours follow the active theme and re-render when it changes.
• Series navigation — posts tagged series-* display an ordered series box.
• SEO — Open Graph, Twitter Card, JSON-LD (WebSite, Article, BreadcrumbList, sameAs), canonical URL, theme-color meta, cover-image preload. Duplicate OG/Twitter/canonical tags emitted by Bludit plugins are stripped automatically.
• Accessibility — skip link, ARIA labels, :focus-visible, heading anchor links, print stylesheet.
• PWA — web app manifest included.
• CLS-free images — width/height are injected server-side into local-upload images (plus lazy-loading and async decode).
• View transitions — smooth cross-document fade on supporting browsers; respects prefers-reduced-motion.
• Fully responsive; no jQuery, no Bootstrap JS, no webfont requests.

Installation

1. Clone or copy this repository into your Bludit bl-themes/ directory:

   bl-themes/bludit-blowfish/

2. In the Bludit admin panel go to Settings → Themes and activate Blowfish.

3. Add your assets to img/:

   • Your avatar as spleenftw.jpeg — used in the homepage hero and the article sidebar card.
     To change the filename, update php/sidebar.php and php/home.php.

Layout

bludit-blowfish/
├── index.php          Main template (layout, sidebar logic, JS config)
├── metadata.json      Theme metadata
├── manifest.webmanifest
├── css/
│   ├── style.css      All styles (CSS custom properties, 5 themes)
│   └── hljs/          Syntax-highlighting palettes, one per theme
├── js/
│   ├── blowfish.js    Deferred JS bundle (ToC, lightbox, carousel, search, …)
│   ├── highlight.min.js  Self-hosted highlight.js
│   └── mermaid.min.js    Self-hosted mermaid, loaded only on pages with a diagram
├── php/
│   ├── head.php       <head>, fonts, favicon, anti-FOUC theme script
│   ├── navbar.php     Navbar, social icons, theme-picker dropdown
│   ├── home.php       Profile hero + post listing
│   ├── page.php       Single page/post
│   ├── sidebar.php    Right sidebar plugin container
│   ├── toc.php        Left ToC sidebar (article pages with headings)
│   ├── footer.php     Footer + search-index JSON
│   └── icons.php      Inline-SVG icon helper + shared PHP functions
├── img/               Social SVG icons + avatar
└── languages/         Translations (10 languages)

Themes

Each colour theme is a block of CSS custom properties. Light lives in :root; the others override it under [data-theme="dark"], [data-theme="nord"], [data-theme="dracula"] and [data-theme="catppuccin"].

The data-theme attribute is set on <html> before the first paint (in php/head.php) to avoid a flash. The navbar swatch picker updates it at runtime and persists the choice to localStorage and a cookie.

To add a new theme: add a variable block in css/style.css, register the theme name + background colour in index.php ($blowfishThemeBg), and add a swatch entry in php/navbar.php.

Table of Contents

When an article's rendered HTML contains any h2, h3 or h4 headings, the layout automatically switches from 2-column to 3-column:

[ Left ToC (col-md-3) ] [ Article (col-md-6) ] [ Right sidebar (col-md-3) ]

The sidebar ToC is hidden on mobile; a floating button opens a slide-up drawer instead. The container switches to .container-wide (1400 px max-width) and the navbar widens to match via body.has-toc .navbar .container.

Tabbed code blocks

Use a ```tabs fenced block. Delimit tabs with [Tab Name] (brackets) or @tab Tab Name (@ prefix):

```tabs
[pgs01]
root@pgs01:~# psql -c "SELECT …"

[pgs02]
root@pgs02:~# psql -c "SELECT …"
```

Image carousel

Use a ```carousel fenced block. Each non-empty line is one slide. Accepts standard markdown image syntax or a bare URL with an optional | caption:

```carousel
![Front panel](/bl-content/uploads/…/server1.png)
![Rear view](/bl-content/uploads/…/server2.png)
```

Supports swipe on touch devices.

Callout boxes

> [!NOTE]
> Useful information.

> [!WARNING]
> Something to watch out for.

Supported types: NOTE, TIP, WARNING, DANGER, IMPORTANT.

Text after the marker replaces the default title, and a + or - makes the box
collapsible — + starts open, - starts closed:

> [!TIP] A custom title, always open
> Body text.

> [!WARNING]+ Starts expanded
> The reader can fold this away.

> [!NOTE]- Starts collapsed
> Hidden until the reader expands it.

Collapsible callouts are built on <details>/<summary>, so keyboard and
screen-reader behaviour comes from the browser. Titles may contain formatting.

Note on existing content: a single-line > [!NOTE] Some text now renders
"Some text" as the title rather than the body. Put the marker on its own
line to keep the default label.

Mermaid diagrams

Use a ```mermaid fenced block:

```mermaid
graph LR
  A[Proxmox node] --> B{linstor}
  B --> C[(Ceph pool)]
```

Diagram colours are mapped from the active theme's CSS custom properties and
re-rendered when the swatch picker changes, so diagrams follow the site theme.

mermaid.min.js is self-hosted and fetched only on pages that actually
contain a diagram — other pages load nothing. It is a large file (~3.5 MB), so
serving the theme with gzip or brotli compression is recommended. A diagram that
fails to parse falls back to showing its source rather than an empty gap.

License

MIT

汉化简介：

• 五种主题色板选择器——浅色、深色、北欧色、德古拉色、猫咪主题。选择通过localStorage+ cookie 保存（下次加载时不闪烁）；否则将使用操作系统偏好设置。
• 单色基础设计——克制的灰度调色板，搭配清晰的 Inter 字体（自托管，不使用 Google Fonts）。
• 主页主图——圆形头像、网站标题、标语和社交链接。
• 固定目录——带有h2“/ h3/”h4标题的文章会在左侧边栏显示目录，滚动时目录始终固定，并高亮显示当前部分。布局切换为三栏，容器更宽。移动设备上，浮动按钮会打开抽屉式菜单。
• 首页仅显示“关于我们”、“分类”、“访问量”等智能右侧边栏；文章页面显示完整插件设置。
• 客户端搜索叠加层——/按键或导航栏按钮；在客户端搜索标题、描述和标签。
• 键盘快捷键—— /（搜索）、g h（返回主页）、t（返回顶部）、Esc（关闭叠加层）。
• 随机导航——每次加载时，导航/页面插件列表都会被打乱。
• 帖子列表和单个帖子上会显示阅读时间和日期。
• 文章列表摘要和缩略图— 页面描述以 2 行摘要的形式呈现，封面图片作为右侧缩略图；标签数量上限为 5 个，并带有+N徽章。
• 按时间顺序排列的文章导航——每篇文章下方、相关文章上方的链接。
• 导航栏和首页中的社交图标（SVG 文件img/）。
• 标签和类别以药丸徽章的形式呈现。
• 图片灯箱——点击任何文章图片即可全屏打开，并带有深色叠加层和缩放提示。
• 图片轮播图——```carousel围栏块，每行一张图片（markdown 语法或带可选参数的裸 URL | caption）。
• 带标签的代码块——```tabs带有标题[Tab Name]或@tab Name标头的围栏式代码块。
• 代码块标题栏——每个代码块上都有语言标签和复制到剪贴板按钮。
• 标注/提示框— > [!NOTE], > [!TIP], > [!WARNING], > [!DANGER], > [!IMPORTANT]; 可选择折叠并自定义标题。
• 美人鱼图表——```mermaid围栏式模块。该库自托管，仅在包含图表的页面上加载；颜色随当前主题变化而变化，并在主题更改时重新渲染。
• 系列导航——带有标签的文章series-*会显示一个有序的系列框。
• SEO ——Open Graph、Twitter Card、JSON-LD（WebSite、Article、BreadcrumbList、sameAs）、规范 URL、主题颜色元数据、封面图片预加载。Bludit 插件生成的重复 OG/Twitter/规范标签将被自动移除。
• 辅助功能——跳转链接、ARIA 标签:focus-visible、标题锚链接、打印样式表。
• PWA——包含Web应用程序清单。
• 无 CLS 图像— width/height在服务器端注入到本地上传图像中（加上延迟加载和异步解码）。
• 视图过渡— 在支持的浏览器上实现平滑的跨文档淡入淡出；遵循prefers-reduced-motion。
• 完全响应式设计；无需 jQuery、Bootstrap JS 或 Web 字体请求。

bludit-blowfish/
├—— index.php  主模板（布局、侧边栏逻辑、JS 配置）
└──   metadata.json  主题元数据
├── manifest. webmanifest
├── css/
│ ├—— style.css     所有样式（CSS 自定义属性，5 个主题）
│ └── hljs/  语法高亮调色板，每个主题一个
├── js/
│ ├—— blowfish.js 延期 JS 捆绑包（目录、lightbox、carousel、搜索等）
│ ├── highlight.min.js 自主持highlight.js
│ └── mermaid.min.js 自托管美人鱼，仅加载在带有图表的页面上
 ├── php/
│ ├── head.php，字体，favicon，反FOUC主题脚本
│ ├── navbar.php 导航栏、社交图标、主题选择下拉菜单
│ ├── home.php 个人资料英雄 + 帖子列表
│ ├── page.php 单页/帖子
│ ├── sidebar.php 右侧栏插件容器
│ ├── toc.php 左目录侧边栏（带标题的文章页）
│ ├── footer.php 页脚 + 搜索索引 JSON
│ └── icons.php 内联 SVG 图标助手 + 共享 PHP 函数
├── img/    社交 SVG 图标 + 头像
└── languages/   翻译（10种语言）

以上为官方MD简介与本人的翻译 ，目前项目仍在维护 仅仅一天就恰好更新到V1.8 匹配了大部分场景需求 目前比较满意