The kitchen-sink-dot-json file

When generating HTML content, most of the work can be done without context of “where” an application will be hosted. Unfortunately, some information do leak a bit. In particular, if you want to support some features like OpenGraph or RSS, you are supposed to know, at the time of generating the HTML and before publishing the HTML, the URL of published URLs. Rather than polluting all articles with this concern, we do it once for all articles. Enters the kitchen-sink.json configuration file.

contents of kitchen-sink.json

As the time of writing this article, kitchen-sink.json supports the following keys:

• title: the title on the index page and the prefix of per-articles titles
• publishURL: the url that will be added as prefix of links in permalinks
• basePath (optional): a path prefix (e.g., "tramaj" or "/tramaj") prepended to every internal link, stylesheet, script, and image URL that kitchen-sink generates. Leave unset (or "") when the site is hosted at the domain root; set it when the site is hosted under a subpath, such as a GitHub Pages project page (https://user.github.io/reponame/) as opposed to a user/org page (https://user.github.io/). This also covers root-relative links and images an author writes by hand inside main-content/summary markdown – [home](/index.html) is rewritten the same way as kitchen-sink’s own generated links, while absolute (https://...), protocol-relative (//...), and fragment (#...) URLs are left alone. Raw HTML is the exception: a .html link/src an author writes inside a raw .html file, or inline in markdown (an <iframe>, say), is not analyzed and is copied through untouched – see Other Formats for why, and for the .tramaj-doc workaround. It is also available to .dhall/.tramaj-json/.tramaj-doc sections as kitchensink.pathPrefix/$ctx.pathPrefix (see Dhall sections / Tramaj sections), for cases like a CSS section’s own @import URLs that kitchen-sink itself does not rewrite
• homeLink (optional): an object tuning the link back to the site root shown in every layout’s header, with two optional fields. label is the link text and defaults to "Home". icon is the URL of an image rendered inside the link before the label (with an empty alt, since the label carries the meaning); a root-relative URL such as "/images/logo.png" follows the basePath like every other internal link, while absolute URLs are left alone. The anchor carries a home-link class so a stylesheet can size the icon (the scaffold’s navigation.css sets it to 1em high). Leave homeLink out to keep a plain “Home” link.
• menu (optional): an array of entries shown in the header of every layout, after the home link. Each entry has a label and a url and, optionally, children: an array of {label, url} links rendered as a sub-menu (one level only). URLs follow the same rule as homeLink.icon: a root-relative URL follows the basePath, other URLs are left alone. The list carries a site-menu class (site-submenu for the sub-menus). Leave menu out to render nothing.
• footer (optional): an object rendered at the bottom of every layout, with two optional fields. columns is an array of {heading, links} objects (heading is optional, links is an array of {label, url}), and legal is a line of text shown below the columns (e.g., a copyright notice). The <footer> carries a site-footer class, with footer-columns, footer-column and footer-legal inside. Leave footer out (or give it neither columns nor legal) to render nothing.
• twitterLogin (optional): the Twitter handle for the website, which may differ from the Twitter handle of individual authors
• commands: an array of json objects containing:
  • a display for the text on the web
  • a handle that must be unique across command and gives a command name, this value is used as a query-param (suggestion: a lower-kebab-case word)
  • a exe as a path to a script that is executable from the webserver
• publishScript (deprecated, use a command instead): an historical “blessed” command. This is documented only if you ever encounter a kitchen-sink.json with this field, the support for this field will be removed in the feature.
• api (required,experimental): asks kitchen-sink, when run in DEV mode, to proxy /api-prefixed requests to an [host,port] destination
  • the proper type is an Aeson-encoded Haskell datatype (i.e., using a level of JSON-object containing tag and contents keys)
  • values can either be
    • {"tag": "NoProxying"}
    • {"tag": "SlashApiProxy", "contents": ["localhost",3000]}
    • {"tag": "SlashApiProxyList", "contents": [ {"security": "UsePlainText", "prefix":"/api/appli-1", "rewrite": {"tag": "NoRewrite"}, "hostname":"localhost", "portnum":8001}, {"security": "UseHTTPS", "prefix":"/api/appli-2", "rewrite": {"tag": "NoRewrite"}, "hostname":"some.example.com", "portnum":443} ]}
• linkedSites (optional, experimental): a series of json objects containing a listing of the external sites you consider especially important (and they show up on the site-graph for instance):
  • a baseUrl string
  • a siteTitle string
  • a siteType string

An example of kitchen-sink.json

{ "title": "Kitchen Sink Default Page"
, "publishURL": "https://kitchensink.github.io"
, "twitterLogin": "lucasdicioccio"
, "commands":
  [ {"display": "publish to github", "handle": "publish", "exe": "./scripts/publish.sh" }
  ]
, "api": {"tag": "SlashApiProxy", "contents": ["localhost", 3000] }
, "linkedSites":
  [ {"baseURL": "https://dicioccio.fr/", "siteTitle": "Lucas' blog.", "siteType": "kitchen-sink"}
  , {"baseURL": "https://en.wikipedia.org/", "siteTitle": "The English WikiPedia.", "siteType": "website"}
  ]
}

The publishScript here is very simple (switches to the output dir, git-add and commit everything, git pushes).

specifying a special-location

The normal mode for KitchenSink is to locate kitchen-sink.json in your site source directory. Thus, if your --srcDir parameter is foobar, KitchenSink will look for foobar/kitchen-sink.json.

You can override where to locate this special file with the --ksFile command line argument.