Cryogen

Static sites generated with Clojure

Creating pages is not much different from writing posts. You're still required to include the map representing the metadata and the page must be written in valid Markdown.

The Pages Folder

Similar to your posts, all of your pages should reside under the page-root folder specified in your configuration file. Again, as long as the file contains the proper metadata followed by valid Markdown content, they will be converted into an HTML page.

Creating Pages

To create a new page, just make a new Markdown/AsciiDoc file under your page-root. You don't need to include a date in the file name or in the metadata like you did a post but words should still be dash-separated and the file must have a .md or .adoc extension. For example:

about.md
my-projects.md
contact-me.adoc

Page Contents

You may include an EDN-formatted map of metadata at the start of your page file. If you do include such a map, the following information is mandatory:

KeyDescription
titleYour post title provided as a string.
page-indexBecause pages can be linked up with previous/next links, this is how they get sorted.

These are some optional keys that you may provide:

KeyDescription
navbar?Set this to true if you want the link to this page to appear in the navbar. Set it to false or leave out the key if you want it in the sidebar.
home?Set this to true if you want to use this page as your index rather than a blog post or list of previews. Only one page may have this flag set to true. This page will not be part of your navbar-pages or sidebar-pages collection. The :layout key will be respected. :previews? must be set to false in the config.edn.
tocSet this to true if you want a table of contents to be generated from the headers/headings in your post. (The default table of contents format is an ordered list. Set this to :ul if you want a bulleted list.)
toc-classSpecify the class that you want attached to the root element of your TOC (either ul or li). If this is not provided then the compiler will look for the class in config.edn. If neither are provided then "toc" is used.
klipseSet Klipse configuration for the post. See Klipse Integration for details.
layoutA keyword corresponding to an HTML file under themes/{theme}/html. Defaults to :page.
descriptionProvide a custom description for the page (available as {{page.description}} in the templates) instead of the one created automatically from the post's preview. Set it to false to disable description for the page. (page.description will thus be nil.)
imagePath to an image illustrating the page, or a map with the keys as documented below; in either case, used to provide the metadata to allow social media platforms to construct a rich Open Graph banner for a link to your post.

For example:

{:title      "Check out this page!"
 :page-index 0
 :navbar?    false
 :home?      false}

If you include a map rather than a path as the value of :image, it should have keys as follows:

KeyDescription
alta description of the image intended to describe it to users with visual impairments.
heightthe height of the image in pixels as a number.
paththe path to the image.
typethe MIME type of the image, as a string; typically one of "image/gif", "image/jpeg", or "image/png".
widththe width of the image in pixels as a number.

If you don't include a map of metadata at the head of your post, an attempt will be made to construct such a map. Fields will be constructed as follows:

KeyDerivation
authorwill be inferred from the owner of the file. This will be passed to an appropriate operating system mechanism to retrieve the real name associated with that user account, if any.
descriptionwill be taken from the first normal paragraph of the text.
imagewill be taken from the first image linked in the text, if any.
titlewill be taken from the first top level heading in the text, or, failing that, from the name of the file with the date part (if any) and extension removed.

There are clearly, then, fields which are not currently inferred; these are:

  1. :home?;
  2. :klipse — which could be inferred and may be in the future but is not now;
  3. :layout;
  4. :navbar?;
  5. :page-index — this is not currently inferred but clearly should be;
  6. :toc — this again could be inferred but is not currently.

If you wish to use any of these fields you must embed metadata in your file; and, curently, you cannot use both embedded and inferred metadata: if a metadata map is found, no metadata will be inferred.

Images in Your Pages

You can include images in your pages in the same way you include images in your blog posts. Please refer to the "Including Images in Posts" and "Images in Markdown" sections of the Writing Posts page.

You can link to other pages or posts on your site in the same way you include these links in your blog posts.

Highlighting Code Snippets

Want to show off your code in a page? It works the same way as it does in posts. Just wrap your code block in triple backticks and highlight.js will take care of the rest.