virtual

Documentation

Overview

Package virtual implements a "virtual" view over a fs.FS that makes it suitable for serving Markdown and other files in a web format. It includes a template system and helpers for presenting a nice static web view and an easy-to-maintain format.

A special file "whisper.cfg" at the root exposes settings you can use via the Config() function. This file is hidden from view.

A special folder "template" at the root holds HTML templates should you want to customize. At minimum, a template called "default" is required for handling Markdown files, and a template called "image" is required for handling image files.

Hidden files and folders (those starting with ".") are ignored.

If the above conditions are not met, then the file is provided as-is from the underline file system.

Special File Handling

When an endpoint like "/foo/bar.html" is called and it does not exist, the virtual file system first looks for a Markdown file named "/foo/bar.md". If present, a "virtual" file "/foo/bar.html" is presented that will render the underlying Markdown file into HTML. In this case, the underlying Markdowndown file, "/foo/bar.md", is hidden from view outside of the file system. By default, a template called "default" is used to render the Markdown, unless the front matter of the file specifies a different template.

If a Markdown file is not found, the system will look for an image file (PNG, JPG, WEBP, and GIF). If an image file is found, a virtual file "/foo/bar.html" is created that will render an HTML file using the "image" template. The underlying image file is not hidden, because it needs to be served for the HTML. Note that this special image handling only happens when the top-level folder is one of the following:

"photos", "images", "pictures", "cartoons", "toons", "sketches", "artwork", "drawings"

Site Map

If a file in the root names "sitemap.txt" is present, it will be run as template that can list the files of the site map. This allows you to customize what your site map looks like. The site map receives only the list of file names as a slice of strings.

Front Matter

Markdown files may contain front matter which is in TOML format. The front matter is delimited by "+++"" at the start and end. For example:

+++
# This is my front matter
title = "My glorious page"
+++
# This is my Heading
This is my [Markdown](https://en.wikipedia.org/wiki/Markdown).

Front matter may include:

Name       Type                  Description
---------  -----------------     -----------------------------------------
title         string             Title of page
date          time               Publish date
tags          array of strings   Tags for the articles (not used yet)
template      string             Override the template to render this file
redirect      string             You can use this to issue an HTML meta-tag redirect
originalfile  string             The original filename (markdown or image)

Templates

The system uses standard Go templates from the `html/template` package, and includes two default templates, "default" and "image". Templates are stored in the "template" top-level folder with the extension ".html".

Templates are passed page information (virtual.PageInfo), front matter (virtual.FrontMatter), and rendered HTML from Markdown (template.HTML), and can use these data elements in their processing. Template also make the following helper functions available:

dir(path string) []virtual.File
	Return the contents of the given folder, excluding special files and subfolders
sortbyname([]virtual.File) []virtual.File
	Sort by name (reverse)
sortbytime([]virtual.File) []virtual.File
	Sort by time (reverse)
match(string, ...string) bool
	Match string against file patterns
filter([]virtual.File, ...string) []virtual.File
	Filter list against file patterns
join(parts ...string) string
	The same as path.Join
ext(path string) string
	The same as path.Ext
prev([]virtual.File, string) *virtual.File
	Find the previous file based on Filename
next([]virtual.File, string) *virtual.File
	Find the next file based on Filename
reverse([]virtual.File) []virtual.File
	Reverse the list
trimsuffix(string, string) string
	The same as strings.TrimSuffix
trimprefix(string, string) string
	The same as strings.TrimPrefix
trimspace(string) string
	The same as strings.TrimSpace
markdown(string) template.HTML
	Render Markdown file into HTML
frontmatter(string) *virtual.FrontMatter
	Read front matter from file
now() time.Time
	Current time

Index Files

Most web servers will want to provide an "index.html" file to handle folder roots (like "/articles"). This is handled automatically when using things like http.FileServer if you simply create an "index.md" file to render the "index.html" in the folder.

Errors

To assist web implementations that want to serve a custom file for 404 or 500 errors, you can create a 404.md and 500.md files in the root of the file system. Although the file system will expose these files through the normal "fs" package operations, the sitemap and "dir" template function will not show them, making it straightforward to design your site. The web implementation can request 404.html or 500.html to be served when the file system returns an error or fs.ErrNotExist.

Index

• type Config
• type Duration
  • func (d Duration) MarshalText() (text []byte, err error)
  • func (d Duration) String() string
  • func (d *Duration) UnmarshalText(text []byte) error
• type FS
  • func New(innerFS fs.FS) (*FS, error)
  • func (vfs *FS) Close() error
  • func (vfs *FS) Config() (*Config, error)
  • func (vfs *FS) Open(name string) (fs.File, error)
  • func (vfs *FS) ReloadTemplates(tplReload time.Duration)
• type File
• type FrontMatter
• type PageInfo
  • func (p PageInfo) Pathname() string

Types

type Config

type Config struct {
	Expires       Duration          `toml:"expires"`       // Expiry duration for dynamic content
	StaticExpires Duration          `toml:"staticexpires"` // Expiry duration for static content
	CacheSize     int               `toml:"cachesize"`     // Cache size in megabytes
	CacheDuration Duration          `toml:"cacheduration"` // Cache duration
	Headers       map[string]string `toml:"headers"`       // Headers to add
}

Config contains configuration data from the whisper.cfg file.

type Duration

type Duration time.Duration

func (Duration) MarshalText

func (d Duration) MarshalText() (text []byte, err error)

func (Duration) String

func (d Duration) String() string

func (*Duration) UnmarshalText

func (d *Duration) UnmarshalText(text []byte) error

type FS

type FS struct {
	// contains filtered or unexported fields
}

FS provides a virtual view of the file system suitable for serving Markdown and other files in a web format.

func New

func New(innerFS fs.FS) (*FS, error)

New returns a new FS that presents a virtual view of innerFS.

func (*FS) Close

func (vfs *FS) Close() error

func (*FS) Config

func (vfs *FS) Config() (*Config, error)

Config returns configuration from the whisper.cfg file. It is not an error if the file does not exist.

func (*FS) Open

func (vfs *FS) Open(name string) (fs.File, error)

Open opens the named file.

When Open returns an error, it should be of type *fs.PathError with the Op field set to "open", the Path field set to name, and the Err field describing the problem.

Open should reject attempts to open names that do not satisfy fs.ValidPath(name), returning a *PathError with Err set to ErrInvalid or ErrNotExist.

func (*FS) ReloadTemplates

func (vfs *FS) ReloadTemplates(tplReload time.Duration)

type File

type File struct {
	FrontMatter FrontMatter
	Filename    string
}

File holds data about a page endpoint.

type FrontMatter

type FrontMatter struct {
	Title        string    `toml:"title"`        // Title of this page
	Date         time.Time `toml:"date"`         // Date the article appears
	Template     string    `toml:"template"`     // The name of the template to use
	Tags         []string  `toml:"tags"`         // Tags to assign to this article
	Redirect     string    `toml:"redirect"`     // Issue a redirect to another location
	OriginalFile string    `toml:"originalfile"` // The original file (markdown or image)
}

FrontMatter holds data scraped from a Markdown page.

type PageInfo

type PageInfo struct {
	Path     string // path from URL
	Filename string // end portion (file) from URL
}

PageInfo has information about the current page.

func (PageInfo) Pathname

func (p PageInfo) Pathname() string

Pathname joins the path and filename.