diff --git a/doc/kiln.1.scd b/doc/kiln.1.scd index 7e9b3db..b61f60c 100644 --- a/doc/kiln.1.scd +++ b/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 -: Gemini feed template +| atom.xml +: Atom feed template | output.html : HTML output template -The scope of templates can be limited by placing them in subdirectories of the templates directory. -For example, the template templates/blog/page.gmi will apply to all pages in src/blog. +The scope of a template is limited to the directory it is placed in. +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 - denotes the title of the feed. - +: A list of Atom feeds. Keys denote the path to the feed directory, and values denote the title of the feed. diff --git a/templates.go b/templates.go index 67bf2d3..de147ab 100644 --- a/templates.go +++ b/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("/page.gmi", page_gmi) - t.LoadTemplate("/atom.xml", atom_xml) - t.LoadTemplate("/output.html", output_html) + t.LoadTemplate("/_default/index.gmi", index_gmi) + t.LoadTemplate("/_default/page.gmi", page_gmi) + t.LoadTemplate("/_default/atom.xml", atom_xml) + 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 := filepath.Join(path, tmpl) - if t, ok := t.tmpls[tmplPath]; ok { - return t - } - slash := path == "/" - path = filepath.Dir(path) - if slash && path == "/" { - break - } + tmplPath := pathpkg.Join(path, tmpl) + if t, ok := t.tmpls[tmplPath]; ok { + return t } - return nil + return t.tmpls[pathpkg.Join("/_default", tmpl)] } // Default index template