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. Your CSS files are copied into the output under content-hashed names, such as "my-theme-3f2a9c1b.css", so browsers and CDNs fetch a fresh copy whenever the CSS changes (see css->html-defaults).

5 Adding a site navigation bar🔗ℹ

Themed docs published on your own website usually need a way back to the rest of that site. Pass a list of navigation items to theme/provide-doc with the #:nav keyword, and a bar of links is inserted at the top of every HTML page:

"my-themed-scribblings.scrbl"

#lang racket/base

(require scribble-theme)

(define site-nav

(list (cons "My Site" "https://example.com/")

(cons "Projects" "https://example.com/projects.html")

(cons "Other docs"

(list (cons "Guide" "https://example.com/guide/")

(cons "Reference" "https://example.com/reference/")))))

(theme/provide-doc "my-package.scrbl" "my-theme.css" #:nav site-nav)

Each item is either a nav link (a label paired with a URL) or a nav menu (a label paired with a list of nav links). A menu renders as a <details> element, so it opens and closes without JavaScript.

The bar appears exactly once on every page: on the single page produced by scribble --html, and on every page produced by scribble --htmls. Internally, a block is added to the front of every part in the document; at render time this block produces the bar only in parts that begin a new HTML page, and an empty hidden <span> everywhere else.

This package supplies no CSS for the bar. It generates the markup below, and you style it in your theme:

The bar is placed inside the main column, just after the page heading, so a fixed position is the simplest way to keep it at the top of the window. The CSS below is a starting point. It also moves Scribble’s own fixed elements (table of contents, page navigation, version box) down to make room:

6 Linking to docs you publish elsewhere🔗ℹ

When a themed doc refers to a binding or section in another document (with racket, secref and so on), Scribble resolves the link from the cross-reference info of the copy installed locally. The --redirect flag shown above sends every such link through https://docs.racket-lang.org/local-redirect/, which only knows about the docs on that site. If you publish several of your own packages’ docs on your own site, links between them should stay on your site instead.

The module scribble-theme/xref loads the cross-reference info of every user-scope document itself and rewrites the link targets. Targets in the docs you publish get the absolute URL of the published page. Targets in every other user-scope doc are made to look like part of the main Racket docs, so that --redirect-main sends them to https://docs.racket-lang.org along with the real main docs. Write a small module that calls theme/load-xref with your URLs:

"site-xref.rkt"

#lang racket/base

(require scribble-theme/xref)

(provide site-xref)

(define (site-xref)

(theme/load-xref (hash "my-package" "https://example.com/docs/my-package/"

"my-other-package" "https://example.com/docs/my-other-package/")))

The keys are document ids: the name of the directory that holds a document’s rendered pages, which is normally the name of the main ".scrbl" file, or the name given in the package’s scribblings declaration. Then render with ++xref-in in place of --redirect, and add --redirect-main so that links into the main Racket docs still go to https://docs.racket-lang.org:

Links marked #:indirect are the one exception. Scribble always sends those through a search URL, so an indirect link into a doc you publish goes to a tag search at the installation’s documentation search site rather than to your copy. Drop the #:indirect flag for docs that are installed when you render.

7 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.

If #:nav is given, a site navigation bar built from the nav links and nav menus in nav-items-expr is added to the top of every HTML page (see Adding a site navigation bar).

The CSS files are copied into the output under content-hashed names unless #:fingerprint? is #f (see css->html-defaults).

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

Changed in version 2.1 of package scribble-theme: Added the #:nav and #:fingerprint? arguments.