Allow overriding the default templates

doc/kiln.1.scd

@@ -28,6 +28,8 @@ A kiln site is structured in the following way:
 |  html/
 :  Site HTML destination
 
+Any file or directory whose name begins with "\_" will be ignored.
+
 # TEMPLATES
 
 kiln looks for templates in the *templates* directory.
@@ -39,13 +41,15 @@ The following templates are supported:
 :  Page template
 |  index.gmi
 :  Directory index template
-|  feed.gmi
+|  atom.xml
-:  Gemini feed template
+:  Atom feed template
 |  output.html
 :  HTML output template
 
-The scope of templates can be limited by placing them in subdirectories of the templates directory.
+The scope of a template is limited to the directory it is placed in.
-For example, the template templates/blog/page.gmi will apply to all pages in src/blog.
+For example, the template templates/blog/page.gmi will only apply to pages in src/blog.
+
+kiln has default templates built-in. To override the default templates, put templates in the templates/\_default directory. These templates will apply to any directory which does not have its own templates specified.
 
 ## FUNCTIONS
 
@@ -63,7 +67,11 @@ Site metadata contains the following information:
 [[ *Variable*
 :[ *Description*
 |  Title
-:  The title of the site, which can be specified in the site configuration.
+:  The title of the site.
+|  URL
+:  The URL of the site.
+
+To configure these variables, see *CONFIGURATION*.
 
 ## PAGE TEMPLATES
 
@@ -107,9 +115,11 @@ Index templates are provided with the following information:
 The title and content are taken from the index.gmi file in the directory.
 If no index.gmi file exists, then the index template will not be rendered.
 
+The default index template implements the lightweight subscription specification found at gemini://gemini.circumlunar.space/docs/companion/subscription.gmi.
+
 ## FEED TEMPLATES
 
-Feed templates are provided with the following information:
+Atom feed templates are provided with the following information:
 
 [[ *Variable*
 :[ *Description*
@@ -118,7 +128,7 @@ Feed templates are provided with the following information:
 |  Path
 :  Path to the feed directory
 |  Entries
-:  List of feed entries
+:  List of pages in this feed
 
 Feeds are written to the directory path plus "feed".
 
@@ -136,19 +146,24 @@ HTML output templates are provided with the following information:
 # CONFIGURATION
 
 kiln looks for a configuration file named "config.ini".
+
 The configuration file uses the _ini_ format.
+A line beginning with ";" is considered a comment and ignored, as are empty lines.
+New sections begin with [section-name] on a single line.
+Keys and values are separated with "=".
+
 The following keys are supported:
 
 [[ *Key*
 :[ *Description*
 |  title
 :  Site title
+|  url
+:  Site URL. Should not end with a trailing slash.
 
 The following sections are supported:
 
 [[ *Section*
 :[ *Description*
 |  feeds
-:  A list of feeds. Each key denotes a path to a directory, and each value
+:  A list of Atom feeds. Keys denote the path to the feed directory, and values denote the title of the feed.
-   denotes the title of the feed.
-

templates.go

@@ -3,6 +3,7 @@ package main
 import (
 	"io/ioutil"
 	"os"
+	pathpkg "path"
 	"path/filepath"
 	"strings"
 	"text/template"
@@ -30,10 +31,10 @@ func (t *Templates) Funcs(funcs template.FuncMap) {
 // LoadDefault loads the default templates.
 // Should be called after Funcs.
 func (t *Templates) LoadDefault() {
-	t.LoadTemplate("/index.gmi", index_gmi)
+	t.LoadTemplate("/_default/index.gmi", index_gmi)
-	t.LoadTemplate("/page.gmi", page_gmi)
+	t.LoadTemplate("/_default/page.gmi", page_gmi)
-	t.LoadTemplate("/atom.xml", atom_xml)
+	t.LoadTemplate("/_default/atom.xml", atom_xml)
-	t.LoadTemplate("/output.html", output_html)
+	t.LoadTemplate("/_default/output.html", output_html)
 }
 
 // LoadTemplate loads a template from the provided path and content.
@@ -63,20 +64,13 @@ func (t *Templates) Load(dir string) error {
 	})
 }
 
-// FindTemplate searches recursively for a template for the given path.
+// FindTemplate returns a template for the given path, or the default template if it does not exist.
 func (t *Templates) FindTemplate(path string, tmpl string) *template.Template {
-	for {
+	tmplPath := pathpkg.Join(path, tmpl)
-		tmplPath := filepath.Join(path, tmpl)
+	if t, ok := t.tmpls[tmplPath]; ok {
-		if t, ok := t.tmpls[tmplPath]; ok {
+		return t
-			return t
-		}
-		slash := path == "/"
-		path = filepath.Dir(path)
-		if slash && path == "/" {
-			break
-		}
 	}
-	return nil
+	return t.tmpls[pathpkg.Join("/_default", tmpl)]
 }
 
 // Default index template