Update README.md

README.md

@@ -46,6 +46,29 @@ Page templates are provided with the following information:
 - `Permalink`: Permalink to the page
 - `Content`: The contents of the file (including the title)
 
+Pages can specify dates in their filenames. kiln will recognize the date and
+remove it from the permalink.
+
+Pages can also specify titles in their content. kiln will parse and remove the
+title from the content. Example:
+
+```
+$ cat src/hello-world.gmi
+# Hello, world!
+
+This is some content.
+
+$ cat templates/page.gmi
+Title: {{ .Title }}
+Content:
+{{ .Content }}
+
+$ cat dst/hello-world.gmi
+Title: Hello, world!
+Content:
+This is some content.
+```
+
 ## Directories
 
 Directory templates are provided with the following information:
@@ -55,6 +78,24 @@ Directory templates are provided with the following information:
 - `Pages`: The pages in this directory
 - `Directories`: The subdirectories of this directory
 
+Directory templates are written to `index.gmi` in the corresponding directory.
+Example:
+
+```
+$ ls src/posts/
+src/posts/post-1.gmi
+src/posts/post-2.gmi
+
+$ cat templates/directory.gmi
+{{ range .Pages }}
+=> .Permalink
+{{ end }}
+
+$ cat dst/posts/index.gmi
+=> /posts/post-1.gmi
+=> /posts/post-2.gmi
+```
+
 ## Templates
 
 Templates are located in the `templates` directory.
@@ -63,3 +104,28 @@ There are currently two supported templates:
 
 - `page.gmi`: The template used for pages
 - `directory.gmi`: The template used for directories
+
+If `page.gmi` does not exist, kiln will simply copy pages from source to
+destination. If `directory.gmi` does not exist, directory index files will not
+be created.
+
+## Permalinks
+
+Every page and directory in the site is assigned a path and a permalink.
+
+```
+file:      src/posts/2020-09-22-hello-world.gmi
+path:      posts/2020-09-22-hello-world.gmi
+permalink: /posts/hello-world.gmi
+```
+
+Paths are relative and point to the source file.
+Permalinks are absolute and point to the destination file.
+
+Here is an example of a directory:
+
+```
+directory: src/posts/
+path:      posts
+permalink: /posts/
+```

kiln.go

@@ -10,6 +10,7 @@ import (
 	"time"
 )
 
+// Site represents a kiln site.
 type Site struct {
 	Static    map[string][]byte  // Static files
 	Directory *Directory         // Site directory
@@ -127,6 +128,7 @@ type Page struct {
 
 var titleRE = regexp.MustCompile("^# ?([^#\r\n]+)\r?\n?\r?\n?")
 
+// NewPage returns a new Page with the given path and content.
 func NewPage(path string, content string) *Page {
 	// Try to parse the date from the page filename
 	var date time.Time
@@ -185,7 +187,7 @@ type Directory struct {
 	Index *Page
 }
 
-// NewSection returns a new Section with the given path.
+// NewDirectory returns a new Directory with the given path.
 func NewDirectory(path string) *Directory {
 	var permalink string
 	if path == "" {