Creating PLT-Style Web Pages
1 Configuring a Site
site
site?
site-dir
site-css-path
site-favicon-path
site-navbar
site-navbar-dynamic-js
2 Creating Site Content
page
page*
plain
plain*
copyfile
symlink
make-indexes
index-site?
index-site
index-page
call-with-registered-roots
3 Generating Site Content
4 Utilities
basename
web-path
7.0

Creating PLT-Style Web Pages

The plt-web language builds on scribble/html for generating pages in the same style as http://racket-lang.org/.

Unlike scribble/html, the values of expressions in a plt-web module are not treated as HTML. Instead, top-level expressions in plt-web are as in racket/base.

Meanwhile, a main submodule is added that runs render-all (after parsing command-line arguments) to render all registered resources, including HTML pages. Pages are meant to be registers through a page form that is defined by a define-context or define+provide-context declaration that configures a particular site (i.e., collection of pages).

1 Configuring a Site

A site is identifiers by a relative directory path, which determines where the site’s content is generated. For a non-local build, the relative directory is mapped to a destination URL via url-roots.

procedure

(site dir    
  [#:url url    
  #:always-abs-url? always-abs-url?    
  #:generate? generate?    
  #:share-from share-from    
  #:page-style? page-style?    
  #:page-headers page-headers    
  #:meta? meta?    
  #:robots robots    
  #:htaccess htaccess    
  #:navigation navigation])  site?
  dir : path-string?
  url : (or/c string? #f) = #f
  always-abs-url? : any/c = #t
  generate? : any/c = #t
  share-from : (or/c site? #f) = #f
  page-style? : any/c = #t
  page-headers : outputable/c = null
  meta? : any/c = page-style?
  robots : (or/c #f #t outputable/c) = #t
  htaccess : (or/c #f #t outputable/c) = #t
  navigation : (listof outputable/c) = null
Creates a value that represents a site.

If url is not #f, then it will be registered to url-roots for a build in web mode (as opposed to local mode) and recorded as the target for dir in a "sites.rktd" file when building in deployment mode.

If always-abs-url? is true (the default), then url is registered with a 'abs flag, so that (in deployment mode) references within a site are relative to the site root, as opposed to relative to the referencing resource.

If generate? is #f, then resources for the site (such as icons or CSS files) are not generated.

If share-from is a site, then resources generated for the site (such as icons or CSS files) are used when as possible for the new site.

If page-style? is true, HTML pages generated for the site include content to set the style of the overall page. Otherwise, only sufficient resources and content are included to specify the style of the PLT web-page header (i.e., a bar with the Racket logo).

The page-headers argument provides content for the header of any HTML page generated at the site via page or page*.

If meta? is true, then ".htaccess", "robots.txt", and similar files are generated for the site. The robots and htaccess arguments determine robot and access information included by the default resource-mapping function. A #t value enables normal access, a #f value disables access, and any other value is used as the corresponding specification.

The navigation argument determines content (usually links) to be included in the PLT header. Currently, up to four such links are supported.

procedure

(site? v)  boolean?

  v : any/c
Returns #t if v represents a site, #f otherwise.

procedure

(site-dir s)  path-string?

  s : site?
Extracts the destination directory of s.

procedure

(site-css-path s)  outputable/c

  s : site?
Extracts a reference to a CSS resource for HTML pages at site s.

procedure

(site-favicon-path s)  outputable/c

  s : site?
Extracts a reference to a "favicon.ico" file for the site s. The result is #f if meta-file resources are not generated for the site.

procedure

(site-navbar s)  outputable/c

  s : site?
Generates HTML for the banner on HTML pages at the site s.

procedure

(site-navbar-dynamic-js s)  outputable/c

  s : site?
Generates a JavaScript definition of a AddNavbarToBody function, which adds a banner dynamically to the current page for a page at site s.

2 Creating Site Content

syntax

(page keyword-arg ... form ...)

 
keyword-arg = keyword expr
Equivalent to (page* keyword-arg ... (lambda () (begin/text form ...))).

procedure

(page* #:site s    
  [#:html-only html-only?    
  #:id id    
  #:file file    
  #:title title    
  #:link-title link-title    
  #:window-title window-title    
  #:width width    
  #:description description    
  #:extra-headers extra-headers    
  #:extra-body-attrs body-attrs    
  #:referrer referrer    
  #:part-of part-of]    
  content)  outputable/c
  s : site?
  html-only? : any/c = #f
  id : path-string? = #f
  file : (or/c path-string? #f) = #f
  title : string? = (... id)
  link-title : outputable/c = title
  window-title : string? = (string-append "Racket: " label)
  width : (or/c #f 'full outputable/c) = #f
  description : string? = #f
  extra-headers : outputable/c = #f
  body-attrs : outputable/c = #f
  referrer : (string? outputable/c ... . -> . outputable/c)
   = 
(λ (url . content)
  (a href: url (if (null? content) linktitle content)))
  part-of : (or/c #f symbol?) = #f
  content : outputable/c
Registers an HTML page as a resource (via resource) and returns a value that can be used to refer to the page within another resource, assuming that html-only? is #f. If html-only? is true, then the result represents HTML for the page, instead of a way to reference the page, and no resource is registered.

The page is generated as part of the site s, and either an id or file must be provided to identify the page within the site. Furthermore, either id or title must be provided to determine the page’s title.

The link-title and window-title arguments control separate the title of the page as used by references and for the page as viewed.

The width argument determines the page wide: #f is the default, 'full is full width, and any other value is used as a CSS width.

The description argument provides a meta tag for the page.

The part-of argument determines where the page resides in a larger site when the layout uses a global navigation bar (but the current format does not use a navigation bar in that sense).

syntax

(plain keyword-arg ... form ...)

 
keyword-arg = keyword expr
Equivalent to (plain* keyword-arg ... (lambda () (begin/text form ...))).

procedure

(plain* #:site s    
  [#:id id    
  #:suffix suffix    
  #:file file    
  #:referrer referrer    
  #:newline newline?]    
  content)  outputable/c
  s : site?
  id : path-string? = #f
  suffix : (or/c #f string?) = #f
  file : (or/c path-string? #f) = #f
  referrer : (string? outputable/c ... . -> . outputable/c)
   = 
(λ (url . content)
  (a href: url (if (null? content) linktitle content)))
  newline? : any/c = #t
  content : outputable/c
Like page*, but for a resource that is a plain file.

procedure

(copyfile #:site s src [dest])  outputable/c

  s : site?
  src : path-string?
  dest : string? = (basename src)

procedure

(symlink #:site s src [dest])  outputable/c

  s : site?
  src : path-string?
  dest : string? = (basename src)
Registers a resource that is either a copy of a file or a symbolic link, returning a value that can be used to reference the resource.

procedure

(make-indexes s    
  dir    
  [#:depth depth    
  #:use-dir? use-dir?])  void?
  s : site?
  dir : (or/c 'same relative-path?)
  depth : (or/c #f exact-nonnegative-integer?) = #f
  use-dir? : ((or/c 'same relative-path?) . -> . any/c)
   = (lambda (dir) #t)
Uses index-site and index-page to register an "index.html" file for every directory within dir (relative to the current directory) that does not have an "index.html" file already. If depth is not #f, then subdirectories are explored at most depth layers deep. The use-dir? predicate is called for each directory to determine whether the directory’s subdirectories are traversed.

The generated index files are registered for the site s at destinations that correspond to treating the current directory as the site root.

procedure

(index-site? v)  boolean?

  v : any/c

procedure

(index-site site)  index-site?

  site : site?

procedure

(index-page isite    
  path    
  content    
  [#:html-only? html-only?])  outputable/c
  isite : index-site?
  path : (or/c 'same relative-path?)
  content : 
(listof
 (or/c (cons/c path-string? (or/c exact-integer? 'dir))
       (cons/c path-string?
               (cons/c string? (or/c exact-integer? 'dir)))))
  html-only? : any/c = #f
The index-page function registers an individual "index.html" file (or returns its content if html-only? is true) for the given index site, where an index site is created once for a given site (to register support resources, such as icons). The "index.html" file is generated for the subdirectory indicated by path.

The index file lists the content specified by content. For each element of content, the initial path string is the item as shown on the page, and an ending integer corresponds to a file size or and ending 'dir indicates a directory. If an extra string is provided, then the content link is redirected to the string as a URL, otherwise the link is the same as the name shown on the page.

Changed in version 1.3 of package plt-web-lib: Added the redirection option in content.

procedure

(call-with-registered-roots thunk)  any

  thunk : (-> any)
Calls thunk with url-roots set to a mapping for registered sites.

3 Generating Site Content

To generate web pages from a plt-web module, run the module, typically with a -o flag to specify the output directory. For example, if "pages.rkt" is the module, then

  racket pages.rkt -o /tmp/pages

builds the output to a "/tmp/pages" directory.

The command-line flags are recognized by the main submodule that is introduced by plt-web:

4 Utilities

procedure

(basename p)  string?

  p : path-string?
Extracts a file name from a path.

procedure

(web-path str ...)  string?

  str : string?
Joins strs with a "/" separator to form a relative URL path.