Your Options
Cryogen provides some flexible configuration options. Your site's configuration file can be found at content/config.edn and contains the following by default:
{:site-title "My Awesome Blog"
:author "Bob Bobbert"
:description "This blog is awesome"
:site-url "http://blogawesome.com/"
:post-root "posts"
:page-root "pages"
:post-root-uri "posts-output"
:page-root-uri "pages-output"
:tag-root-uri "tags-output"
:author-root-uri "authors-output"
:public-dest "public"
:blog-prefix "/blog"
:rss-name "feed.xml"
:rss-filters ["cryogen"]
:recent-posts 3
:post-date-format "yyyy-MM-dd"
:archive-group-format "yyyy MMMM"
:sass-src []
:sass-path "sass"
:compass-path "compass"
:theme "blue"
:resources ["img"]
:keep-files [".git"]
:disqus? false
:disqus-shortname ""
:ignored-files [#"\.#.*" #".*\.swp$"]
:previews? false
:posts-per-page 5
:blocks-per-preview 2
:description-include-elements #{:p :h1 :h2 :h3 :h4 :h5 :h6}
:clean-urls :trailing-slash
:collapse-subdirs? false
:hide-future-posts? true
:klipse {}
:debug? false}}
Details
Keys marked with a * must be provided.
| Key | Description |
|---|---|
* site-title | Your site's title |
* author | Your name goes here! |
* description | A blurb describing your site |
* site-url | Your site's root url. This, along with all of the above values are used when generating your sitemap and RSS feed. |
* post-root | The folder where the compiler will look for blog posts. |
* page-root | The folder where the compiler will look for your custom pages. |
post-root-uri | The folder where the compiler will output compiled blog posts. This value is prepended to all post uri's. If this key is omitted then the name of the output folder will be the same as the post-root folder. If en empty string ("") is provided then the posts will be outputted to the root folder of the blog (ie. {public-dest}/{blog-prefix}). |
page-root-uri | The folder where the compiler will output compiled pages. This value is prepended to all page uri's. If this key is omitted then the name of the output folder will be the same as the page-root folder. If the empty string ("") is provided then the posts will be outputted to the root folder of the blog. |
tag-root-uri | The folder where the compiler will output compiled tag pages. This value is prepended to all tag page uri's. If this key is omitted then the empty string will be used. |
author-root-uri | If this value is provided then the compiler will generate a page for each author containing a list of all their posts. More info here. |
public-dest | Sets where to output the rendered site. Defaults to "public" if not specified. |
* blog-prefix | Prepended to all uri's. This must start with a slash. |
* rss-name | The name of the rss file generated. |
rss-filters | A vector of specific tags for which you want to create a separate RSS feed. |
recent-posts | The maximum number of recent posts to show in the sidebar. Defaults to 3. |
* post-date-format | Set the date format that you want to use for the names of your .md files representing your posts. |
archive-group-format | Set the date format in which your archive page is organised. "yyyy" organises by year, "yyyy MMMM" organises by year and month. Defaults to "yyyy MMMM". |
sass-src | A vector of directories containing sass(scss) files to be compiled. If this key is omitted then the default is ["css"]. Be sure to include these directories in your :resources section as the compiled css will be outputted in the same directory. |
sass-path | Path at which the sass executable can be found. The default value "sass" works if you have the executable in your path, in that case nothing needs to be changed. If the executable is not in the search path or has a different name then please adapt this value. |
compass-path | Path at which the compass executable can be found. Just as with the sass-path the default value "compass" works if you have the executable in your path; in that case, nothing needs to be changed. If the executable is not in the search path or has a different name then please adapt this value. |
* theme | Set this to the theme you wish to deliver from the themes directory. You can add your own theme to this folder along with the current blue, blue_centered and nucleus themes. |
resources | A vector of directories/files to be copied over from content to public upon compilation. |
keep-files | A vector of directories/files to preserve when wiping the public folder between compilations. |
disqus? | Set this to true if you want Disqus enabled on your site. disqus-shortname must be provided if this is true. |
disqus-shortname | Your Disqus shortname. |
ignored-files | A vector of regexes matching files that you want to ignore during compilation. (Ex: emacs interlock files.) |
ignored-sitemap-paths | A vector of regexes matching paths that you want to ignore when generating a sitemap. |
previews? | Set this to true if you would like to display a list of recent posts rather than a full, single post on your home page. Discussed here. post-per-page and blocks-per-preview must provided if this is true. |
post-per-page | If post previews are enabled then this is the maximum number of previews on a page. Defaults to 5. |
blocks-per-preview | The default number of (html) blocks to display per post preview. This can be overwritten by adding <!--more--> to your .md or .adoc file to indicate where you'd like to break off your post. Defaults to 2. |
:description-include-elements | The HTML elements from a preview whose content should be included in the plain-text :description of the page/post. Defaults to paragraphs and all headings, i.e. #{:p :h1 :h2 :h3 :h4 :h5 :h6}. |
* clean-urls | :trailing-slash, :no-trailing-slash, and :dirty are valid options. Set this to :trailing-slash to emit html as subdirectories, e.g., prefix/root/page-name/index.html. Links would then end in /page-name/. Set this to :no-trailing-slash if you use GitHub Pages and prefer URLs not contain a final trailing slash. Links would then end in /page-name. Note: :no-trailing-slash will not work on all hosting providers such as Amazon S3. Set this to :dirty will result in prefix/root/page-name.html. Links would then end in /page-name.html Note 2: You can override the default URL with a smart use of :update-article-fn. |
collapse-subdirs? | Set this to true if you have your posts or pages organized in subdirectories and do not want that structure reflected in the url. e.g., /awesome-post/ instead of /2016/awesome-post/. |
hide-future-posts? | Set this to true to include only current and past blogs in the compiled site. This allows for easy drafting of future articles. |
klipse | Set Klipse configuration for the whole site. See Klipse Integration for details. |
debug? | Enable debug outputs for compiler. |
Custom Values
In addition to these default configuration options, you may add your own custom values. For example, if your blog has a subtitle that you'd like to display on your site:
- Add
:subtitle "My subtitle"to the config file - Inject the value into your templates via Selmer using
{% subtitle %}
Advanced Configuration
If you want to override or extend config.edn from code, (e.g. by reading environment variables or by using an untracked file) you can edit src/cryogen/core.clj and src/cryogen/server.clj to pass a clojure map to the compile-assets-timed function. This is especially useful if you are making use of the custom values to configure 3rd party integrations like ReCaptcha.
For Example, if you wanted to have private options loaded from a secrets.edn file, you could do the following:
;; src/cryogen/core.clj
;; ...
(defn -main []
(load-plugins)
(compile-assets-timed (read-string (slurp "secrets.edn")))
(System/exit 0))
;; ...
;; src/cryogen/server.clj
;; ...
(defn init []
(let [overrides (read-string (slurp "secrets.edn"))]
(load-plugins)
(compile-assets-timed overrides)
(let [ignored-files (-> (resolve-config) :ignored-files)]
(start-watcher! "content" ignored-files (partial compile-assets-timed overrides))
(start-watcher! "themes" ignored-files (partial compile-assets-timed overrides)))))
;; ...
Deriving Additional Params for Use in Templates
If you wish to further derive more parameters from the data that the cryogen compiler generates, you may pass in a :extend-params-fn in your overrides map which will be invoked by the compiler like so
((:extend-params-fn overrides)
params
{:posts posts
:pages pages
:posts-by-tag posts-by-tag
:navbar-pages navbar-pages
:sidebar-pages sidebar-pages})
It should return the params, likely with additional keys. These will be visible to your templates.
See Customizing/Extending Cryogen for an example.