mkpage

package module
v1.0.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 21, 2023 License: BSD-3-Clause Imports: 20 Imported by: 0

README

MkPage Project

MkPage Project is a collection of tools for rendering static websites. Featured is the mkpage command, a front end to Pandoc (>= v3). Pandoc supports converting from many lightweight markup languages. mkpage supports metadata encoded as JSON front matter[^frontmatter], as well as additional data sources expressed on the command line in a simple command language. Content is rendered using Pandoc's template language.

[^frontmatter]: Front matter in light weight markup languages like Markdown start at the top of the file and begin and end with a simple set of delimiters. JSON front matter uses open and close curly braces are used by JSON.

MkPage Project was inspired by deconstructing more complex content management systems and distilling the rendering functions down to a core set of simple command line tools. It is well suited for building sites hosted on services like GitHub Pages or Amazon's S3. It uses the widely adopted Pandoc as its markup conversion engine and template engine. As such you can create your website using a variety of light weight markup languages such as Markdown, Textile, ReStructureText and Jira's wiki markup.

The MkPage Project's tools can run on machines as small as a Raspberry Pi. Their small foot print and minimal dependencies (only Pandoc) means installation usually boils down to copying the precompiled binaries to a bin directory in your path after a installing Pandoc. Precompiled binaries of MkPage Project are available for Linux, Windows 10 and macOS running on Intel as well as for the ARM7 versions of Raspbian running on Raspberry Pi.

MkPage Project's minimalism is an advantage. It plays nice with the standard suite of text processing tools available with most Unix/POSIX compatible operating systems[^posix]. This makes scripting a MkPage Project using languages like Python, Julia, Lua, Make or Bash straight forward. Each mkpage utility is independent. You can use as few or as many or as few as you like. You determine the workflow and build process that best fits your needs.

[^posix]: Common POSIX compatible systems include macOS, Linux, and recent versions of Windows 10

A quick tour mkpage command

The mkpage command accepts key/value pairs as command line parameters. The pairs can be explicit data types, files on disc or resources from the web. Additionally mkpage will merge in any front matter found in your light weight markup such as Markdown documents. mkpage assembles the all metadata into a JSON structure which will be processed by Pandoc when rendering a Pandoc template. Additionally mkpage understands the Fountain markup language will will handle conversion before passing to onto Pandoc.

mkpage's command language

The "key" in our key/value pairs is used to map into the Pandoc templates you want rendered. If a key was called "content" the template element would be like ${content}. The value of "content" would replace ${content} in the Pandoc template. Pandoc templates can combine logic and iteration to make more complex pages. See the Pandoc User Guide for more details.

On the "value" side of the key/value pair you have strings of one of several formats - plain text, markdown, fountain, ReStructureText, Jira text and JSON. The values can be from explicit strings associated with a data type, data from a file where the file extension identifies the content type, or content retrieved via a URL based on the mime-type sent from the web service. Here's a basic demonstration of sampling of capabilities and integrating data from the NOAA weather website.

Next is an example of a basic Pandoc template followed by an example command line for invoking mkpage.

A basic template

    Date: ${now}
    
    Hello ${name},
        
    The weather forecast is
    
    ${if(weather.data.weather)}
      ${weather.data.weather[; ]}
    ${endif}
    
    Thank you
    
    ${signature}

To render the template above (i.e. weather.tmpl) is expecting values from various data sources broken down as follows.

  • "now" and "name" will be explicit strings
    • "now" integrates getting data from the Unix date command
  • "weather" will come from a URL which returns a JSON document
    • ".data.weather" is the path into the JSON document
  • "signature" will come from a plain text file in your local disc
typing the mkpage command

Here is how we would express the key/value pairs on the command line.

    mkpage "now=text:$(date)" \
        'name=text:Little Frieda' \
        'weather=http://forecast.weather.gov/MapClick.php?lat=13.47190933300044&lon=144.74977715100056&FcstType=json' \
        'signature=examples/signature.txt' \
        'examples/weather.tmpl'

Notice the two explicit strings are prefixed with "text:" (other formats include "markdown:" and "json:"). Values without a prefix are assumed to be local file paths. We see that in testdata/signature.txt is one. Likewise the weather data is coming from a URL identified by the "http:" protocol reference . mkpage uses the "protocol" prefix to distinguish between literals, file paths and URL based based content. "http:" and "https:" returns an HTTP header the header is used to identify the content type for processing by mkpage before handing off to Pandoc. E.g. "Content-Type: text/markdown" tells us to use Pandoc to translate from Markdown to HTML. For data contained in files we rely on the file extension to identify content type, e.g. ".md" is markdown, ".rst" is ReStructureText, ".json" is a JSON document. If no content type is discernible then we assume the content is plain text.

MkPage Project Tools
mkpage

mkpage is a page renderer and front end to Pandoc. It is used to aggregate metadata and templates into a complete website page. It serves as a pre-processor for Markdown, Fountain, ReStructureText, Textile, Jira markup, JSON using Pandoc as conversion and template engine.

blogit

blogit performs two tasks, first if given a filename and date (in YYYY-MM-DD format) blogit will copy the file into an appropriate blog path based on the date provided. The second task it performs is to maintain a blog.json file describing the content of the blog. This is placed in the same folder as the where the year folders for the blog are create.

mkrss

mkrss is an RSS feed generator for content authored in Markdown. It can read a blog.json file created with the blogit and produce an RSS feed from it or scan the directory tree for Markdown files with corresponding HTML files and generate an RSS feed.

frontmatter

frontmatter will extract JSON front matter from a plain text file (e.g. a Markdown document).

byline

byline inside a Markdown file's front matter for a "byline" field and return it before scanning the file using a regular expression for the byline. If nothing is found in either the front matter or the regular expression then it'll return an empty string.

titleline

titleline will look inside a markdown file's front matter for a "title" field it if not present in the front matter it'll look for the h1 demlimiter (Markdown '# ') and return it's content. It will return an empty string if it finds none.

reldocpath

reldocpath is intended to simplify the calculation of relative asset paths (e.g. common CSS files, images, RSS files) when working from a common project directory.

Example reldocpath

You know the path from the source document to target document from the project root folder.

  • Source is course/week/01/readings.html
  • Target is css/site.css.

In Bash this would look like--

    # We know the paths relative to the project directory
    DOC_PATH="course/week/01/readings.html"
    CSS_PATH="css/site.css"
    echo $(reldocpath $DOC_PATH $CSS_PATH)

the output would look like

    ../../../css/site.css
sitemapper

sitemapper a simplistic XML Sitemap generator. Sitemaps are used by web crawls to find content in your website and can help your website be more search-able by modern full text search engines.

ws

ws is a simple static file web server. It is suitable for viewing your local copy of your static website on your machine. It runs with minimal resources and by default will serve content out to the URL http://localhost:8000. It is a fast, small, web server for site development and copyedit work.

Example
    ws Sites/mysite.example.org

This would start the web server up listen for browser requests on http://localhost:8000. The content viewable by your web browser would be the files inside the Sites/mysite.example.org directory.

    ws -url http://mysite.example.org:80 Sites/mysite.example.org

Assume the machine where you are running ws has the name mysite.example.org then your could point your web browser at http://mysite.example.org and see the web content you have in Site/mysite.example.org directory.

Problem Reporting and lending a hand

MkPage project is hosted at GitHub and bugs can be reported via the Issue Tracker. As an open source project pull requests as well as bug reports are appreciated.

Getting your copy of MkPage Project

You can find releases of MkPage Project at github.com/caltechlibrary/mkpage

License

MkPage Project is released under an open source license.

Documentation

Overview

Package mkpage is an experiment in a light weight template and markdown processor.

@author R. S. Doiel, <rsdoiel@caltech.edu>

Copyright (c) 2021, Caltech All rights not granted herein are expressly reserved by Caltech

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Package mkpage codesnip.go - extracts code snippets from markdown

@author R. S. Doiel, <rsdoiel@caltech.edu>

Copyright (c) 2021, Caltech All rights not granted herein are expressly reserved by Caltech

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Package mkpage is an experimental static site generator

@author R. S. Doiel, <rsdoiel@caltech.edu>

Copyright (c) 2021, Caltech All rights not granted herein are expressly reserved by Caltech

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Package mkpage is an experiment in a light weight template and markdown processor.

@author R. S. Doiel, <rsdoiel@caltech.edu>

Copyright (c) 2021, Caltech All rights not granted herein are expressly reserved by Caltech

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Package mkpage is an experimental static site generator

@author R. S. Doiel, <rsdoiel@caltech.edu>

Copyright (c) 2021, Caltech All rights not granted herein are expressly reserved by Caltech

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Package mkpage is an experimental static site generator

@author R. S. Doiel, <rsdoiel@caltech.edu>

Copyright (c) 2021, Caltech All rights not granted herein are expressly reserved by Caltech

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Package mkpage ws.go provides the core library used by cmds/ws/ws.go

@author R. S. Doiel, <rsdoiel@caltech.edu>

Copyright (c) 2021, Caltech All rights not granted herein are expressly reserved by Caltech.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Index

Constants

View Source 
const (

	// JSONPrefix designates a string as JSON formatted content
	JSONPrefix = "json:"
	// CommonMarkPrefix designates a string as Common Mark
	// (a rich markdown dialect) content
	CommonMarkPrefix = "commonmark:"
	// MarkdownPrefix designates a string as Markdown (pandoc's dialect)
	// content
	MarkdownPrefix = "markdown:"
	// MarkdownStrict designates a strnig as John Gruber's Markdown content
	MarkdownStrictPrefix = "markdown_strict:"
	// GfmMarkdownPrefix designates a string as GitHub Flavored Markdown
	GfmMarkdownPrefix = "gfm:"
	// MMarkPrefix designates MMark format, for now this will just be passed to pandoc.
	MMarkPrefix = "mmark:"
	// TextPrefix designates a string as text/plain not needed processing
	TextPrefix = "text:"
	// FountainPrefix designates a string as Fountain formatted content
	FountainPrefix = "fountain:"
	// TextilePrefix designates source as Textile for processing by pandoc.
	TextilePrefix = "textile:"
	// ReStructureText designates source as ReStructureText for processing by pandoc
	ReStructureTextPrefix = "rst:"
	// JiraPrefix markup designates source as Jire text for processing by pandoc
	JiraPrefix = "jira:"
	// JSONGeneratorPrefix evaluates the value as a command line that
	// returns JSON.
	JSONGeneratorPrefix = "json-generator:"

	// DateExp is the default format used by mkpage utilities for date exp
	DateExp = `[0-9][0-9][0-9][0-9]-[0-1][0-9]-[0-3][0-9]`
	// BylineExp is the default format used by mkpage utilities
	BylineExp = (`^[B|b]y\s+(\w|\s|.)+` + DateExp + "$")
	// TitleExp is the default format used by mkpage utilities
	TitleExp = `^#\s+(\w|\s|.)+$`

	// FrontMatterIsUnknown means front matter and we can't parse it
	FrontMatterIsUnknown = iota
	// FrontMatterIsJSON means we have detected JSON front matter
	FrontMatterIsJSON
	// FrontMatterIsPandocMetadata means we have detected a Pandoc
	// style metadata block, e.g. opening lines start with
	// '%' attribute name followed by value(s)
	// E.g.
	//      % title
	//      % author(s)
	//      % date
	FrontMatterIsPandocMetadata
	// FrontMatterIsYAML means we have detected a Pandoc YAML
	// front matter block.
	FrontMatterIsYAML
)
View Source 
const (
	DateFmt = "2006-01-02"
)
View Source 
const (
	// LicenseText provides a string template for rendering cli license info
	LicenseText = `` /* 1530-byte string literal not displayed */

)
View Source 
const Version = "1.0.4"

Variables

View Source 
var (
	// Set a default -f (from) value used by Pandoc
	PandocFrom string
	// Set a default -t (to) value used by Pandoc
	PandocTo string
)
View Source 
var (
	// Config holds a global config.
	// Uses the same structure as Front Matter in that it is
	// the result of parsing TOML, YAML or JSON into a
	// map[string]interface{} tree
	Config map[string]interface{}
)

Functions

func BlogMetaToRSS added in v0.1.1 

func BlogMetaToRSS(blog *BlogMeta, feed *rss2.RSS2) error

Generate a Feed from walking the BlogMeta structure

func Codesnip added in v0.0.21 

func Codesnip(in io.Reader, out io.Writer, language string) error

Codesnip works on io.Reader and ioWriter and string used to identified the langauge. It reads a Markdown block looking for code fenses and snips out the code to write to a file.

func ConfigFountain added in v0.0.28 

func ConfigFountain(config map[string]interface{}) error

ConfigFountain sets the fountain defaults then applies the map[string]interface{} overwriting the defaults returns error necessary.

func GetPandocVersion added in v0.1.1 

func GetPandocVersion() (string, error)

Return the Pandoc version that will be used when calling Pandoc.

func Grep added in v0.0.14 

func Grep(exp string, src string) string

Grep looks for the first line matching the expression in src.

func IsDotPath added in v0.0.13 

func IsDotPath(p string) bool

IsDotPath checks to see if a path is requested with a dot file (e.g. docs/.git/* or docs/.htaccess)

func JSONGenerator added in v0.1.2 

func JSONGenerator(cmdExpr string, obj interface{}) error

JSONGenerator accepts command line string and executes it. It take command's output, validates that it is JSON and returns it.

func LoadBlogMeta added in v0.0.33 

func LoadBlogMeta(fName string, meta *BlogMeta) error

Reads a JSON blog meta document and popualtes a blog meta structure

func MakePandoc added in v0.0.33 

func MakePandoc(wr io.Writer, templateName string, keyValues map[string]string) error

MakePandoc resolves key/value map rendering metadata suitable for processing with pandoc along with template information rendering and returns an error if something goes wrong

func MakePandocString added in v0.2.0 

func MakePandocString(tmplSrc string, keyValues map[string]string) (string, error)

MakePandocString resolves key/value map rendering metadata suitable for processing with pandoc along with template information rendering and returns an error if something goes wrong

func NormalizeDate added in v0.0.14 

func NormalizeDate(s string) (time.Time, error)

NormalizeDate takes a MySQL like date string and returns a time.Time or error

func OpeningParagraphs added in v0.1.1 

func OpeningParagraphs(src string, cnt int, para string) string

OpeningParagraphs scans a Markdown file and attempts to copy the first `cnt` paragraphs ignoring GitHub image inserts. Paragraphs are scanned text followed by a delimiting character, typically that's a two new line sequence.

Example: 

src, _ := ioutil.ReadFile("post.md")
opening := mkpage.OpenParagraphs(fmt.Sprintf("%s", src, "\n\n"), 2)

func PandocBlock added in v0.1.1 

func PandocBlock(src string, from string, to string) string

PandocBlock will attempt to convert a src byte array from one to another formats. If conversion is successful it returns a converted string, if unsuccessful it returns the original byte array as a string.

func ProcessorConfig added in v0.0.28 

func ProcessorConfig(configType int, frontMatterSrc []byte) (map[string]interface{}, error)

ProcessorConfig takes front matter and returns a map[string]interface{} containing configuration NOTE: removed yaml, toml support as of v0.2.4 NOTE: added Pandoc Metadata block as of v0.2.5

func RelativeDocPath added in v0.0.11 

func RelativeDocPath(source, target string) string

RelativeDocPath calculate the relative path from source to target based on implied common base.

Example: 

docPath := "docs/chapter-01/lesson-02.html"
cssPath := "css/site.css"
fmt.Printf("<link href=%q>\n", MakeRelativePath(docPath, cssPath))

Output: 

<link href="../../css/site.css">

func RequestLogger added in v0.0.13 

func RequestLogger(next http.Handler) http.Handler

RequestLogger logs the request based on the request object passed into it.

func ResolveData 

func ResolveData(data map[string]string) (map[string]interface{}, error)

ResolveData takes a data map and reads in the files and URL sources as needed turning the data into strings to be applied to the template.

func ResponseLogger added in v0.0.13 

func ResponseLogger(r *http.Request, status int, err error)

ResponseLogger logs the response based on a request, status and error message

func ShowEnvironment added in v1.0.3 

func ShowEnvironment()

ShowEnvironent writes the contents of the environment to stdout. It is implemented so I can see the environment when mkpage is installed as a snap or in a container.

func SplitFrontMatter added in v0.0.26 

func SplitFrontMatter(input []byte) (int, []byte, []byte)

SplitFrontMatter takes a []byte input splits it into front matter type, front matter source and Markdown source. If either is missing an empty []byte is returned for the missing element. NOTE: removed yaml, toml support as of v0.2.4 NOTE: Added support for Pandoc title blocks v0.2.5

func StaticRouter added in v0.0.13 

func StaticRouter(next http.Handler) http.Handler

StaticRouter scans the request object to either add a .html extension or prevent serving a dot file path

func UnmarshalFrontMatter added in v0.0.33 

func UnmarshalFrontMatter(configType int, src []byte, obj *map[string]interface{}) error

UnmarshalFrontMatter takes a []byte of front matter source and unmarshalls using only JSON frontmatter NOTE: removed yaml, toml support as of v0.2.4 NOTE: Added support for Pandoc title blocks as of v0.2.5

func Walk added in v0.0.14 

func Walk(startPath string, filterFn func(p string, info os.FileInfo) bool, outputFn func(s string, info os.FileInfo) error) error

Walk takes a start path and walks the file system to process Markdown files for useful elements.

func WalkRSS added in v0.1.1 

func WalkRSS(feed *rss2.RSS2, htdocs string, excludeList string, titleExp string, bylineExp string, dateExp string) error

Generate a Feed by walking the file system.

Types

type BlogMeta added in v0.0.33 

type BlogMeta struct {
	Name        string     `json:"name,omitempty"`
	Quip        string     `json:"quip,omitempty"`
	Description string     `json:"description,omitempty"`
	BaseURL     string     `json:"url,omitempty"`
	Copyright   string     `json:"copyright,omitempty"`
	License     string     `json:"license,omitempty"`
	Language    string     `json:"language,omitempty"`
	Started     string     `json:"started,omitempty"`
	Ended       string     `json:"ended,omitempty"`
	Updated     string     `json:"updated,omitempty"`
	IndexTmpl   string     `json:"index_tmpl,omitempty"`
	PostTmpl    string     `json:"post_tmpl,omitempty"`
	Years       []*YearObj `json:"years"`
}

func (*BlogMeta) BlogAsset added in v0.1.1 

func (meta *BlogMeta) BlogAsset(prefix string, fName string, dateString string) error

BlogAsset copies a asset file to the directory as a blog post calculated from prefix and dataString. It is used by BlogIt to copy the Markdown document to the right path.

func (*BlogMeta) BlogIt added in v0.0.33 

func (meta *BlogMeta) BlogIt(prefix string, fName string, dateString string) error

BlogIt is a tool for posting and updating a blog directory structure on local disc. It includes maintaining additional metadata resources to make it easy to script blogsites and podcast sites. @param prefix - a prefix path for the blog (relative to working dir) @param fName - the name of the file to publish to generated blog path @param dateString - A date string used to calculate the blog path, e.g. 

YYYY-MM-DD maps to YYYY/MM/DD.

@returns an error type

func (*BlogMeta) RefreshFromPath added in v0.1.1 

func (meta *BlogMeta) RefreshFromPath(prefix string, year string) error

RefreshFromPath crawls the dircetory tree and rebuilds the `blog.json` file based on what is found. It takes a File extension to target (e.g. .md for Markdown) and analyzes the path for YYYY/MM/DD and transforms the information found into an entry in `blog.json`.

func (*BlogMeta) Save added in v0.0.33 

func (meta *BlogMeta) Save(fName string) error

Save writes a JSON blog meta document

type CreatorObj added in v0.0.33 

type CreatorObj struct {
	ORCID string `json:"orcid,omitempty"`
	Name  string `json:"name,omitempty"`
}

type DayObj added in v0.0.33 

type DayObj struct {
	Day   string     `json:"day"`
	Posts []*PostObj `json:"posts"`
}

type MetadataBlock added in v1.0.0 

type MetadataBlock struct {
	Title   string   `json:"title"`
	Authors []string `json:"authors"`
	Date    string   `json:"date"`
}

MetadataBlock holds the Pandoc style Metadata block delimited by start '%' at the being of the line in the start of a text file.

func (*MetadataBlock) Marshal added in v1.0.0 

func (block *MetadataBlock) Marshal() ([]byte, error)

func (*MetadataBlock) String added in v1.0.0 

func (block *MetadataBlock) String() string

func (*MetadataBlock) Unmarshal added in v1.0.0 

func (block *MetadataBlock) Unmarshal(src []byte) error

type MonthObj added in v0.0.33 

type MonthObj struct {
	Month string    `json:"month"`
	Days  []*DayObj `json:"days"`
}

type PostObj added in v0.0.33 

type PostObj struct {
	Slug        string       `json:"slug"`
	Document    string       `json:"document"`
	Title       string       `json:"title,omitempty"`
	SubTitle    string       `json:"subtitle,omitempty"`
	Byline      string       `json:"byline,omitempty"`
	Series      string       `json:"series,omitempty"`
	Number      string       `json:"number,omitempty"`
	Subject     string       `json:"subject,omitempty"`
	Keywords    []string     `json:"keywords,omitempty"`
	Abstract    string       `json:"abstract,omitempty"`
	Description string       `json:"description,omitempty"`
	Category    string       `json:"category,omitempty"`
	Lang        string       `json:"lang,omitempty"`
	Direction   string       `json:"direction,omitempty"`
	Draft       bool         `json:"draft,omitempty"`
	Creators    []CreatorObj `json:"creators,omitempty"`
	Created     string       `json:"date,omitempty"`
	Updated     string       `json:"updated,omitempty"`
}

type YearObj added in v0.0.33 

type YearObj struct {
	Year   string      `json:"year"`
	Months []*MonthObj `json:"months"`
}

Source Files

View all Source files

Directories

Path Synopsis
cmd
blogit
mkpage is a thought experiment in a light weight template and markup (markdown, fountain) processing.
 mkpage is a thought experiment in a light weight template and markup (markdown, fountain) processing.
byline
byline reads a Markdown file and returns the first byline encountered.
 byline reads a Markdown file and returns the first byline encountered.
frontmatter
frontmatter.go - is a command line tool that reads a Markdown file and returns the frontmatter portion.
 frontmatter.go - is a command line tool that reads a Markdown file and returns the frontmatter portion.
mkpage
mkpage is a thought experiment in a light weight template and markup (markdown, fountain) processing.
 mkpage is a thought experiment in a light weight template and markup (markdown, fountain) processing.
mkrss
mkrss.go is a command line tool for generating an RSS file from a blog directory structure in the form of PATH_TO_BLOG/YYYY/MM/DD/BLOG_ARTICLES.html
 mkrss.go is a command line tool for generating an RSS file from a blog directory structure in the form of PATH_TO_BLOG/YYYY/MM/DD/BLOG_ARTICLES.html
reldocpath
reldocpath.go takes a source document path and a target document path with same base path returning a relative path to the target file.
 reldocpath.go takes a source document path and a target document path with same base path returning a relative path to the target file.
sitemapper
sitemapper generates a sitemap.xml file by crawling the content generate with genpages
 sitemapper generates a sitemap.xml file by crawling the content generate with genpages
titleline
titleine reads a Markdown file and returns the first title encountered.
 titleine reads a Markdown file and returns the first title encountered.
urldecode
urldecode.go is a simple command line utility to decode a string in a URL friendly way.
 urldecode.go is a simple command line utility to decode a string in a URL friendly way.
urlencode
urlencode.go is a simple command line utility to encode a string in a URL friendly way.
 urlencode.go is a simple command line utility to encode a string in a URL friendly way.
ws
ws.go - A simple web server for static files.
 ws.go - A simple web server for static files.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.