https://github.com/micahkepe/radion
A sleek, modern blog theme. 📡
https://github.com/micahkepe/radion
blog blog-theme giscus markdown static-site-generator zola-theme
Last synced: about 1 month ago
JSON representation
A sleek, modern blog theme. 📡
- Host: GitHub
- URL: https://github.com/micahkepe/radion
- Owner: micahkepe
- License: mit
- Created: 2024-11-05T18:21:27.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-01-26T20:06:26.000Z (about 2 months ago)
- Last Synced: 2026-01-27T07:36:00.844Z (about 2 months ago)
- Topics: blog, blog-theme, giscus, markdown, static-site-generator, zola-theme
- Language: SCSS
- Homepage: https://micahkepe.com/radion
- Size: 49.5 MB
- Stars: 41
- Watchers: 1
- Forks: 16
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# radion
A sleek, modern blog theme for [Zola](https://www.getzola.org/). See the live
site demo [here](https://micahkepe.com/radion/).
> **radion**
> noun
>
> 1. (_physics_) A scalar field in higher-dimensional spacetimes
Dark theme
Light theme
## Features
- [x] Code Snippet Clipboards
- [x] Line(s)-specific highlighting
- [x] Latex Support
- [x] Light/Dark mode support
- [x] Search functionality
- [x] Table of Contents option
- [x] Footnote support
- [x] Built-in comments option (Giscus)
- [x] Open Graph cover image selection
## Contents and Configuration Guide
- [Installation](#installation)
- [Options](#options)
- [Top\-menu](#top-menu)
- [Title](#title)
- [Author Attribution](#author-attribution)
- [Defining a Global Default Author in config\.toml](#defining-a-global-default-author-in-configtoml)
- [Defining Author(s) Per\-Page](#defining-authors-per-page)
- [Favicon](#favicon)
- [GitHub](#github)
- [Fediverse and Mastodon](#fediverse-and-mastodon)
- [Code Snippets](#code-snippets)
- [Syntax Highlighting:](#syntax-highlighting)
- [Enhanced Codeblocks (Clipboard Support and Language Tags)](#enhanced-codeblocks-clipboard-support-and-language-tags)
- [LaTex Support](#latex-support)
- [Searchbar](#searchbar)
- [Light and Dark Modes](#light-and-dark-modes)
- [Table of Contents](#table-of-contents)
- [Comments](#comments)
- [Post Revision History](#post-revision-history)
- [Set Post Open Graph Image (Cover Image)](#set-post-open-graph-image-cover-image)
- [Custom Fonts](#custom-fonts)
- [Font Weights by Provider](#font-weights-by-provider)
- [Examples](#examples)
- [Acknowledgements](#acknowledgements)
## Installation
> [!IMPORTANT]
> **Requires Zola >= 0.22.** For older Zola versions (0.20–0.21), use
> [v1.0.0](https://github.com/micahkepe/radion/releases/tag/v1.0.0).
First download this theme to your `themes` directory:
```bash
cd themes
git clone https://github.com/micahkepe/radion
```
and then enable it in your `config.toml`:
```toml
theme = "radion"
```
This theme requires your index section (`content/_index.md`) to be paginated to
work:
```toml
paginate_by = 5
```
The posts should therefore be in directly under the `content` folder.
The theme requires tags and categories taxonomies to be enabled in your
`config.toml`:
```toml
taxonomies = [
# You can enable/disable RSS
{ name = "categories", feed = true },
{ name = "tags", feed = true },
]
```
If you want to paginate taxonomies pages, you will need to overwrite the
templates as it only works for non-paginated taxonomies by default.
---
## Options
### Top-menu
Set a field in `extra` with a key of `radion_menu`:
```toml
radion_menu = [
{ url = "$BASE_URL", name = "Home" },
{ url = "$BASE_URL/categories", name = "Categories" },
{ url = "$BASE_URL/tags", name = "Tags" },
{ url = "https://google.com", name = "Google" },
]
```
If you put `$BASE_URL` in a url, it will automatically be replaced by the actual
site URL.
### Title
The site title is shown on the homepage. As it might be different from the
`` element that the `title` field in the config represents, you can set
the `radion_title` instead.
### Author Attribution
You may define the author(s) of a page in either the root `config.toml` file, or
on a per-page basis in the page's frontmatter.
The order of precedence for determining the author shown in a page’s footer is:
1. `page.extra.author` (highest precedence)
2. `page.authors`
3. `config.author` (lowest precedence, default)
#### Defining a Global Default Author in `config.toml`
In `config.toml`:
```toml
author = "John Smith"
```
#### Defining Author(s) Per-Page
At the top of a page in its frontmatter (wrap this in `+++`):
1. Define a single author for the page:
```toml
title = "..."
date = 1970-01-01
[extra]
author = "John Smith"
```
Alternatively, you can define the `page.authors` variable with a single entry:
```toml
title = "..."
date = 1970-01-01
authors = ["John Smith"]
```
2. Define multiple authors for a page:
```toml
title = "..."
date = 1970-01-01
authors = ["John Smith", "Joe Schmoe", "Jane Doe"]
```
> [!NOTE]
> Do not define both `extra.author` and `authors` in the same page unless you
> want `extra.author` to take precedence.
### Favicon
To change the default favicon:
1. Create your own favicon folder with the following site:
[RealFaviconGenerator](https://realfavicongenerator.net/)
- Set the 'Favicon path' option to `/icons/favicon/`
2. Unzip the created folder
3. Create a `static/icons/` directory if it does not already exist
4. Place the unzipped `favicon/` directory in `static/icons/`.
By default, favicons are enabled, however, if for some reason you would like to
disable favicons, set the following in your `config.toml`:
```toml
[extra]
favicon = false
```
### GitHub
To enable a GitHub reference link in the header, set the following in your
`config.toml`:
```toml
[extra]
github = "https://github.com/your-github-link"
```
### Fediverse and Mastodon
In your `config.toml` you can set options related to the Fediverse and
explicitly Mastodon.
To enable author attribution, set the `extra.fediverse.creator` option to your
account address. To enable website verification, set the
`extra.fediverse.rel_me` option to a link to your profile.
Set the `extra.mastodon` field to a link to your Mastodon account to show a
Mastodon logo with this link.
```toml
[extra]
fediverse.creator = "@username@my.instance.example.com"
fediverse.rel_me = "https://my.instance.example.com/@username"
mastodon = "https://my.instance.example.com/@username"
```
### Code Snippets
#### Syntax Highlighting:
This theme uses [giallo](https://github.com/getzola/giallo) for **class-based
syntax highlighting**, which was introduced in Zola 0.22 as a replacement for
[syntect](https://github.com/trishume/syntect).
In your `config.toml`:
```toml
[markdown.highlighting]
style = "class"
dark_theme = "material-theme-palenight"
light_theme = "everforest-light"
```
The above configuration will use the `material-theme-palenight` theme for dark
mode and the `gruvbox-dark-medium` theme for light mode. Zola will automatically
generate `giallo-dark.css` and `giallo-light.css` in the build output.
##### Choosing Themes
1. Browse available themes in the [giallo
README](https://github.com/getzola/giallo) or preview them at
[textmate-grammars-themes.netlify.app](https://textmate-grammars-themes.netlify.app/)
2. Update `dark_theme` and `light_theme` with your preferred themes
3. Run `zola serve` or `zola build` — the CSS files will be regenerated
automatically
##### Migration from v1.0.0 (syntect)
If upgrading from [v1.0.0](https://github.com/micahkepe/radion/releases/tag/v1.0.0)
or earlier (Zola <0.22):
1. Replace the old `[markdown]` highlighting config:
```diff
- [markdown]
- highlight_code = true
- highlight_theme = "css"
- highlight_themes_css = [
- { theme = "one-dark", filename = "syntax/syntax-theme-dark.css" },
- { theme = "gruvbox-dark", filename = "syntax/syntax-theme-light.css" },
- ]
+ [markdown.highlighting]
+ style = "class"
+ dark_theme = "one-dark-pro"
+ light_theme = "everforest-light"
```
2. Delete the `static/syntax/` directory (old syntect CSS files)
3. Run `zola build` to generate the new giallo CSS files
#### Enhanced Codeblocks (Clipboard Support and Language Tags)
```toml
[extra]
codeblock = true
```
> [!NOTE]
> Ligatures are disabled by default as defined in the
> [\_theme.scss](./sass/_theme.scss) file.
### LaTex Support
To enable LaTeX support with MathJax, set the following in your `config.toml`:
```toml
[extra]
latex = true
```
### Searchbar
To enable a searchbar at the top of the page navigation, set the following in
your `config.toml`:
```toml
build_search_index = true
[search]
index_format = "elasticlunr_json"
[extra]
enable_search = true
```
### Light and Dark Modes
To set the color theme of the site, set the following in your `config.toml`:
```toml
[extra]
theme = "toggle" # options: {light, dark, auto, toggle}
```
There are four options for the `theme` field:
- `light`: Always light mode
- `dark`: Always dark mode
- `auto`: Automatically switch between light and dark mode based on the user's
system preferences
- `toggle`: Allow the user to toggle between light and dark mode
### Table of Contents
To enable a table of contents on a page, add the following to the front matter
of the page:
```toml
[extra]
toc = true
```
### Comments
> [!NOTE]
> Giscus comments assumes that you are hosting the blog site via GitHub Pages
> and thus have access to GitHub Discussions.
First, follow the instructions at [giscus.app](https://giscus.app/).
This includes installing the Giscus app and enabling discussions on the
GitHub repository that you host the website code. Additionally, fill in the
repository path in the prompt. Then, from the generated script, fill in the
corresponding values in the `config.toml`:
```toml
[extra]
comments = true # {true, false}; sets global enabling of comments by default
giscus_repo = "FILL ME IN"
giscus_repo_id = "FILL ME IN"
giscus_data_category_id = "FILL ME IN"
# giscus_data_category = "General" # Default to "General"
```
Comments can be enabled or disabled on a per page basis by editing the page's
front matter. For example, to disable comments on a specific post:
```toml
[extra]
comments = false
```
The `config.toml` value for `comments` takes precedence and priority. For
example, if you globally disable comments in your `config.toml` by setting
`comments = false`, then trying to enabling comments through a page's front
matter will have no effect.
### Post Revision History
To enable revision history links that allow readers to view the commit history
for individual posts, configure the following in your `config.toml`:
```toml
[extra]
# Enable revision history globally
revision_history = true
# Your blog's GitHub repository URL
blog_github_repo_url = "https://github.com/username/repository-name"
```
Revision history can be enabled or disabled on a per-page basis by adding the
following to a page's front matter:
```toml
[extra]
revision_history = true # or false to disable for this page
```
When enabled, a "(revision history)" link will appear in the page footer that
links directly to the GitHub commit history for that specific content file,
allowing readers to see how the post has evolved over time.
### Set Post Open Graph Image (Cover Image)
[Open Graph](https://ogp.me/) is a standard for embedding rich previews of
content on the Internet. It is used by social media platforms like Facebook,
Twitter, and LinkedIn to display a preview of a page when a user shares the
page on their social media network.
For example, to set the Open Graph image for a post `my-post` to be the page
asset `cover.png`, add the following to the front matter of the post:
1. Make sure the image is located in the page's content directory (i.e.
`content/my-post/`. For example:
```
content/
└── my-post/
├── index.md
├── cover.png # Your cover image
└── assets/
└── other-image.jpg
```
or
```
content/
└── my-post/
├── index.md
└── assets/
├── other-image.jpg
└── cover.png # Your cover image
```
2. Add the following to the front matter of the post:
```toml
[extra]
cover_image = "cover.png"
```
> [!NOTE]
> The image must be located within the page's content directory and
> `cover_image` expects just the filename of the image (e.g., `"cover.png"`, not
> a path like `"assets/cover.png"`). The first filename match will be used.
### Custom Fonts
Currently three font CDN sites are supported:
1. [Google Font (`"googlefont"`)](https://fonts.google.com/): Fonts from `fonts.google.com`
2. [Fontsource (`"fontsource"`)](https://fontsource.org/): Self-hosted fonts from `fontsource.org`. Uses WOFF2 files.
3. [ZeoSeven Font (`"zeoseven"`)](https://fonts.zeoseven.com/): Fonts from
`fonts.zeoseven.com`. Requires a `font_id` for URL construction.
To configure, add entries under `[extra]` in your `config.toml`:
| Option | Type | Default | Description |
| --------------- | ------ | ------------------ | -------------------------------------------------------------------------- |
| `font_cdn` | String | `"googlefont"` | Font provider: `"googlefont"`, `"fontsource"`, `"zeoseven"`, or `"custom"` |
| `font_name` | String | `"JetBrains Mono"` | Font family name (e.g., `"Inter"`, `"Roboto"`) |
| `font_weights` | Array | (_See below_) | Weights to load (provider-specific format) |
| `font_display` | String | `"swap"` | CSS `font-display` value: `"swap"`, `"block"`, `"auto"`, etc. |
| `font_id` | Number | _None_ | **ZeoSeven only**: Numeric ID from font URL |
| `font_css_urls` | Array | _None_ | **Custom only**: Array of CSS URLs for font definitions |
#### Font Weights by Provider
| Provider | Format | Example |
| ------------ | ---------------- | ------------ |
| Google Fonts | Array of numbers | `[400, 700]` |
| Fontsource | Array of strings | `["main"]` |
| ZeoSeven | Array of numbers | `[400, 700]` |
#### Examples
```toml
# Google Fonts
[extra]
font_cdn = "googlefont"
font_name = "Inter"
font_weights = [300, 400, 500, 700]
font_display = "swap"
# Fontsource
[extra]
font_cdn = "fontsource"
font_name = "JetBrains Mono"
font_weights = ["main"]
# ZeoSeven
[extra]
font_cdn = "zeoseven"
font_name = "Custom Font"
font_id = 443
font_weights = [400, 700]
# Custom CSS
[extra]
font_cdn = "custom"
font_name = "My Custom Font"
font_css_urls = [
"https://example.com/fonts/custom-font.css",
"https://cdn.example.com/typography.css"
]
```
---
## Acknowledgements
Lots of inspiration and code snippets taken from these awesome Zola themes:
- [`after-dark`](https://github.com/getzola/after-dark) by
[Vincent Prouillet](https://www.vincentprouillet.com/)
- [`apollo`](https://github.com/not-matthias/apollo/tree/main) by
[not-matthias](https://github.com/not-matthias)
- [`redux`](https://github.com/SeniorMars/redux) by
[SeniorMars](https://github.com/SeniorMars).