xlog

README

XLog

📼 Xlog is a static site generator for digital gardening written in Go. It serves markdown files as HTML and allows editing files online. It focuses on enriching markdown files and surfacing implicit links between pages.

Documentation

• Documentation
• Installation
• Usage
• Generating static site
• Overriding Assets
• Extensions
• Writing Your Own Extension

License

Xlog is released under MIT license

Logo

Cassette tape icons created by Good Ware - Flaticon

Documentation

Index

• Variables
• func Banner(p Page) string
• func Delete(path string, handler HandlerFunc)
• func EachPage(ctx context.Context, f func(Page))
• func Emoji(p Page) string
• func FindAllInAST[t ast.Node](n ast.Node) (a []t)
• func FindInAST[t ast.Node](n ast.Node) (found t, ok bool)
• func Get(path string, handler HandlerFunc)
• func IgnorePath(r *regexp.Regexp)
• func IsFontAwesome(i string) bool
• func IsIgnoredPath(d string) bool
• func Listen(e PageEvent, h PageEventHandler)
• func MapPage[T any](ctx context.Context, f func(Page) T) []T
• func Partial(path string, data Locals) template.HTML
• func Post(path string, handler HandlerFunc)
• func Properties(p Page) map[string]Property
• func RegisterBuildPage(p string, encloseInDir bool)
• func RegisterCommand(c func(Page) []Command)
• func RegisterExtension(e Extension)
• func RegisterHelper(name string, f any) error
• func RegisterJS(f string)
• func RegisterLink(l func(Page) []Command)
• func RegisterPageSource(p PageSource)
• func RegisterPreprocessor(f Preprocessor)
• func RegisterProperty(a func(Page) []Property)
• func RegisterQuickCommand(c func(Page) []Command)
• func RegisterStaticDir(f fs.FS)
• func RegisterTemplate(t fs.FS, subDir string)
• func RegisterWidget(s WidgetSpace, priority float32, f WidgetFunc)
• func RenderWidget(s WidgetSpace, p Page) (o template.HTML)
• func RequireHTMX()
• func Start(ctx context.Context)
• func Trigger(e PageEvent, p Page)
• type Command
  • func Commands(p Page) []Command
  • func Links(p Page) []Command
  • func QuickCommands(p Page) []Command
• type Configuration
• type DynamicPage
  • func (DynamicPage) AST() ([]byte, ast.Node)
  • func (DynamicPage) Content() Markdown
  • func (DynamicPage) Delete() bool
  • func (DynamicPage) Exists() bool
  • func (DynamicPage) FileName() string
  • func (DynamicPage) ModTime() time.Time
  • func (d DynamicPage) Name() string
  • func (d DynamicPage) Render() template.HTML
  • func (DynamicPage) Write(Markdown) bool
• type Extension
• type HandlerFunc
• type Locals
• type Markdown
  • func PreProcess(content Markdown) Markdown
• type Output
  • func BadRequest(msg string) Output
  • func Cache(out Output) Output
  • func InternalServerError(err error) Output
  • func JsonResponse(a any) Output
  • func NoContent() Output
  • func NotFound(msg string) Output
  • func PlainText(text string) Output
  • func Redirect(url string) Output
  • func Render(path string, data Locals) Output
• type Page
  • func NewPage(name string) (p Page)
  • func Pages(ctx context.Context) []Page
• type PageEvent
• type PageEventHandler
• type PageSource
• type Preprocessor
• type Property
• type Request
• type Response
• type WidgetFunc
• type WidgetSpace

Variables

var (

	// a function that returns the CSRF token
	CSRF = csrf.Token
)

var ErrHelperRegistered = errors.New("Helper already registered")

var MarkdownConverter = sync.OnceValue(func() goldmark.Markdown {
	return goldmark.New(
		goldmark.WithExtensions(
			extension.GFM,
			extension.DefinitionList,
			extension.Footnote,
			extension.Typographer,
			highlighting.NewHighlighting(
				highlighting.WithCustomStyle(styles.Get(Config.CodeStyle)),
				highlighting.WithFormatOptions(
					chroma_html.WithLineNumbers(true),
				),
			),
			emoji.Emoji,
		),

		goldmark.WithParserOptions(
			parser.WithAutoHeadingID(),
		),

		goldmark.WithRendererOptions(
			html.WithHardWraps(),
			html.WithUnsafe(),
		),
	)
})

The instance of markdown renderer. this is what takes the page content and converts it to HTML. it defines what features to use from goldmark and what options to turn on

Functions

func Banner

func Banner(p Page) string

func Delete

func Delete(path string, handler HandlerFunc)

Delete defines a new route that gets executed when the request matches path and method is http Delete.

func EachPage

func EachPage(ctx context.Context, f func(Page))

EachPage iterates on all available pages. many extensions uses it to get all pages and maybe parse them and extract needed information

func Emoji

func Emoji(p Page) string

func FindAllInAST

func FindAllInAST[t ast.Node](n ast.Node) (a []t)

Extract all nodes of a specific type from the AST

func FindInAST

func FindInAST[t ast.Node](n ast.Node) (found t, ok bool)

FindInAST takes an AST node and walks the tree depth first searching for a node of a specific type can be used to find first image, link, paragraph...etc

func Get

func Get(path string, handler HandlerFunc)

Get defines a new route that gets executed when the request matches path and method is http Get.

func IgnorePath

func IgnorePath(r *regexp.Regexp)

IgnorePath Register a pattern to be ignored when walking directories.

func IsFontAwesome

func IsFontAwesome(i string) bool

func IsIgnoredPath

func IsIgnoredPath(d string) bool

IsIgnoredPath checks if a file path should be ignored according to the list of ignored paths. page source implementations can use it to ignore files from their sources

func Listen

func Listen(e PageEvent, h PageEventHandler)

Register an event handler to be executed when PageEvent is triggered. extensions can use this to register hooks under specific page events. extensions that keeps a cached version of the pages list for example needs to register handlers to update its cache

func MapPage

func MapPage[T any](ctx context.Context, f func(Page) T) []T

MapPage Similar to EachPage but iterates concurrently and accumulates returns in a slice

func Partial

func Partial(path string, data Locals) template.HTML

Partial executes a template by it's path name. it passes data to the template. returning the output of the template. in case of an error it will return the error string as the output

func Post

func Post(path string, handler HandlerFunc)

Post defines a new route that gets executed when the request matches path and method is http Post.

func Properties

func Properties(p Page) map[string]Property

Properties return a list of properties for a page. It executes all functions registered with RegisterProperty and collect results in one slice. Can be passed to the view to render a page properties

func RegisterBuildPage

func RegisterBuildPage(p string, encloseInDir bool)

RegisterBuildPage registers a path of a page to export when building static version of the knowledgebase. encloseInDir will write the output to p/index.html instead instead of writing to p directly. that can help have paths with no .html extension to be served with the exact name.

func RegisterCommand

func RegisterCommand(c func(Page) []Command)

RegisterCommand registers a new command

func RegisterExtension

func RegisterExtension(e Extension)

func RegisterHelper

func RegisterHelper(name string, f any) error

RegisterHelper registers a new helper function. all helpers are used when compiling templates. so registering helpers function must happen before the server starts as compiling templates happened right before starting the http server.

func RegisterJS

func RegisterJS(f string)

RegisterJS adds a Javascript library URL/path to be included in the scripts used by the template

func RegisterLink

func RegisterLink(l func(Page) []Command)

Register a new links function, should return a list of Links

func RegisterPageSource

func RegisterPageSource(p PageSource)

func RegisterPreprocessor

func RegisterPreprocessor(f Preprocessor)

RegisterPreprocessor registers a Preprocessor function. extensions should use this function to register a preprocessor.

func RegisterProperty

func RegisterProperty(a func(Page) []Property)

RegisterProperty registers a function that returns a set of properties for the page

func RegisterQuickCommand

func RegisterQuickCommand(c func(Page) []Command)

func RegisterStaticDir

func RegisterStaticDir(f fs.FS)

RegisterStaticDir adds a filesystem to the filesystems list scanned for files when serving static files. can be used to add a directory of CSS or JS files by extensions

func RegisterTemplate

func RegisterTemplate(t fs.FS, subDir string)

RegisterTemplate registers a filesystem that contains templates, specifying subDir as the subdirectory name that contains the templates. templates are registered such that the latest registered directory override older ones. template file extensions are signified by '.html' extension and the file path can be used as template name without this extension

func RegisterWidget

func RegisterWidget(s WidgetSpace, priority float32, f WidgetFunc)

RegisterWidget Register a function to a widget space. functions registered will be executed in order of priority lower to higher when rendering view or edit page. the return values of these widgetfuncs will pass down to the template and injected in reserved places.

func RenderWidget

func RenderWidget(s WidgetSpace, p Page) (o template.HTML)

This is used by view and edit routes to render all widgetfuncs registered for specific widget space.

func RequireHTMX

func RequireHTMX()

RequireHTMX registes HTML library, this helps include one version of HTMX

func Start

func Start(ctx context.Context)

Define the catch all HTTP routes, parse CLI flags and take actions like building the static pages and exit, or start the HTTP server

func Trigger

func Trigger(e PageEvent, p Page)

Trigger event handlers for a specific page event. page methods use this function to trigger all registered handlers when the page is edited or deleted for example.

Types

type Command

type Command interface {
	// Icon returns the Fontawesome icon class name for the Command
	Icon() string
	// Name of the command. to be displayed in the list
	Name() string
	// Attrs a map of attributes to their values
	Attrs() map[template.HTMLAttr]any
}

Command defines a structure used for 3 categories of lists: 1. Commands for Ctrl+K actions menu 2. Quick commands displayed in the default template at the top right of the page 3. Links displayed in the navigation bar The template decides where and how to display commands. it can choose to use them in a different way than the default template

func Commands

func Commands(p Page) []Command

Commands return the list of commands for a page. when a page is displayed it executes all functions registered with RegisterCommand and collect all results in one slice. result can be passed to the view to render the commands list

func Links

func Links(p Page) []Command

Links returns a list of links for a Page. it executes all functions registered with RegisterLink and collect them in one slice. Can be passed to the view to render in the footer for example.

func QuickCommands

func QuickCommands(p Page) []Command

QuickCommands return the list of QuickCommands for a page. it executes all functions registered with RegisterQuickCommand and collect all results in one slice. result can be passed to the view to render the Quick commands list

type Configuration

type Configuration struct {
	Source             string // path to markdown files directory
	Build              string // path to write built files
	Readonly           bool   // is xlog in readonly mode
	Sitename           string // name of knowledgebase
	Index              string // name of the index page markdown file
	NotFoundPage       string // name of the index page markdown file
	BindAddress        string // bind address for the server
	ServeInsecure      bool   // should the server use https for cookie
	CodeStyle          string
	CsrfCookieName     string
	DisabledExtensions string
}

var Config Configuration

type DynamicPage

type DynamicPage struct {
	NameVal  string
	RenderFn func() template.HTML
}

DynamicPage implement Page interface and allow extensions to define a page to be passed to templates without having underlying file on desk

func (DynamicPage) AST

func (DynamicPage) AST() ([]byte, ast.Node)

func (DynamicPage) Content

func (DynamicPage) Content() Markdown

func (DynamicPage) Delete

func (DynamicPage) Delete() bool

func (DynamicPage) Exists

func (DynamicPage) Exists() bool

func (DynamicPage) FileName

func (DynamicPage) FileName() string

func (DynamicPage) ModTime

func (DynamicPage) ModTime() time.Time

func (DynamicPage) Name

func (d DynamicPage) Name() string

func (DynamicPage) Render

func (d DynamicPage) Render() template.HTML

func (DynamicPage) Write

func (DynamicPage) Write(Markdown) bool

type Extension

type Extension interface {
	Name() string
	Init()
}

type HandlerFunc

type HandlerFunc func(Request) Output

HandlerFunc is the type of an HTTP handler function + returns output function. it makes it easier to return the output directly instead of writing the output to w then return.

type Locals

type Locals map[string]any // passed to templates

map of string to any value used for template rendering

type Markdown

type Markdown string

Markdown is used instead of string to make sure it's clear the string is markdown string

func PreProcess

func PreProcess(content Markdown) Markdown

This function take the page content and pass it through all registered preprocessors and return the last preprocessor output to the caller

type Output

type Output = http.HandlerFunc

alias of http.HandlerFunc as output is expected from defined http handlers

func BadRequest

func BadRequest(msg string) Output

BadRequest returns an output function that writes BadRequest http response

func Cache

func Cache(out Output) Output

Cache wraps Output and adds header to instruct the browser to cache the output

func InternalServerError

func InternalServerError(err error) Output

InternalServerError returns an output function that writes InternalServerError http response

func JsonResponse

func JsonResponse(a any) Output

func NoContent

func NoContent() Output

NoContent returns an output function that writes NoContent http status

func NotFound

func NotFound(msg string) Output

NotFound returns an output function that writes 404 NotFound to http response

func PlainText

func PlainText(text string) Output

PlainText returns an output function that writes text to response writer

func Redirect

func Redirect(url string) Output

Redirect returns an output function that writes Found http response to provided URL

func Render

func Render(path string, data Locals) Output

Render returns an output function that renders partial with data and writes it as response

type Page

type Page interface {
	// Name returns page name without '.md' extension
	Name() string
	// returns the filename, makes sure it converts slashes to backslashes when
	// needed. this is safe to use when trying to access the file that represent the
	// page
	FileName() string
	// checks if the page underlying file exists on disk or not.
	Exists() bool
	// Renders the page content to HTML. it makes sure all preprocessors are called
	Render() template.HTML
	// Reads the underlying file and returns the content
	Content() Markdown
	// Deletes the file and makes sure it triggers the AfterDelete event
	Delete() bool
	// Overwrite page content with new content. making sure to trigger before and
	// after write events.
	Write(Markdown) bool
	// ModTime Return the last modification time of the underlying file
	ModTime() time.Time
	// Parses the page content and returns the Abstract Syntax Tree (AST).
	// extensions can use it to walk the tree and modify it or collect statistics or
	// parts of the page. for example the following "Emoji" function uses it to
	// extract the first emoji.
	AST() ([]byte, ast.Node)
}

a Type that represent a page.

func NewPage

func NewPage(name string) (p Page)

func Pages

func Pages(ctx context.Context) []Page

type PageEvent

type PageEvent int

a type used to define events to be used when the page is manipulated for example modified, renamed, deleted...etc.

const (
	PageChanged PageEvent = iota
	PageDeleted
	PageNotFound // user requested a page that's not found
)

List of page events. extensions can use these events to register a function to be executed when this event is triggered. extensions that require to be notified when the page is created or overwritten or deleted should register an event handler for the interesting events.

type PageEventHandler

type PageEventHandler func(Page) error

a function that handles a page event. this should be implemented by an extension and then registered. it will get executed when the event is triggered

type PageSource

type PageSource interface {
	// Page takes a page name and return a Page struct
	Page(string) Page
	// Each iterates over all pages in the source
	Each(context.Context, func(Page))
}

type Preprocessor

type Preprocessor func(Markdown) Markdown

A Preprocessor is a function that takes the whole page content and returns a modified version of the content. extensions should define this type and register is so that when page is rendered it will execute all of them in order like a pipeline each function output is passed as an input to the next. at the end the last preprocessor output is then rendered to HTML

type Property

type Property interface {
	// Icon returns the fontawesome icon class name or emoji
	Icon() string
	// Name returns the name of the property
	Name() string
	// Value returns the value of the property
	Value() any
}

Property represent a piece of information about the current page such as last update time, number of versions, number of words, reading time...etc

type Request

type Request = *http.Request

alias *http.Request for shorter handler declaration

type Response

type Response = http.ResponseWriter

alias http.ResponseWriter for shorter handler declaration

type WidgetFunc

type WidgetFunc func(Page) template.HTML

WidgetFunc a function that takes the current page and returns the widget. This can be used by extensions to define new widgets to be rendered in view or edit pages. the extension should define this func type and register it to be rendered in a specific widgetSpace such as before or after the page.

type WidgetSpace

type WidgetSpace string

WidgetSpace used to represent a widgets spaces. it's used to register widgets to be injected in the view or edit pages

var (
	WidgetAfterView  WidgetSpace = "after_view"  // widgets rendered after the content of the view page
	WidgetBeforeView WidgetSpace = "before_view" // widgets rendered before the content of the view page
	WidgetHead       WidgetSpace = "head"        // widgets rendered in page <head> tag
)

List of widgets spaces that extensions can use to register a WidgetFunc to inject content into.