Scribble themes🔗

1 How it works🔗

A theme is a set of one or more CSS files. Theming, for our purposes, involves substituting your own CSS file(s) for the ones supplied by scribble/manual, and doing so in a way that does not affect the output when rendered using “normal” methods like raco setup.

By default, documents written in #lang scribble/manual that are rendered to HTML link out to three files stored in the scribble collection: "manual-style.css" (which in turn brings in "manual-fonts.css" via a CSS @import declaration), and "manual-racket.css". This is all documented in Manual Rendering Style.

It’s possible to overrride "manual-style.css" by adding a #:style argument to title inside your Scribble doc; but this would affect the styling of your document every time it is rendered, which you might not want. Also, scribble/manual links "manual-racket.css" as a css-style-addition after your code runs, so there’s no way to add code to your document that can suppress that file from being included.

This module makes it easy to create a separate “themed” version of your document that imports its doc value (provided by all Scribble modules), strips out the default CSS and adds in your own. The normal/original document will still render normally, but you can also render the themed version for customized output.

2 Installation🔗

I recommend to install this package by forking/cloning its GitHub repository.

When you have a local copy of it, install it as a “linked” package:

3 Setting Up Your Theme🔗

Assuming you’ve installed the package from a local/linked folder on your computer, you can simply edit the base theme supplied with this package.

Edit the "manual-my-style.css" and "manual-my-fonts.css" files in this repo’s main folder to customize your theme.

4 Rendering HTML🔗

In the same folder as your Scribble sources, create a new file:

"my-themed-scribblings.scrbl"

#lang racket/base

(require scribble-theme)

(customize+provide-doc "my-package.scrbl" 'my-theme)

This new file acts like a custom overlay over your original Scribble doc. You can render this file with scribble like so:

This will place the output in the "doc/" subfolder with "index.html" as the main HTML file.

5 Adding Themes🔗

The default approach in this package is to set up one theme, housed within this package. That way you can reuse the theme across multiple projects and update it for all of them by editing one set of files.

But you can have more than one theme. You can do this either by adding more themes to your copy of this package, or by supplying themes stored within your own package.

Whichever method you choose, you’ll first need to create additional CSS files for your theme. You can get started quickly by copying the default styles for scribble/manual into a single new CSS file by running this command from this package’s main folder:

6 Reference🔗

In addition to the bindings below, this module also re-exports html-defaults from scribble/html-properties.