Changelog
Updates, improvements and changes happening to Kaamiki.
Loads through Sphinx alone
The biggest release yet. Kaamiki loads through Sphinx natively.
- Added
A
walkthroughdirective, which scrolls a reader through a snippet a line at a time, with the values it held at each one written beside the code.An
attemptsdirective, which shows the versions a piece of code went through on its way to what it is now, the lines on their way out going red and the new ones coming in green.A
releasedirective, which writes a changelog entry like the ones on this page, with its date and version beside it.buttontakes:fa-icon-position: afterto put its icon after the label, rather than before it.A dropdown taller than the screen folds down to about a screenful, with a Show more button under it. While one is unfolded, Show less waits at the bottom of the screen, so folding it back never means scrolling all the way up.
The build writes
sitemap.xmland arobots.txtpointing at it, unlessshow_sitemapis off.A site without a
fa_kitgets Font Awesome Free, so its icons still draw.buttontakes a colour for its:scheme:,red,yellow,blueorgreen: the label and a faint outline in that colour, the outline filling in on hover.A
km-radius-normal-bgclass sets a block on the code background, with rounded corners, the width of the text.licensenames the content's licence in the footer, with a link when given one:{"name": "CC BY 4.0", "url": "https://..."}.show_kaamiki_themeadds a line naming the theme to the footer, the wayhtml_show_sphinxnames Sphinx.buttontakes:new-tab:,:no-new-tab:,:rel:,:title:,:download:and:class:.button_schemeandbutton_icon_positionset the ones a button does not say andbutton_coloursnames colours for:scheme:, like{"purple": "#7c3aed"}.authortakes:avatar-size:,:interval:,:hide-reading-time:and:hide-copy-url:, which hide what the byline shows without them.releasetakes:date:,:url:and:article-label:.release_version_fmtsays how a version spells its date andrelease_kindsgives a group of its own a colour.videotakes:sources:,:poster:,:preload:,:loop:,:muted:,:hide-controls:and:track:.youtubetakes:endat:,:loop:,:muted:,:hide-controls:,:privacy:,:language:,:ratio:and:click-to-load:, which shows the video's picture and loads the player once it is clicked.youtube_privacy,youtube_allowandyoutube_referrer_policyset the rest for the site.embed_iframe_hostsnames the hosts an<iframe>may come from andembed_css,embed_jsandembed_js_loadingload files on every page with an embed.thumbnailtakes:grayscale:.repositorytakes:hide-stars:and:hide-forks:.An option says what the author wants by being there. A bare
:grayscale:or:new-tab:turns on what is off without it, and:hide-*:or:no-*:turns off what is on without it. No option takestrueorfalse.show_page_last_updatedputs the day a page was last updated in the feedback box. It is on once feedback is, and a page turns it off with:km-show-page-last-updated: false.A setting the theme cannot use stops the build with Python's own error, rather than being worked around. A few settings take only certain words or numbers (
fa_style,embed_js_loading,button_icon_position,logo_size,show_more_afterandwords_per_minute), and the build says which. The warnings left arekaamiki.pages,kaamiki.embedandkaamiki.walkthroughforsuppress_warnings.The paths in
authorandvideocount from the top of the site,_static/cover.pngor/_static/cover.png, so they reach the same file from every page.:km-fb-subject:sets the feedback mail's subject for a page.sharpie_colour,underline_colour,underline_width,underline_wobbleandrole_coloursset what thesharpieandunderlineroles draw, andunderlinetakes its width and wobble after the colour,<red; width=3; wobble=0>.walkthrough_limit,walkthrough_timeout,walkthrough_memory,walkthrough_output_limit,walkthrough_budget,walkthrough_python,walkthrough_pythonpath,walkthrough_eventsandwalkthrough_comprehensionssay what a snippet may run with. A snippet's own:limit:and:timeout:can lower them, never go past them.walkthrough_cachekeeps a trace next to the doctrees and uses it again while the snippet, its options, the interpreter and the installed packages stay the same.last_updated_on_fmtspells every date the theme shows, afterhtml_last_updated_fmt.internal_hostsnames hosts that count as the site,logo_sizesizes the logo andwords_per_minuteand thetoctree_*settings replace what the templates had written in.A page in no toctree, an orphan, names its own previous and next pages with
:km-pg-prev:and:km-pg-next:. Sphinx works those out from the toctree, so an orphan got no buttons at the bottom. An article areleaselinks to goes back to the release's page on its own.feedbacksets the feedback box's defaults and a page turns anyshow_*setting on or off for itself with a field,:km-show-feedback: false. The page's field wins.Everything the theme writes reads in the site's
language. Its own words come in a catalogue that joins Sphinx's, so a site's own translation of one still wins andgettextnow collects a directive's text, a release's title and a page's:km-pg-*:and:km-fb-*:words.
- Changed
Every link that opens in a new tab says
rel="noopener noreferrer", the footer's too, and the footer's Kaamiki link followsinternal_hostslike the rest.show_last_updated_onisshow_page_last_updatedandshow_show_moreisshow_more. The old names are no longer read.The drawer lists what
toctree_titles_onlysays, as the header does, rather than the reverse.open_graph: {"enable": False}keeps the page's plain<meta name="description">.release_kindsnames groups the theme does not colour itself, and says so when it is givenaddedor another it does.:km-fb-fa-icon:is:km-fb-icon:, asfeedbackcalls it.embed_iframe_hostsletsabout:blankthrough.A feedback box with nowhere to send the reader is not drawn.
Copied!!isCopied!. The walkthrough'sreturns:anderror:marks, the repository's counts and an attempt'sBrokeorWorkedare words a catalogue can translate.header_buttons,sidebar_buttons,licenseandfeedbacktakeurlwhere some of them tooklink, so every setting that names an address names it the same way. Change yours, as the old name is no longer read.markis nowsharpie, as is its class and the--sharpie-colorit draws with.The thumbnail card is drawn in colour, unless
:grayscale:asks for grey. It used to be grey until hovered.sphinx-design's success colour is Kaamiki's green, with dark text on it, so a
bdg-successbadge keeps 4.5:1.A setting that is read while pages are read,
button_schemeandwalkthrough_limitamong them, sends every page back through reading when it changes. Sphinx only does that for settings it knows about, so the old buttons stayed in the saved pages until a build with-E.What a page writes in
authorwins overhtml_context, which used to be poured over the options.A date may be written
2026-10-05as well as5 October 2026.A version that does not read as a date,
v1.2.0say, no longer failsrelease. It shows without a date, unless:date:gives one.The theme loads through Sphinx alone. A site that runs builders other than HTML lists
"kaamiki"inextensions.A page shows as soon as the document is ready, so a stalled Font Awesome kit, a slow image or a video cannot keep it blank.
Every class the theme owns starts with
km-and a page's own fields are:km-pg-*:and:km-fb-*:.A click anywhere on a heading copies its link and brings the heading to the top, with the same "Copied!" the byline shows. The link icon is gone, so a heading on a phone no longer breaks onto another line for it.
With
add_copy_to_headerlinkson, a heading under acontentstable no longer links back to it, so the click copies instead.Numbered and bullet lists draw each marker in a ring, with a line running from one ring to the next. A list written in raw HTML keeps its own look.
Secondary buttons on a card or a
km-radius-normal-bgblock take the muted fill, so they still stand out in the dark.The header is a little taller and its tint and blur fade out only below its links, so the page scrolls under it without a line and the links stay clear of it.
The footer keeps to the 800px column. Its lines wrap on a wide screen rather than squeezing up and stack on a phone.
Buttons fade between their colours on hover rather than switching at once.
Links within a page, Show less and the back to top button glide with the browser's own smooth scrolling and give way the moment you scroll.
The stylesheets go through
lightningcssas the build finishes, so nesting reaches Safari 15 as rules it can read.sphinx_design's stylesheet and tab script only go to pages that use them, which saves the rest about 50 KB.Links in prose carry a faint underline, which darkens on hover.
Reloading a folded page finds it as it was left: opened if it had been and where it had been read to.
A site's
templates_pathcan replaceauthor.html.jinjaand the rest, the way it replaceslayout.html.The text in
button,video,youtube,thumbnailandauthoris read as rST, so a substitution or a role in a label or a caption shows the way it would in a paragraph.Dates read in the site's
languageand the same way everywhere,05 October 2026in English, under a page and beside a release.Dropdowns open and close smoothly however long they are and the plus turns back the moment one starts to close.
The header's menus and a newly picked tab fade in rather than popping up and Show more glides down with the page it unfolds.
Tab titles sit on one line in a rounded strip, which scrolls sideways on a phone rather than wrapping and the picked tab's fill slides across to it.
A card's link is a round button with an arrow. Its text is left for screen readers.
The 404 page is a plain one, a line and a button home. A
404.htmlin the site'stemplates_pathreplaces it.The title badge only shows when
fa_iconsnames one.A release's groups keep their colours when their headings are written in the site's
language.A page fades in block by block a little more slowly, so each part can be seen arriving.
The stylesheets are 814 lines lighter: what was left of the Tailwind build they started as, rules for markup the theme no longer writes and declarations a later rule always overrode.
Borders are gone, except on the byline, the release timeline, the phone menu's edge, inline code, the header's menus, table rows and the strip of tab titles. Everything else stands apart by its fill, lighter in the dark, so nothing sinks into an OLED screen's black.
Text, code and tables sit in an 800px column, while pictures and videos keep the wider 861px.
- Fixed
In Firefox, a jump past a walkthrough lands where it was asked to.
Tabs work from the keyboard.
The copy buttons work on a plain HTTP address, where the clipboard API is missing.
A
mailto:link no longer opens an empty tab.A
thumbnailwith both:title:and:channel:keeps them, rather than having YouTube's written over them.A heading's "Copied!" fades out where it showed, rather than jumping aside as it goes.
Back after a link within the page returns to where you clicked it.
Tabbing back up a page no longer leaves the focused link hidden under the header.
On a phone, tapping the page you are on in the menu closes the menu and goes to the top.
The back to top button jumps rather than glides when the system asks for less motion.
Admonition text keeps 4.5:1 against its box.
On a wide screen, the sidebar and a release's date stay clear of the header instead of slipping under it as the page scrolls.
A lexer error in a code block no longer gets a red box around it.
A code block's "Copied!" shows in green again. Kaamiki's grey had covered it.
A centred heading sits in the middle, not 2px to the left of it.
A hand-drawn underline comes out the same wherever the site is built. It used to depend on the folder the build ran in.
- Removed
Light mode. Kaamiki is dark only:
colour_mode,show_colour_modes, the switch in the footer, its:km-show-colour-modes:field, thedark_modeandlight_modeicons and the light colours are gone.dark_logoislogonow,light_logois gone and a page prints as it shows.thumbnail_grayscale. Write:grayscale:on the thumbnails that need it.:same-tab:,:controls:,:mute:and thefalsethat:privacy:,:comprehensions:,:reading-time:and:copy-url:once took.base.js, a minified bundle of Alpine and clipboard.js with no source behind it.theme.jsdoes its work now.The
picturedirective, which no page used any more.--km-scroll-minand--km-scroll-max, which timed the script the browser's own scrolling replaced.The frame and dashed rules around the content and the line under the header once a page has scrolled.
youtube's:modestbranding:and:playsinline:, which did nothing and themodestbrandingparameter YouTube stopped reading in 2023.The undocumented
km-no-zoomclass. A picture zooms only when it asks to, withkm-zoom.A colour picked under the September release is no longer read back. That release stored one for every visitor, chosen or not.
The footer's own "Content licensed under CC BY 4.0", which every site using the theme showed.
licenseputs one back.The
permalinkicon infa_icons, with the icon it named.The cal.com loader. A site booking calls through cal.com loads its own script, through
html_js_files.
Previews, folds and a 404 of its own
Pages describe themselves to social sites, long pages fold up and the theme writes its own 404.
- Added
Open Graph and Twitter metadata, worked out from the page itself. A page's own fields win.
A page longer than
show_more_afterminutes folds down to one screenful, with a Show more button under it.fa_kitnames the Font Awesome kit. It used to be hardcoded, so every site using the theme loaded my kit off my quota.The theme writes a
404.htmlthe site's host can serve, undershow_404.
- Changed
Every directive renders with escaping on, so a title carrying an
&or a<no longer breaks the page.The reading time is worked out as the page is built, rather than counted again in the browser.
The stylesheets load side by side in a stated order, rather than one
@importafter another.
- Removed
sphinxext-opengraph, which pulledmatplotlibin purely to draw social cards.The "On this page" rail.
iframe is now embed
- Changed
The
iframedirective is nowembed, since it covers inline content and HTML fragments as well as iframes. Its argument isiframeor the fragment's path, replacing:file:.An option's value may run over several indented lines.
Backgrounds behind the byline
- Added
authortakes:background:, one or more pictures that fade through behind the page's title.
A byline that links anywhere
- Changed
The byline's link is no longer tied to GitHub, so it can point at any profile.
No more timestamps
- Removed
author's:timestamp:option, which nothing ever rendered.
Kaamiki gets its name
- Changed
The theme has a name of its own, Kaamiki.
- Removed
Support for Algolia's DocSearch.
A leaner byline
- Removed
The email, bio and LinkedIn details from
author.
Templates in a folder of their own
- Changed
The theme registers from
base/templatesrather thanbase, which keeps the templates apart from the styling.The directives are called extensions inside the theme, which is the more accurate name for them.
Kaamiki's overriding stylesheets load at priority 800 rather than 900.
Settings through html_context
- Changed
Everything the templates read comes through
html_contextand Kaamiki's options are Sphinx's ownhtml_theme_options.The byline's details are optional and fall back to the project's in
conf.py.
- Removed
The byline's custom subject header, in favour of the page title.
- Deprecated
website_optionsandregister_website_options, in favour ofhtml_context.The
taggeddirective, which no page put to any real use.
Thumbnails without scraping
- Changed
thumbnailreads a video's details from YouTube's oEmbed endpoint.
- Removed
Scraping YouTube with
requestsand BeautifulSoup, which broke whenever YouTube changed its markup and made builds very slow.
Face tags
- Added
A
taggeddirective, which lays clickable face tags over an image.
- Changed
The "Last updated" date sits above the footer.
A look for sphinx-design
- Added
Stylesheets that restyle
sphinx_design's components to match the theme andsphinx_docsearch's too, until DocSearch went in February 2026.
The first release
- Added
Support for
sphinxext-opengraph, out of the box.