Arabesque for Zola

Introducing Arabesque for Zola

2026-10-20T00:00:00+00:00

Arabesque is the Arabesque Labs design system: tokens, CSS and a few small helpers, accessible and bidirectional from the start. This theme is the shortest way from it to a website.

What’s in it🔗

A range of templates for a Zola site: the home page with its hero, sections that list their pages, pages with “On this page” beside them, tags, an archive, search and a page for when something isn’t found. Each one is built from the system’s components, as their specs describe them, and nothing else.

Page templates 8

Components 19

Languages, to start 2

What it isn’t🔗

It isn’t a framework, and it doesn’t ask for one. The pages are plain HTML; a small script adds the pattern, copy buttons, and search. Without it, every page still reads and works.

Read the guide to install it, or start from its repository, which is this site.

Markdown, in the system's look

2026-10-12T00:00:00+00:00

Running text is set in the reading face, at the reading measure, with an em between blocks. This page has one of everything, so you can see how yours will look. Hover over a heading for its own link.

Text🔗

A paragraph with strong words, emphasis, both at once, inline code, a link to the guide, ~~a word struck out~~ and a footnote.¹ Smart punctuation turns “double” and ‘single’ quotes, – and — dashes, and three dots… into their proper forms.

A line can break without a new paragraph:
put a backslash at its end,
or two spaces.

A quotation has a rule at its start, and is muted. It’s for what someone else wrote.

It can run to more than one paragraph.

Inline HTML🔗

Markdown passes HTML through, for the few things it has no syntax for. Press Ctrl + K to search; highlight a phrase that matters; write H₂O and E = mc²; and spell out an RTL layout on hover.

Lists🔗

An unordered list
With a second item
- And one nested inside it
  - And one inside that
And a last one

An ordered list
Counts its items
- With a bulleted list inside an item
- That keeps its own markers
In the page’s digits

A list after a paragraph can start at any number:

This one starts at five
And counts on from there

A task that’s done
A task that isn’t

An item can hold more than one paragraph.

Indent the next one to line up with the item’s text, and it stays inside.
```
zola serve
```
Code, too, as above.

Images🔗

An image on its own line fills the measure, and keeps its corners as the system’s.

Code🔗

// The theme's script, in brief.
import { initToc } from "../js/toc.js";
const strings = JSON.parse(document.getElementById("zt-strings").textContent);
initToc();

1fn main() {
2    let greeting = "مرحبا";
3    println!("{greeting}, world");
4}

Tables🔗

Columns of figures are aligned as figures, and a column can be set to the start, the centre or the end with colons in the rule under the head.

Breakpoint	Width	Columns
Small	40rem	1
Medium	52rem	2
Large	64rem	3

A wide table scrolls on its own, never the page. (The figures are made up.)

Month	Posts	Words	Minutes	Images	Code	Tables	Notes	Quotes	Lists	Links	Tags	Languages
January	1	820	4	0	2	0	1	0	1	3	2	English
February	2	1,460	7	2	3	1	0	1	2	5	4	English
March	2	1,910	9	1	5	1	2	0	2	6	3	Both
April	3	2,730	13	4	6	2	3	1	3	8	6	Both

Headings🔗

A heading’s address comes from its words, or from an id you give it: this one is #headings-in-a-post.

A third-level heading🔗

A fourth-level heading🔗

Headings below the page’s title start at the second level; “On this page” lists the second-level ones.

Footnotes gather at the foot of the page, after a hairline.

Galleries, diagrams and embeds

2026-10-05T00:00:00+00:00

The theme’s first components write the design system’s own. These seven go further: they show what a post carries with it, break it into scenes, draw diagrams, and bring in things that live on other sites. Each is shown working here; the components page says how to write them.

Gallery🔗

A post that’s a folder, with its images beside its index.md, can show them all as a grid. Zola makes the thumbnails, so the page loads small files; each links to its image in full.

Separators🔗

A break between scenes, in one of fifteen styles. The pattern’s star is the theme’s own.

The default is three asterisks, the classic scene break of a novel.

An Arabic star, for an Arabic text, and a rule that fades at both ends.

Diagrams🔗

A Mermaid diagram is written as text and drawn in the browser, in the theme’s colours. Switch to dark, and it’s drawn again.

flowchart LR
  md[Markdown] --> zola((Zola))
  tpl[Templates] --> zola
  zola --> html[HTML]
  html --> browser[Browser]
  css[arabesque.css] --> browser
  js[theme.js] --> browser

Video🔗

From YouTube’s no-cookie domain, at 16:9, loaded only when it’s near the screen.

PDF🔗

In the page, with a link to download it for the browsers (most phones) that can’t show one.

Download the PDF: About this theme

Gist🔗

Instagram🔗

See this post on Instagram

Native support for RTL content

2026-09-30T00:00:00+00:00

A page in Arabic isn’t a page in English turned around. Some things mirror, and some never do; the theme follows the design system’s rules for both.

What mirrors🔗

The layout: the header’s title moves to the right, its tools to the left; “On this page” sits on the right; Previous is on the right and Next on the left. Arrows and chevrons point the way the text reads.

What doesn’t🔗

Numbers, code, the pattern and anything with a fixed direction of its own. A number inside an Arabic sentence is isolated, so its digits stay in order: the theme puts dates, counts and reading times in <bdi>.

The type🔗

Role	Latin	Arabic
Interface	Jost	IBM Plex Sans Arabic
Headings	Jost	Kufam
Reading	Newsreader	Amiri
Code	IBM Plex Mono	(system)

Each script falls through to its own face, character by character. Arabic is set a little larger, with more leading, never tracked, and never in capitals: it has none.

Read the same post in Arabic.

A page for your projects

2026-09-22T00:00:00+00:00

A list of links suits a guide, and a column of dated articles suits a blog. Neither suits the things you’ve made, where a reader wants to see them side by side and go straight to the one that looks interesting. So the theme has two more templates: projects.html for a section, and project.html for its pages. The Projects page uses them.

A card for each🔗

Each project is a card: its picture across the top, its title, the one sentence from its description, then its year and links to its site and its source. A source on GitHub gets GitHub’s mark. The whole card is a link to the project’s page, and its site and source are links of their own above it, so each goes where it says.

A project with no picture isn’t left blank. Its title’s first letter sits on the quiet pattern, in the display face: Latin or Arabic, whichever the title begins with.

Groups🔗

A section’s subsections follow its own projects, each under its title and description, with cards of their own. The demo keeps its smaller things under Experiments.

Its own page🔗

A project’s page is a page like any other, with breadcrumbs, its lede and the projects either side at its foot. It adds the year and links under the title, and the picture below them, at its own size, never stretched.

[extra]
image = "cover.jpg"
year = "2025"
website = "https://example.com"
source = "https://github.com/me/lantern"

Every key is optional. Writing in the guide has the rest.

Light, dark, and the reader's choice

2026-09-14T00:00:00+00:00

The theme follows the reader’s system by default: light, or dark when prefers-color-scheme says so. The button in the header cycles through three modes: as the system, light, and dark. Its icon shows the mode in use (a screen, a sun, a moon), and its name says what pressing it does: “Switch to dark theme”.

Remembered, without a flash🔗

The choice is kept in the browser; “as the system” keeps nothing. A small script in the head applies it before the first paint, so a dark page never flashes white, and the button’s icon is set by CSS, so it’s right before any script runs.

Every pair measured🔗

The design system computes the contrast of every text and interface colour against every background it sits on, in both themes, and the build fails if one falls below its minimum. The theme adds no colours of its own: everything is a token.

Forced colours

With Windows’ high contrast themes, the system hands its colours to the browser, and the pattern steps aside.

Why the hero draws itself once

2026-08-28T00:00:00+00:00

The pattern across the home page isn’t an image. It’s drawn when the page loads, by rule: the 4.8.8 tiling, two lines from each edge’s midpoint at the contact angle of 67.5°, meeting where the geometry puts them.

Once, and only once🔗

The hero may draw itself in, the way it’s constructed: the tiling appears as scaffolding, the strands grow outwards from the focal tile, then the scaffolding fades. It’s the one motion that plays on load, and it never plays for someone who has asked for reduced motion.

Turn it off with animate = false under [extra.home], or the whole pattern with pattern = false.

Pagination, in words

2026-08-10T00:00:00+00:00

This blog shows five posts at a time, so this one is on its second page: the pagination at the foot of the list is working.

It follows the design system’s spec: Previous and Next in words, never icons alone; the first, the last and the current page with one each side; and which of how many above the list, not in the pagination.