DynSite: Dynamic Org 2 HTML Project definition

The dynsite package builds on the standard org-publish scheme. It provides functions which simplify the definition of groups of projects. Instead of defining projects in emacs-lisp by creating lists of settings for folders and properties, one defines for each site one source folder and one target folder only. Any number of projects or subprojects can be defined inside a source folder. Dynsite scans all folders of a site, and creates projects for those folders which contain a file config.org, naming each project after the name of the folder that contains it. Projects in subfolders inherit the configuration parameters of their superfolder-projects.

An important feature is the automatic completion of relative paths of links, which keeps the links to css or other files consistent even in subfolders of a project. For example:

If the path to a css file, which is used for headers defining the page style of a all files in a site, is ./css/org.css, then normally a file which is placed in a subfolder of the projects' top folder must change the path of the css style link to ./../css/org.css. Org-mode > 8.0 provides a mechanism for doing this simpler described in the doc (http://orgmode.org/worg/org-tutorials/org-publish-html-tutorial.html) in paragraph /"Tired of export templates?"/. Dynsite provides a scheme that is simpler than that. In order to make any link update to a relative path to the root folder, one codes the "root folder" of the project with the string {{.}}. So instead of defining the style path in html-head as:

<link rel="stylesheet" href="./css/org.css" type="text/css"/>

one defines it as:

<link rel="stylesheet" href="{{.}}/css/org.css" type="text/css"/>

Dynsite adds a filter to org-export-filter-final-output-functions which converts the string . to a relative path consitently pointing to the original css file. The same holds for all other links inside the org files to be published.

For each site defned with DynSite expects all org-to-html projects to be stored as subfolders of one single folder. For example, if one has 3 projects named project1, project2 and project3, one could place them in one folder named org as follows:

path	contents
/users/user1/websites/org	top folder containing all projects
/users/user1/website/org/project1	all files (and folders) of project1
/users/user1/website/org/project2	all files (and folders) of project2
/users/user1/website/org/project2	all files (and folders) of project3

These projects are published in subfolders of the single target folder specified in the site definition, preserving the same structure as the source folder.

It is possible to work with several different sites, where each site has its own source folder (the org project files), its own target folder (the published html files) and a url for uploading the rendered html files to a server using rsync. See Working with multiple sites below.

There is only one rule for defining a project:

If a folder is contained in the top folder containing all projects and this folder contains a file called config.org then this folder becomes a project folder.

This means: To define a new project for publishing, you must do 2 things:

1. Create a folder for the project, which is contained inside the top folder holding all projects, or one of its subfolders
2. Create a file called config.org inside the top level of the folder that contains the project.

The contents of the file config.org define the properties of the project, i.e. they customize the project. In orgmode, the publishing options of a project are defined as (emacs-lisp) properties. These are described in section "13.1.5 Options for the HTML/LaTeX exporters" of the org-info documentation (type "meta-x org-info" to enter the org-info documentation, then go to section (menu item) Publishing, subsection Configuration, subsubsection "Publishing options"). The config.org file lets one define these properties in a simpler way, without writing them as lisp expressions. This is done as follows:

A property consists of a name (the name of the property) and a value (the value of the property). In the config.org file, the name of the property is given as a top-level org-node entry and the value of the property is given as the contents of the entry. For example, to define the property "author" giving it the value "Tom Jones", one puts the following node in the config.org file:

* author
Tom Jones

A special case are properties whose values are not strings (such as the string "Tom Jones" above), but lisp objects such as numbers, functions or other types of objects. These are indicated in the config.org file by appending ":" to the name of the property, and are entered as expressions that are evaluated by lisp, in the same line as the property name. For example, If a property needs to have a numerical value, or an otherwise computed value, this value is written as an expression that can be evaluated by lisp, in a single line. For example, to set the property "section-numbers" to the value "nil", one writes:

* section-numbers: nil

Second example: To set the property "headline-levels" to 3, one writes:

* headline-levels: 3

Following example compares the configuration of a project using lisp source code with the same configuration done using config.org in DynSite.

;; Webtools project. Configuration using the original emacs-lisp code method of orgmode: 
(add-to-list 'org-publish-project-alist
	'("webtools"
	 :base-directory "~/Dropbox/orgshared/sites/org/earlab/tools/webtools/"
	 :base-extension "org"
	 :publishing-directory "~/Dropbox/orgshared/sites/html/earlab/tools/webtools/"
	 :section-numbers nil
	 :table-of-contents nil
	 :recursive t
	 :publishing-function org-publish-org-to-html
	 :headline-levels 1        
	 :auto-preamble t
	 :preamble 
	 "
<div id=\"toc\">
<a href=\"http://earlab.org/\">Earlab Home</a> | 
<a href=\"http://earlab.org/tools/webtools\">Web Tools Home</a> | 
<a href=\"http://earlab.org/tools/webtools/gettingstart.html\">Getting Started</a> | 
<a href=\"http://earlab.org/tools/webtools/javascript.html\">JavaScript</a> | 
<a href=\"http://earlab.org/tools/webtools/projects.html\">Projects</a> | 
<a href=\"http://earlab.org/tools/webtools/tutorials.html\">Tutorials</a> | 
<a href=\"http://earlab.org/tools/webtools/topics.html\">Topics</a> | 
<a href=\"http://earlab.org/tools/webtools/links.html\">Links</a> |  
</div> 

<div style = \"position: absolute; top: 10px; left: 10px; \">
 <FORM METHOD=\"POST\" ACTION=\"/tools/webtools/cgi-bin/3.0/search_engine.cgi\"><INPUT TYPE=\"text\" SIZE=\"20\" NAME=\"keywords\" MAXLENGTH=\"80\"><INPUT TYPE=\"SUBMIT\" VALUE=\"Search\"></FORM> 
</div>

"
	 :style "
<link rel=\"stylesheet\" href=\"http://ambiant.earlab.org/css/org.css\" type=\"text/css\"/>
"
	 :auto-index t
	 :table-of-contents t
	 :author "Ioannis Zannos & Aris Bezas"
	 :email  "zannos AT gmail DOT com  & aribezas AT gmail DOT com"
)
	)

;; Copy files from tool to ambiant workshop2011
(add-to-list 'org-publish-project-alist
	'("copy-webtools-files"
	 :base-directory "~/Dropbox/orgshared/sites/org/earlab/tools/webtools/"
	 :base-extension "css\\|js\\|png\\|jpg\\|gif\\|pdf\\|mp3\\|ogg\\|swf\\|zip"
	 :publishing-directory "~/Dropbox/orgshared/sites/html/earlab/tools/webtools/"
	 :recursive t
	 :publishing-function org-publish-attachment
	 )

       )

To define the same project using DynSite one writes the following text in the config.org file which is contained in the folder that holds the org files of he project:

* section-numbers: nil
* table-of-contents: nil
* recursive: t
* headline-levels: 1
* auto-preamble: t
* preamble
<div id="toc">
<a href="http://earlab.org/">Earlab Home</a> | 
<a href="http://earlab.org/tools/webtools">Web Tools Home</a> | 
<a href="http://earlab.org/tools/webtools/gettingstart.html">Getting Started</a> | 
<a href="http://earlab.org/tools/webtools/javascript.html">JavaScript</a> | 
<a href="http://earlab.org/tools/webtools/projects.html">Projects</a> | 
<a href="http://earlab.org/tools/webtools/tutorials.html">Tutorials</a> | 
<a href="http://earlab.org/tools/webtools/topics.html">Topics</a> | 
<a href="http://earlab.org/tools/webtools/links.html">Links</a> | 
</div>
* style
<link rel="stylesheet" href="./css/org.css" type="text/css"/>
* auto-index: t
* table-of-contents: t
* author: "Ioannis Zannos & Aris Bezas"
* email:  "zannos AT gmail DOT com  & aribezas AT gmail DOT com"

Note that the definition of the project is much shorter in config.org, because many items are automatically provided by DynSite based on the location and name of the folder which contains the project:

• The name of the project is provided by the name of the folder that contains the config.org and the org content files.
• The base directory is inferred automatically.
• The publishing directory is inferred automatically.
• The publishing function is provided automatically
• The project for publishing configuration and media files (css, png, mp3, etc) is created automatically

You can add a site to the list of sites as follows (but this will not make it current):

Example:

To add a site and make it current use the function org-install-site as described in the next section.

If a project folder a contains a folder b that defines another project, then the project defined in folder b inherits the properties of project a. The property values set in b overwrite any properties with the same name set by a. b is called a subproject of a, and a is called a superproject of b.

The name of each project is generated from the name of the folder that contains it, and the names of its superprojects, separated by "<". For example, if we have two projects contained in folders like this:

./mainproject ./mainproject/subproject

then the project contained in folder ./mainproject/subproject will be called subproject<mainproject.

For each folder that contains a config.org file, DynSite generates three projects:

1. A project for the org files of the site only. This contains the org files which will be translated to html.
2. A "static" project containing non-org files of the site (css, jpeg, mp3, pdf or other files). These files are simply copied over to the target folder as-is, without any translation.
3. A project including both the org-files and the non-org files.

The non-org file projects are named by appending "-static" to the name of the org project. The projects containing both the org and the non-org files are named by appending "-all" to the name of the org project.

Additionally there are generated 3 project groups: "all", "all-all", and "all-static" that contain all org, static and combined org/static projects of a site. The projects are named after the folder that contains them plus the list of superfolders, so as to be immediately identifiable. For example, the projects of the site defined in folder dynsite-org in the present documentation are:

"all-all"

All projects of the website.

"dynsite-org-all"

All projects of the dynsite project (= top project).

"dynsite-org"

The org files of the dynsite project, that is, the org files, which will be rendered in html.

"dynsite-org-static"

The static project of dynsite, that is, media and other files which are not rendered but only copied.

"subproject<dynsite-org-all"

All files of the project contained in folder subproject.

"subproject<dynsite-org"

Only the org files of the project subproject

"subproject<dynsite-org-static"

Only the static files of the project subproject

The list of known org-publish websites is stored in variable org-sites. This is a list of the form:

((name org-site-root org-site-html org-site-url) (name org-site-root ...) ...) (see above at Installing a Site

Each element of the list has the form (name org-site-root org-site-html org-site-url), where:

• name is the name of the site
• org-site-root is the path of the root folder containing the org files
• org-site-html is the path of the root folder which will hold the exported html files. If it is nil, it is deduced from org-site-root by adding a folder "html" inside the folder org-site-root.
• org-site-url is the root url of the site, used to upload the site files with rsync

The default value of the org-sites list is:

(("default" "~/org" nil "earlabor@earlab.org:~/public_html/org/"))

This means that there is only one default site, named "default".

To add a new site definition to the list of known sites without making it current use the function add-to-list. Example:

(add-to-list 'org-sites '("site2" "~/site2" "~/site2_published" "tomjones@jones.com:~/public_html/"))

To add a site and make it current use the function org-install-site (see above Installing a Site)

1. Type: meta-x org-choose-site
2. Type the "tab" key to show all known sites

Choose a site by typing the initial names of its name and using the tab-key to autocomplete the rest of the name. Then type return to install the chosen site as current.

meta-x org-publish-add-all-files-to-refile-targets

This adds all 1st and 2nd level sections of all files of all projects to refile targets, making them interactively accessible through a list by org-capture-goto-target (control-u control-c control-w).

meta-x org-reset-all-project-files

meta-x org-dired-site

meta-x org-publish-edit-all-configs