8.1 Site Configuration Language

9.1

8.1 Site Configuration Language🔗

A Camp site is a single website, organized as a Racket package.

A site has one or more collections, which are named groups of pages with a sort order, a mapping between source and output paths, and optional taxonomies for further organization.

A page is a single source document.

A feed is an RSS or Atom feed which includes all pages from a set of one or more collections. A site may specify zero feeds, one feed, or multiple feeds.

#lang camp/site

package: camp-lib

The #lang camp/site language provides a TOML-based configuration format for defining Camp sites. Files written in this language are parsed and validated against the site schema.

8.1.1 Required Fields🔗

Field	Type	Description
title	string	Site title
url	string	Base URL (must be valid)
founded	date	Founding date for tag URI generation
authors	array	Authors in "Name (email)" format

8.1.2 Optional Fields🔗

Field	Type	Default	Description
sources	string	".md.rkt"	Source file extension
static-folder	string	"static"	Static assets directory
output-folder	string	"publish"	Build output directory
deploy-script	string	#f	Deployment script path
default-render	datum	#f	Default render function

8.1.3 Collections🔗

Each [[collections]] entry defines a group of source documents:

Field	Type	Required	Description
name	string	yes	Collection identifier
source	string	yes	Glob pattern (must end with *)
output-paths	string	yes	Output pattern with * and date codes
render-with	datum	no	Render function specification
order	string	no	"ascending" or "descending" (default)
sort-key	string	no	Metadata key for sorting (default: "date")
taxonomies	array	no	Taxonomy metadata keys

8.1.4 Feeds🔗

Each [[feeds]] entry defines an RSS or Atom feed:

Field	Type	Description
filename	string	Output filename (.atom or .rss)
collections	array	Collection names to include
render-with	datum	Feed content render function

The feed render function has the same signature as page render functions:

(define (feed-content doc ctxt)
  ;; doc: the Punct document
  ;; ctxt: same context as page render functions (slug, url, collection, etc.)
  ;; Returns x-expression for the feed entry body
  `(article ,@(document-body doc)
            (p (a ((href ,(context-url ctxt))) "Read more..."))))

The ctxt provides access to the page’s canonical URL, enabling feed content to include links back to the original page on your site.

8.1.5 Source/Output Path Mapping🔗

Camp uses path patterns to map source files to output locations.

A source path pattern specifies where to find source documents within a collection (e.g., "blog/*"). An output path pattern specifies the URL structure for rendered pages, with support for slug substitution and date-based paths (e.g., "blog/[yyyy]/[MM]/*/").

An output path pattern specifies the folder/file structure (and thus the URL) for rendered pages, with support for slug substitution and date-based paths. In output path patterns:

Any folder name consisting only of * will be replaced by the source’s slug.
Any folder name consisting of valid CIDR syntax inside a pair of brackets [] will be replaced by a string of the corresponding info from the source’s date meta.
If the pattern ends in a trailing slash /, the output file will be named "index.html". Otherwise the output is the name of the pattern’s final element with an added ".html" extension.

procedure
(source-path-pattern? v) → boolean?
v : any/c

Returns #t if v is a valid source path pattern: a relative path string that does not contain . or .. components, and whose final element is *.

procedure
(output-path-pattern? v) → boolean?
v : any/c

Returns #t if v is a valid output path pattern: a relative path string that does not contain . or .. components, contains at least one * element, and where any bracketed patterns (e.g., [yyyy]) are valid CLDR date format codes.

procedure
(format-output-path pattern slug date) → path?
  pattern : output-path-pattern?
  slug : string?
  date : (or/c date-provider? #f)

Applies an output path pattern to produce an output file path. The slug replaces * in the pattern, and date (if provided) is used for any bracketed date codes.

If the pattern contains date codes but date is #f, an error is raised.

Examples:

> (format-output-path "posts/*/" "hello-world" #f)
#<path:posts/hello-world/index.html>
> (format-output-path "blog/[yyyy]/[MM]/*/" "my-post" (date 2025 1 15))
#<path:blog/2025/01/my-post/index.html>

procedure
(file-extension? v) → boolean?
v : any/c

Returns #t if v is a valid file extension: a string or byte string starting with . and containing no directory separators.

procedure
(non-rkt-file-extension? v) → boolean?
v : any/c

Returns #t if v is a valid file extension other than ".rkt".

8.1.6 Site Configuration API🔗

The following data types from camp underlie the site configuration language. They are represented as hash-views: hash tables with struct-like accessor functions. For more information on hash-views, see hash-view: Struct-like Views of Hashes.

hash-view
(hash-view site ( title
url
founded
authors
[sources #:default ....]
[static-folder #:default ....]
[output-folder #:default ....]
collections
[racket-collection #:default ....]
[deploy-script #:default ....]
[default-render #:default ....]
[feeds #:default ....]))
   title : string?
   url : valid-url-string?
   founded : date-provider?
   authors : (listof string?)
   sources : string? = ".md.rkt"
   static-folder : string? = "static"
   output-folder : string? = "publish"
   collections : (listof collection?)
   racket-collection : (or/c string? #f)
   deploy-script : (or/c string? #f)
   default-render : (or/c list? #f)
   feeds : (listof feed-config?) = '()

A hash-view representing a site configuration. A site is most commonly defined using #lang camp/site.

Required fields are title, url, founded, authors, and collections.

The racket-collection field is set automatically by load-site from the package’s "info.rkt". It contains the Racket collection name (e.g., "myblog") and is #f if the site is not installed as a package.

hash-view
(hash-view collection ( name
source
output-paths
render-with
[order #:default ....]
[sort-key #:default ....]
taxonomies))
   name : string?
   source : source-path-pattern?
   output-paths : output-path-pattern?
   render-with : (or/c list? #f)
   order : string? = "descending"
   sort-key : string? = "date"
   taxonomies : (listof string?)

A hash-view representing a collection configuration. Collections are most commonly defined as part of a #lang camp/site configuration module.

Required fields are name, source, and output-paths.

hash-view
(hash-view feed-config ( filename
collections
render-with))
   filename : string?
   collections : (listof string?)
   render-with : list?

A hash-view representing a feed configuration. Feed configurations are most commonly defined as part of a #lang camp/site configuration module. All fields are required.

procedure
(load-site mod-path) → site?
mod-path :
(or/c path-string? module-path?
(and/c hash? (λ (h) (hash-has-key? h 'path))))

Loads a site configuration from a #lang camp/site module. The mod-path can be:

A filesystem path to a "site.rkt" file
A module path like 'my-site/site
A hash containing a 'path key (such as a book configuration returned by load-book)—the site is discovered from the package’s "info.rkt"

Returns the parsed site configuration as a hash-view with an additional 'root key containing the absolute path to the site’s directory.

procedure
(resolve-site-spec spec) → (or/c path? #f)
spec : (or/c path? string? symbol?)

Resolves a site specification to a path. The spec can be:

A path?: Returns the path if it exists as a file, #f otherwise.
A string?: If it exists as a file, returns it as a path. Otherwise, treats it as a collection name and searches installed packages.
A symbol?: Treats the symbol as a collection name and searches installed packages.

When searching by collection name, finds packages with a 'camp-site field in their "info.rkt" whose 'collection name matches.

(resolve-site-spec "site.rkt")       ; path if file exists
(resolve-site-spec "myblog")         ; finds myblog package
(resolve-site-spec 'myblog)          ; same, with symbol

procedure
(file-path->site-path file-path) → path?
file-path : path-string?

Discovers the site configuration path for a file within a Camp package. Uses path->pkg+subpath to find the package root, then reads the 'camp-site field from the package’s "info.rkt".

Raises an error if the file is not in a package, no "info.rkt" exists, or the 'camp-site field is not defined.

procedure
(load-book file-path) → book?
file-path : path-string?

Loads a book configuration from a #lang camp/book module. Returns the parsed book configuration as a hash-view with an additional 'path key containing the absolute path to the book file.

To load the associated site for a book:

(define mybook (load-book "path/to/my.book.rkt"))
(define mysite (load-site book)) ; discovers site from package info.rkt

contents ← prev up next →

1	Quick Start
2	Basic Camp Concepts
3	Building a Camp Site
4	Tutorial: Navigation and Cross-References
5	Tutorial: Listing and Index Pages
6	Tutorial: Creating a Book from Your Blog
7	Camp Computer: the GUI client for Camp
8	Library Reference
9	License, Acknowledgments

8.1	Site Configuration Language
8.2	Cross-Reference System
8.3	Rendering and Context
8.4	Structural Page Language
8.5	Book Configuration Language
8.6	Command-Line Interface
8.7	Low-Level API

8.1.1	Required Fields
8.1.2	Optional Fields
8.1.3	Collections
8.1.4	Feeds
8.1.5	Source/ Output Path Mapping
8.1.6	Site Configuration API