Scribble themes🔗ℹ

1 How it works🔗ℹ

A theme is a CSS file (and optionally additional CSS files it references via @import directives). 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. When you supply your main CSS file, any additional CSS files referenced via @import directives (one level deep) are automatically discovered and included.

2 Installation🔗ℹ

Install this package from the command line:

You can also install it from the GitHub repository if you prefer.

3 Setting Up Your Theme🔗ℹ

A theme is simply a CSS file (and any additional CSS files it references via @import). You can create and store your theme’s CSS files anywhere you like—typically in the same directory as your Scribble source files, or in a project subdirectory.

To get started, you can use this package’s command-line utility to generate a CSS file containing the default styles from scribble/manual:

This gives you a starting point that you can customize.

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)

(theme/provide-doc "my-package.scrbl" "my-theme.css")

This new file acts like a custom overlay over your original Scribble doc. The first argument is the path to your original Scribble source file, and the second is the path to your main CSS file. If the CSS path is relative, it’s resolved relative to this themed file’s location.

You can render this file with scribble like so:

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

5 Reference🔗ℹ

Dynamically requires the doc value from scrbl-filename, replaces its default CSS with the CSS specified by css-path, and provides the updated doc.

The scrbl-filename should be a module path (typically a string naming a ".scrbl" file).

The css-path can be either an absolute path or a relative path. If relative, it is resolved relative to the location of the file containing the theme/provide-doc call.

Any additional CSS files referenced via @import directives in the main CSS file (one level deep) are automatically discovered and included in the output.

This macro expands to a call to scribble/manual-custom-css wrapped in a provide that exports the doc binding.