xlog

type ASTQueryCache ¶ added in v1.7.10

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

ASTQueryCache provides thread-safe caching for expensive AST-based queries. Extensions can use this to avoid redundant AST parsing when computing aggregate data across multiple pages.

func NewASTQueryCache() *ASTQueryCache

func (c *ASTQueryCache) Get(key string, compute func() any) any

func (c *ASTQueryCache) Invalidate(key string)

func (c *ASTQueryCache) InvalidateAll()

type BrokenLink ¶ added in v1.7.10

type BrokenLink struct {
	SourcePage      string // Page containing the broken link
	TargetPage      string // Referenced page that doesn't exist
	LinkDestination string // Original link text
}

BrokenLink represents a broken internal link found in a page.

func FindBrokenLinks(ctx context.Context) []BrokenLink

type Command ¶ added in v0.27.0

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(p Page) []Command

func Links(p Page) []Command

func QuickCommands(p Page) []Command

type Configuration ¶ added in v1.7.0

type Configuration struct {
	Source             string // path to markdown files directory
	Build              string // path to write built files
	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
	Theme              string // empty switches between light/dark. setting it forces a theme
	CodeStyle          string
	CsrfCookieName     string
	DisabledExtensions string
	Completion         string // shell to generate completion script for
	Readonly           bool   // is xlog in readonly mode
	ServeInsecure      bool   // should the server use https for cookie
	RunDoctor          bool   // run configuration diagnostics
	ShowVersion        bool   // display version information and exit
	ListPages          bool   // list all pages and exit
	ShowStats          bool   // display digital garden statistics and exit
	ExportJSON         bool   // export page metadata as JSON and exit
}

var Config Configuration

type DiagnosticResult ¶ added in v1.7.10

type DiagnosticResult struct {
	Issues   []string
	Warnings []string
}

DiagnosticResult holds the results of running diagnostics.

func (d DiagnosticResult) HasCriticalIssues() bool

func (d DiagnosticResult) IsHealthy() bool

type DuplicatePair ¶ added in v1.7.10

type DuplicatePair struct {
	Page1      string
	Page2      string
	Similarity float64
}

DuplicatePair represents two pages with duplicate or highly similar content.

type DynamicPage ¶ added in v1.7.0

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() ([]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 ¶ added in v1.7.0

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

type GardenStats ¶ added in v1.7.10

type GardenStats struct {
	TotalPages      int
	TotalWords      int
	AvgWordsPerPage int
	TotalLinks      int
	OrphanedPages   int
	HubPages        []string
}

GardenStats holds statistics about the digital garden.

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 ¶ added in v0.45.0

type Markdown string

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

func PreProcess(content Markdown) Markdown

type Output ¶

type Output = http.HandlerFunc

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

func Accepted() Output

func BadRequest(msg string) Output

func Cache(out Output) Output

func Created(location string) Output

func Forbidden(msg string) Output

func InternalServerError(err error) Output

func JsonResponse(a any) Output

func MethodNotAllowed(msg string) Output

func NoCache(out Output) 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

func Unauthorized(msg string) Output

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(name string) (p Page)

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
)

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 PageMetadata ¶ added in v1.7.10

type PageMetadata struct {
	Name      string    `json:"name"`
	Path      string    `json:"path"`
	ModTime   time.Time `json:"mod_time"`
	WordCount int       `json:"word_count"`
	Links     []string  `json:"links"`
}

PageMetadata represents exported page information in JSON format.

type PageSource ¶ added in v0.80.0

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 ¶ added in v0.22.0

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 ¶ added in v0.36.0

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 ¶ added in v0.54.0

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 ¶ added in v0.54.0

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
)