builtin

Documentation

Overview

Package builtin provides embedded documentation that can be deployed as a regular project.

Index

• Constants
• Variables
• func ConvertToHTML(mdContent []byte, nav []DocEntry, currentPath, basePath string) ([]byte, error)
• func GetDocsFS() fs.FS
• func GetIndexContent() ([]byte, error)
• func GetProjectSlug() string
• func GetTitle(content []byte, fallback string) string
• func HasFile(path string) bool
• func IsBuiltinDocsProject(slug string) bool
• func ListMarkdownFiles() ([]string, error)
• func MustReadFile(path string) []byte
• func NormalizePath(path string) string
• func ReadMarkdown(path string) ([]byte, error)
• func TransformMarkdownLinks(content []byte) []byte
• func ValidateDocs() error
• type Deployer
  • func (d *Deployer) Deploy(ctx context.Context, userID int64) error
• type DocEntry
  • func ParseDocTree() ([]DocEntry, error)
• type MissingDocsError
  • func (e *MissingDocsError) Error() string
• type PageData

Constants

const (
	// ProjectSlug is the slug used for the built-in docs project.
	ProjectSlug = "asiakirjat-docs"
	// ProjectName is the display name for the built-in docs project.
	ProjectName = "Asiakirjat Documentation"
	// ProjectDescription is the description for the built-in docs project.
	ProjectDescription = "Built-in documentation for Asiakirjat"
)

Variables

var Version = "dev"

Version is the application version, set from main.go via ldflags.

Functions

func ConvertToHTML

func ConvertToHTML(mdContent []byte, nav []DocEntry, currentPath, basePath string) ([]byte, error)

ConvertToHTML converts markdown content to a full HTML page with navigation.

func GetDocsFS

func GetDocsFS() fs.FS

GetDocsFS returns the embedded documentation filesystem.

func GetIndexContent

func GetIndexContent() ([]byte, error)

GetIndexContent returns the index.md content.

func GetProjectSlug

func GetProjectSlug() string

GetProjectSlug returns the slug for the built-in docs project.

func GetTitle

func GetTitle(content []byte, fallback string) string

GetTitle extracts the title from markdown content. It looks for the first # heading, or falls back to the filename.

func HasFile

func HasFile(path string) bool

HasFile checks if a file exists in the embedded docs.

func IsBuiltinDocsProject

func IsBuiltinDocsProject(slug string) bool

IsBuiltinDocsProject returns true if the given slug is the built-in docs project.

func ListMarkdownFiles

func ListMarkdownFiles() ([]string, error)

ListMarkdownFiles returns all markdown file paths in the docs.

func MustReadFile

func MustReadFile(path string) []byte

MustReadFile reads a file and panics if it doesn't exist. Only use during initialization.

func NormalizePath

func NormalizePath(path string) string

NormalizePath normalizes a path for comparison.

func ReadMarkdown

func ReadMarkdown(path string) ([]byte, error)

ReadMarkdown reads a markdown file from the embedded docs.

func TransformMarkdownLinks

func TransformMarkdownLinks(content []byte) []byte

TransformMarkdownLinks converts .md links to .html links in content.

func ValidateDocs

func ValidateDocs() error

ValidateDocs checks that all required documentation files exist.

Types

type Deployer

type Deployer struct {
	Storage     docs.Storage
	Projects    store.ProjectStore
	Versions    store.VersionStore
	SearchIndex *docs.SearchIndex
	BasePath    string // URL base path (e.g., "/docs")
	Logger      *slog.Logger
}

Deployer handles deployment of built-in documentation.

func (*Deployer) Deploy

func (d *Deployer) Deploy(ctx context.Context, userID int64) error

Deploy creates or updates the built-in documentation project.

type DocEntry

type DocEntry struct {
	Title    string     // Display title (from # heading or filename)
	Path     string     // Relative path without extension (e.g., "tutorials/getting-started")
	HTMLPath string     // Path with .html extension
	Children []DocEntry // Subdirectory entries (for directories)
	IsDir    bool       // Whether this is a directory
	Order    int        // Sort order for display
}

DocEntry represents a documentation file or directory.

func ParseDocTree

func ParseDocTree() ([]DocEntry, error)

ParseDocTree parses the embedded docs directory and returns a structured tree.

type MissingDocsError

type MissingDocsError struct {
	Missing []string
}

MissingDocsError is returned when required docs are missing.

func (*MissingDocsError) Error

func (e *MissingDocsError) Error() string

type PageData

type PageData struct {
	Title       string
	Content     template.HTML
	Navigation  template.HTML
	CurrentPath string
	BasePath    string
	NavPrefix   string // relative prefix to reach doc root from current page (e.g., "../")
}

PageData holds data for rendering a documentation page.