weblorg
weblorg

Routing

(weblorg-route (&rest options))

Add a new route defined with parameters within OPTIONS.

A route contains enough information to find content to be rendered, which template to use to render such content, where to save the rendered output and how to create hyperlinks to it. It sounds like it’s a lot of responsibilities for a single abstraction, but one can think of it as an HTTP route in a website with some helpers for also finding which content to render in that route.

Examples:

  1. Route that finds all the Org-Mode files within the posts directory, aggregate them all in one single collection made available to the also template called posts so it can be used to build summary pages

    (weblorg-route
     :name "index"
     :input-pattern "posts/*org"
     :input-aggregate #weblorg-input-aggregate-all
     :template "blog.html"
     :output "output/index.html"
     :url "/")
    
  2. Route for rendering each Org-Mode file under the directory pages as a separate HTML using the template page.html. Notice the :output parameter will create all the directories in the path that don’t exist

    (weblorg-route
     :name "pages"
     :input-pattern "pages/*.org"
     :template "page.html"
     :output "output/{{ slug }}/index.html"
     :url "/{{ slug }}")
    

Parameters in OPTIONS:

  • :input-pattern glob expression for selecting files within path ‘:base-dir’. It defaults to "*.org";
  • :input-exclude Regular expression for excluding files from the input list. Defaults to "^$";
  • :input-filter Function for filtering out files after they were parsed. This allows using data from within the Org-Mode file to decide if it should be included or not in the input list.
  • :input-aggregate Function for grouping files into collections. Templates are applied to collections, not to files from the input list. The variables available for the template come from the return of this function.
  • :input-source List of collections of data to be written directly to templates. In other words, this parameter replaces the pipeline ‘pattern‘ > ‘exclude‘ > ‘filter‘ > ‘aggregate‘ and will feed data directly into the function that writes down templates. This is useful for generating HTML files off template variables read from whatever source you want.
  • :output String with a template for generating the output file name. The variables available are the variables of each item of a collection returned by ‘:input-aggregate’.
  • :url Similarly to the ‘:output’ parameter, it takes a template string as input and returns the URL of an entry of a given entry in this route.
  • :template Name of the template that should be used to render a collection of files. Notice that this is the name of the template, not its path (neither relative or absolute). The value provided here will be searched within 1. the directory template within ‘:base-dir’ 2. the directory templates within weblorg’s source code.
  • :template-vars Association list of extra variables to be passed down to the template.
  • :base-dir Base path for ‘:input-pattern’ and ‘:output’; If not provided, will default to the ‘:base-dir’ of the website;
  • :site Instance of a weblorg site created by the function weblorg-site. If not provided, it will use a default value. The most valuable information a site carries is its base URL, and that’s why it’s relevant for routes. That way one can have multiple sites in one single program.

(weblorg-copy-static (&rest options))

Utility and Route for static assets of a weblorg site.

Use this route if you want either of these two things:

  1. You want to use a built-in theme and need to copy its assets to the output directory of your site;
  2. You are want to copy assets of your local theme to the output directory of your site;

Examples:

  1. Add static route to the default site. That will allow ‘urlfor’ to find the route "static".

    (weblorg-copy-static
     :output "output/static/{{ basename }}"
     :url "/static/{{ basename }}")
    
  2. This example uses a custom site parameter. The site parameter points to a CDN as its Base URL.

    (weblorg-copy-static
     :output "output/public/{{ filename }}"
     :url "/public/{{ filename }}"
     :site (weblorg-site
            :name "cdn"
            :base-url "https://cdn.example.com"
            :theme "autodoc"))
    (weblorg-export)
    

Parameters in OPTIONS:

  • :output String with a template for generating the output file name. The variables available are the variables of each item of a collection returned by ‘:input-aggregate’.
  • :url Similarly to the ‘:output’ parameter, it takes a template string as input and returns the URL of an entry of a given entry in this route.
  • :site Instance of a weblorg site created by the function weblorg-site. If not provided, it will use a default value. The most valuable information a site carries is its base URL, and that’s why it’s relevant for routes. That way one can have multiple sites in one single program.
  • :name name of the route. This defaults to "static". Notice that if you are using this function to copy assets from a built-in theme, the template of such a theme will reference the route "static" when including assets. Which means that you need at least one "static" route in your site.

Exporting

(weblorg-export)

Export all sites.

Data Sources

(weblorg-input-source-autodoc (pattern))

Pull metadata from Emacs-Lisp symbols that match PATTERN.

Input source functions allow using custom code for feeding the renderization pipeline. It replaces the "Collect -> Aggregate" step with the output of a custom function.

This function is one of these input sources. Its input, PATTERN, is used to find which Emacs Lisp symbols should have its metadata returned.

PATTERN can be either a string or a list of strings. If it’s a string, we parse all symbols found by ‘apropos-internal’:

(weblorg-route
 :name "templatel-api"
 :input-source (weblorg-input-source-autodoc "^templatel-")
 :template "autodoc.html"
 :output "api.html"
 :url "/api.html")

If PATTERN a list of strings, we’ll build a list of all calls to ‘apropos-internal’ for each of the strings in the list. e.g.:

(weblorg-route
 :name "templatel-api"
 :input-source (weblorg-input-source-autodoc
                ("^templatel-env" "^templatel-filter"))
 :template "autodoc.html"
 :output "api.html"
 :url "/api.html")

If you want to group functions into sections, take a look at weblorg-input-source-autodoc-sections.

(weblorg-input-source-autodoc-sections (sections))

Run ‘weblorg-input-source-autodoc’ for various SECTIONS.

Input Filters

(weblorg-input-filter-drafts (post))

Exclude POST from input list if it is a draft.

We use the DRAFT file property to define if an Org-Mode file is a draft or not.