xlog

README

XLog

Local-first personal knowledge management application with focus on enriching markdown files and surfacing implicit links between pages.

Core Features

• Uses any directory of markdown files
• Supports Github flavor markdown (GFM)
• One statically compiled binary
• template.md content will be used for new pages
• Support for nested directories (although not favored)
• Has a list of tools defined by extensions
• Add image to the start of a page to make it a cover photo
• A web server with a very small footprint thanks to Go.
• Minimal third party dependencies
• The first Emoji used in the page will be considered the icon of the page and displayed beside the title
• Shows task list (Done/Total tasks) beside page link (auto links)

Extensions

Extensions are defined under /extensions sub package. each extension is a subpackage. importing the package in cmd/xlog/xlog.go has the side effect of registering the extension hooks. removing the extension from the list of imports will removing the features it provides.

Extension	Description
Autolink	Shorten a link string so it wouldn't take unnecessary space
Autolink pages	Convert a page name mentions in the middle of text to a link
Emoji	Emoji autocomplete while editing
File operations	Add a tool item to delete and rename current page
Hashtags	Add support for hashtags #hashtag syntax
Link preview	Preview tweets, Facebook posts, youtube videos, Giphy links
Opengraph	Adds Opengraph meta tags for title, type, image
Recent	Adds an item to sidebar to list all pages ordered by last modified page file.
Search	Full text search
Shortcode	adds a way for short codes (one line and block)
Star	Star pages to pin them to sidebar
Upload file	Add support for upload files, screenshots, audio and camera recording
Versions	Keeps list of pages older versions
Manifest	adds manifest.json to head tag and output proper JSON value.

Installation

go install github.com/emad-elsaid/xlog/cmd/xlog@latest

Usage

Usage of xlog:
  -bind string
        IP and port to bind the web server to (default "127.0.0.1:3000")
  -build string
        Build all pages as static site in this directory
  -index string
        Index file name used as home page (default "index")
  -readonly
        Should xlog hide write operations, read-only means all write operations will be disabled
  -sidebar
        Should render sidebar. (default true)
  -sitename string
        Site name is the name that appears on the header beside the logo and in the title tag (default "XLOG")
  -source string
        Directory that will act as a storage (default current directory)

Now you can access xlog with localhost:3000

Generating static site

I used Xlog to generate my personal blog. it uses github workflow to do that here is an example.

Overriding Assets

assets is served from public directory if it exists in the source directory. otherwise the default assets are served from xlog binary. any file under public that has the same name as the ones xlog uses will be used instead of the default files.

License

Xlog is released under MIT license

Logo

Cassette tape icons created by Good Ware - Flaticon

Screenshots

Documentation

Index

• Constants
• Variables
• func AUTOCOMPLETE(a Autocompleter)
• func EXTENSION_PAGE(p string)
• func ExtractAllFromAST[t ast.Node](n ast.Node, kind ast.NodeKind) (a []t)
• func ExtractFirstFromAST[t ast.Node](n ast.Node, kind ast.NodeKind) (found t, ok bool)
• func HELPER(name string, f interface{})
• func IGNORE_DIR(r *regexp.Regexp)
• func Listen(e PageEvent, h PageEventHandler)
• func Log(level, label, text string, args ...interface{}) func()
• func NoContent(w http.ResponseWriter, r *http.Request)
• func PREPEND_WIDGET(s widgetSpace, f func(*Page, Request) template.HTML)
• func PREPROCESSOR(f PreProcessor)
• func Partial(path string, data Locals) string
• func RenderWidget(s widgetSpace, p *Page, r Request) (o template.HTML)
• func Start()
• func Trigger(e PageEvent, p *Page)
• func VIEW(view fs.FS)
• func Vars(r Request) map[string]string
• func WIDGET(s widgetSpace, f func(*Page, Request) template.HTML)
• func WalkPages(ctx context.Context, f func(*Page))
• type Autocomplete
• type Autocompleter
• type HandlerFunc
• type Locals
• type Output
  • func BadRequest(msg string) Output
  • func InternalServerError(err error) Output
  • func NotFound(msg string) Output
  • func PlainText(text string) Output
  • func Redirect(url string) Output
  • func Render(path string, data Locals) Output
  • func Unauthorized(msg string) Output
• type Page
  • func NewPage(name string) Page
  • func (p *Page) AST() ast.Node
  • func (p *Page) Content() string
  • func (p *Page) Delete() bool
  • func (p *Page) Emoji() string
  • func (p *Page) Exists() bool
  • func (p *Page) FileName() string
  • func (p *Page) ModTime() time.Time
  • func (p *Page) Render() string
  • func (p *Page) Write(content string) bool
• type PageEvent
• type PageEventHandler
• type PreProcessor
• type Request
• type Response
• type Route
  • func DELETE(path string, handler HandlerFunc, ...) Route
  • func GET(path string, handler HandlerFunc, ...) Route
  • func POST(path string, handler HandlerFunc, ...) Route
  • func ROUTE(route http.HandlerFunc, checks ...RouteCheck) Route
• type RouteCheck
• type Suggestion

Constants

const (
	PUBLIC_PATH      = "public"
	VIEWS_EXTENSION  = ".html"
	CSRF_COOKIE_NAME = "xlog_csrf"
)

const (
	DEBUG = "\033[97;42m"
	INFO  = "\033[97;42m"
)

const (
	TOOLS_WIDGET widgetSpace = iota
	SIDEBAR_WIDGET
	AFTER_VIEW_WIDGET
	ACTION_WIDGET
	HEAD_WIDGET
)

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

Variables

var (
	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
	SIDEBAR  bool   // is sidebar displayed
	INDEX    string // name of the index page markdown file
	TEMPLATE string // name of the template file used as default value for editor
)

var (

	// a function that renders CSRF hidden input field
	CSRF = csrf.TemplateField
)

var MarkDownRenderer = goldmark.New(
	goldmark.WithExtensions(
		extension.GFM,
		extension.DefinitionList,
		extension.Footnote,
		highlighting.Highlighting,
		emoji.Emoji,
	),

	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 AUTOCOMPLETE

func AUTOCOMPLETE(a Autocompleter)

this function registers an autocompleter function. it should be used by an extension to register a new autocompleter function. these functions are going to be executed when rendering the edit page.

func EXTENSION_PAGE

func EXTENSION_PAGE(p string)

EXTENSION_PAGE announces a path of a page as an extension page, enables the page to be exported when building static version of the knowledgebase

func ExtractAllFromAST

func ExtractAllFromAST[t ast.Node](n ast.Node, kind ast.NodeKind) (a []t)

Extract all nodes of a specific type from the AST

func ExtractFirstFromAST

func ExtractFirstFromAST[t ast.Node](n ast.Node, kind ast.NodeKind) (found t, ok bool)

This is a function that takes an AST node and walks the tree depth first recursively calling itself in search for a node of a specific kind can be used to find first image, link, paragraph...etc

func HELPER

func HELPER(name string, f interface{})

HELPER registers a new helper function. all helpers are used when compiling view/templates so registering helpers function must happen before the server starts as compiling views happend right before starting the http server.

func IGNORE_DIR

func IGNORE_DIR(r *regexp.Regexp)

Register a pattern to be ignored when walking directories.

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 Log

func Log(level, label, text string, args ...interface{}) func()

func NoContent

func NoContent(w http.ResponseWriter, r *http.Request)

NoContent an output function that writes NoContent http response

func PREPEND_WIDGET

func PREPEND_WIDGET(s widgetSpace, f func(*Page, Request) template.HTML)

Register widget function to be rendered in a specific space before any other widget. functions registered by this function will have higher priority than the rest. this function is needed for example to register the search input before any other links in the sidebar

func PREPROCESSOR

func PREPROCESSOR(f PreProcessor)

Register a PREPROCESSOR function. extensions should use this function to register a preprocessor.

func Partial

func Partial(path string, data Locals) string

func RenderWidget

func RenderWidget(s widgetSpace, p *Page, r Request) (o template.HTML)

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

func Start

func Start()

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.

func VIEW

func VIEW(view fs.FS)

VIEW registers a filesystem as a view, views are registered such that the latest view directory override older ones. views file extensions are signified by VIEWS_EXTENSION constant and the file path can be used as template name without this extension

func Vars

func Vars(r Request) map[string]string

func WIDGET

func WIDGET(s widgetSpace, f func(*Page, Request) template.HTML)

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

func WalkPages

func WalkPages(ctx context.Context, f func(*Page))

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

Types

type Autocomplete

type Autocomplete struct {
	StartChar   string
	Suggestions []*Suggestion
}

Autocomplete defines what character triggeres the autocomplete feature and what is the list to display in this case.

type Autocompleter

type Autocompleter func() *Autocomplete

This is a function that returns an auto completer instance. this function should be defined by extensions and registered to be executed when rendering the edit page

type HandlerFunc

type HandlerFunc func(http.ResponseWriter, *http.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]interface{} // passed to views/templates

Some aliases to make it easier

type Output

type Output = http.HandlerFunc

Some aliases to make it easier

func BadRequest

func BadRequest(msg string) Output

BadRequest returns an output function that writes BadRequest http response

func InternalServerError

func InternalServerError(err error) Output

InternalServerError returns an output function that writes InternalServerError http response

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

func Unauthorized

func Unauthorized(msg string) Output

Unauthorized returns an output function that writes Unauthorized http response

type Page

type Page struct {
	Name string // page name without '.md' extension
	// contains filtered or unexported fields
}

a Type that represent a page.

func NewPage

func NewPage(name string) Page

Create an instance of Page with name. if no name is passed it's assumed "index"

func (*Page) AST

func (p *Page) AST() ast.Node

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.

func (*Page) Content

func (p *Page) Content() string

Reads the underlying file and returns the content

func (*Page) Delete

func (p *Page) Delete() bool

Deletes the file and makes sure it triggers the AfterDelete event

func (*Page) Emoji

func (p *Page) Emoji() string

Returns the first emoji of the page.

func (*Page) Exists

func (p *Page) Exists() bool

checks if the page underlying file exists on disk or not.

func (*Page) FileName

func (p *Page) FileName() 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

func (*Page) ModTime

func (p *Page) ModTime() time.Time

Return the last modification time of the underlying file

func (*Page) Render

func (p *Page) Render() string

Renders the page content to HTML. it makes sure all preprocessors are called

func (*Page) Write

func (p *Page) Write(content string) bool

Overwrite page content with new content. making sure to trigger before and after write events.

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 (
	BeforeWrite PageEvent = iota
	AfterWrite
	AfterDelete
)

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 PreProcessor

type PreProcessor func(string) string

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 Request

type Request = *http.Request

Some aliases to make it easier

type Response

type Response = http.ResponseWriter

Some aliases to make it easier

type Route

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

func DELETE

func DELETE(path string, handler HandlerFunc, middlewares ...func(http.HandlerFunc) http.HandlerFunc) Route

DELETE defines a new route that gets executed when the request matches path and method is http DELETE. the list of middlewares are executed in order

func GET

func GET(path string, handler HandlerFunc, middlewares ...func(http.HandlerFunc) http.HandlerFunc) Route

GET defines a new route that gets executed when the request matches path and method is http GET. the list of middlewares are executed in order

func POST

func POST(path string, handler HandlerFunc, middlewares ...func(http.HandlerFunc) http.HandlerFunc) Route

POST defines a new route that gets executed when the request matches path and method is http POST. the list of middlewares are executed in order

func ROUTE

func ROUTE(route http.HandlerFunc, checks ...RouteCheck) Route

ROUTE Adds a new HTTP handler function to the list of routes with a list of checks functions. the list of checks are executed when a request comes in if all of them returned true the handler function gets executed.

type RouteCheck

type RouteCheck func(Request) (Request, bool)

type Suggestion

type Suggestion struct {
	Text        string // The text that gets injected in the editor if this option is choosen
	DisplayText string // The display text for this item in the menu. this can be more cosmetic.
}

Suggestions represent an item in the list of autocomplete menu in the edit page