179 lines
8.1 KiB
Markdown
179 lines
8.1 KiB
Markdown
# Blowfish
|
|
|
|
A clean, minimal theme for [Bludit](https://www.bludit.com) inspired by the
|
|
[Blowfish](https://blowfish.page/) 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
|
|
|
|
|
|
```
|
|
````
|
|
|
|
Supports swipe on touch devices.
|
|
|
|
## Callout boxes
|
|
|
|
```markdown
|
|
> [!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:
|
|
|
|
```markdown
|
|
> [!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](LICENSE)
|