Documentation
¶
Overview ¶
Package page defines a single page in a Kisipar web site.
Example ¶
package main
import (
"fmt"
"github.com/biztos/kisipar/page"
)
func main() {
// Most common use case: load a Markdown file using the default parser.
p, err := page.Load("example.md")
if err != nil {
panic(err)
}
fmt.Println("Title:", p.Title())
fmt.Println("Author:", p.Author())
fmt.Println("Hamand:", p.MetaString("Hamand"))
fmt.Println(p.Content)
}
Output: Title: Example Kisipar Page Author: Thelonius Mönch Hamand: EGGS! <h1>Example Kisipar Page</h1> <h2>Welcome to the Example Page!</h2> <p>A paragraph is all you need.</p>
Index ¶
- Variables
- func LimitExtParsers(extlist []string)
- type ExtParser
- type MdParser
- type Page
- func (p *Page) Author() string
- func (p *Page) Created() *time.Time
- func (p *Page) Description() string
- func (p *Page) Keywords() string
- func (p *Page) Load() error
- func (p *Page) MetaBool(key string) bool
- func (p *Page) MetaString(key string) string
- func (p *Page) MetaStringArray(key string) []string
- func (p *Page) MetaTime(key string) *time.Time
- func (p *Page) Parse() error
- func (p *Page) Refresh() error
- func (p *Page) String() string
- func (p *Page) Summary() string
- func (p *Page) Tags() []string
- func (p *Page) Time() *time.Time
- func (p *Page) Title() string
- func (p *Page) Updated() *time.Time
- type ParseResult
- type Parser
- type StringArrayer
- type VerbatimParseResult
- type VerbatimParser
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ExtParsers = []*ExtParser{ {".md", &MdParser{}}, {".MD", &MdParser{}}, {".markdown", &MdParser{}}, {".MARKDOWN", &MdParser{}}, {".txt", &MdParser{}}, {".TXT", &MdParser{}}, }
ExtParsers defines the parsers that will be used for various extensions in Load and LoadVirtual. Note that extensions are matched case-insensitively, but LoadAny is case-sensitive; thus if you specifically expecte to look up a particular cased extension (".Txt" for instance) then you need to set that up here in ExtParsers.
The standard values should be sufficient for any normal Kisipar site.
Functions ¶
func LimitExtParsers ¶
func LimitExtParsers(extlist []string)
LimitExtParsers removes any ExtParser entries from ExtParsers not matching the provided set of extensions, putting the resulting ExtParsers in the order of the extlist received. This is useful for keeping the behavior of LoadAny in sync with any site-wide preload operations.
Note that this is destructive: once limited, the original set of ExtParsers is gone.
Types ¶
type MdParser ¶
type MdParser struct{}
MdParser is the standard Markdown parser, using the frostedmd parsing logic based on blackfriday.
type Page ¶
type Page struct {
// The data source:
Path string // path as loaded; arbitrary unique for Virtual pages.
Virtual bool // does the Page exist on disk?
Unlisted bool // should the Page be included in site listings?
IsIndex bool // is the page an Index?
ModTime time.Time // file mod time; instantiation time for Virtual.
Source []byte // raw, unparsed source data.
// The standard rendered HTML content:
Content template.HTML
// The data extracted from the meta block:
Meta map[string]interface{}
// contains filtered or unexported fields
}
A Page represents a single page, to be rendered in a template. Pages should be created with New, Load or LoadVirtual.
func Load ¶
Load loads a page and parses it using the Parser associated with its extension in ExtParsers.
func LoadAny ¶
LoadAny loads the first page it finds for the source path with an extension listed in ExtParsers. Extensions are matched exactly, meaning that ExtParsers must have entries of every supported extension case.
func LoadVirtual ¶
LoadVirtual returns a page with a virtual path, i.e. not necessarily corresponding to any file on disk. The provided path should indicate the source type, e.g. "virtual/document.md" for Markdown.
func LoadVirtualString ¶
LoadVirtualString is shorthand for LoadVirtual(path,[]byte(string).
func New ¶
New returns a Page with source loaded from the provided path, but not yet parsed. The path must have an extension.
func (*Page) Author ¶
Author returns the Author string from the Page's Meta block. Author is simply shorthand for MetaString("Author").
func (*Page) Created ¶
Created returns the page's creation time as defined in the meta. Created is simply shorthand for MetaTime("Created").
func (*Page) Description ¶
Description returns the Description string from the Page's Meta block. Description is simply shorthand for MetaString("Description").
func (*Page) Keywords ¶
Keywords returns the Keywords string from the Page's Meta block. (Keywords are generally used in the HTML meta elements, which is why this is a string and not a []string. For an array, use Tags.) Keywords is simply shorthand for MetaString("Keywords").
func (*Page) MetaBool ¶
MetaBool returns a boolean value from the Page's Meta block, with undefined and non-boolean values treated as false. If there is no match for the exact key, lookup is attempted on the lowercase and uppercase versions, in that order.
func (*Page) MetaString ¶
MetaString returns a string value from the Meta, with non-string values stringified. If there is no match for the exact key, lookup is attempted on the lowercase and uppercase versions, in that order. If there is no value for the key in any form, the empty string is returned. Thus MetaString should not be used to determine the presence of a key, only in cases where an empty string and nil/not-found have identical meaning.
func (*Page) MetaStringArray ¶
MetaStringArray returns an array of string values from the Meta, or an empty array if there is value for the key. If the value is already a []string, it is returned as-is. If the value is a string, it is split with a comma delimiter and the resulting items are trimmed of leading and trailing spaces. If the value is an array of integers or floats then its contents are stringified. For any type that implements the StringArrayer interface, the result of its StringArray function is returned. All other types return an empty array. Key lookup follows the logic of MetaString.
func (*Page) MetaTime ¶
MetaTime returns a time value from the Meta, if the requested key holds a string value that can be parsed into a time. Nil is returned in all other cases.
func (*Page) Parse ¶
Parse parses the Page's Source data into Meta and Content using the first Parser in ExtParsers to match the Page's Path extension, or the DefaultParser if none matches. Extension matching is case-insensitive.
If the Meta defines a boolean "Unlisted" (or "unlisted" or "UNLISTED") with a value of true, the Page's Unlisted property is set to true.
func (*Page) Refresh ¶
Refresh reloads the page if it is not Virtual and the modtime of the source file is different than the current ModTime. In case of file errors, including not-found, the error will be returned without the page being modified, and the caller must handle the error.
func (*Page) String ¶
String returns a hopefully-useful stringification of the page, for logging and debugging purposes.
func (*Page) Summary ¶
Summary returns the Summary string from the Page's Meta block. Summary is simply shorthand for MetaString("Summary").
func (*Page) Tags ¶
Tags returns a list of tags from the Page's Meta block, as an array of strings. This is normally defined in the meta as either an array of strings directly, or a comma-delimited list in string form such as "foo, bar, baz" -- this function supports both forms within the Meta map but the implmentation is up to the Parser. Tags is simply shorthand for MetaStringArray("Tags")
func (*Page) Time ¶
Time returns the newer of the page's Created and Updated meta times; if neither is set or neither is parseable, returns the ModTime.
type ParseResult ¶
The ParseResult interface defines a struct representing a Parser's Parse output.
type Parser ¶
type Parser interface {
Parse([]byte) (ParseResult, error)
}
The Parser interface defines a struct capable of parsing source data into a meta map and HTML content.
var DefaultParser Parser = &VerbatimParser{}
DefaultParser defines the Parser to use if no more specific Parser is available.
type StringArrayer ¶
type StringArrayer interface {
StringArray() []string
}
The StringArrayer interface enables custom types, usually named array types, to generate string arrays via MetaStringArray.
type VerbatimParseResult ¶
type VerbatimParseResult struct {
// contains filtered or unexported fields
}
VerbatimParseResult is the result of a verbatim parse.
func (*VerbatimParseResult) Content ¶
func (vpr *VerbatimParseResult) Content() []byte
Content implements the ParseResult interface for the VerbatimParseResult type.
func (*VerbatimParseResult) Meta ¶
func (vpr *VerbatimParseResult) Meta() map[string]interface{}
Meta implements the ParseResult interface for the VerbatimParseResult type.
type VerbatimParser ¶
type VerbatimParser struct{}
VerbatimParser is a parser that simply returns its input with an empty meta map.
func (*VerbatimParser) Parse ¶
func (v *VerbatimParser) Parse(b []byte) (ParseResult, error)
Parse implements the Parser interface for the VerbatimParser type.
Source Files