note

Documentation

Overview

Package note provides the core Note type, ID generation, and frontmatter parsing/serialisation for the nn Zettelkasten CLI.

Index

• Variables
• func BM25Scores(notes []*Note, query string, inbound map[string][]string) map[string]float64
• func GenerateID() string
• func IsKnownLinkType(t string) bool
• func Tokenize(s string) []string
• func ValidTypes() []string
• type Link
• type Note
  • func Parse(data []byte) (*Note, error)
  • func (n *Note) Filename() string
  • func (n *Note) Marshal() ([]byte, error)
• type Status
  • func (s Status) IsValid() bool
• type Type
  • func (t Type) IsValid() bool

Variables

var KnownLinkTypes = map[string]bool{
	"refines":     true,
	"contradicts": true,
	"source-of":   true,
	"extends":     true,
	"supports":    true,
	"questions":   true,
	"governs":     true,
}

KnownLinkTypes is the canonical set of link relationship types. nn link --type warns when the type is not in this set.

Functions

func BM25Scores

func BM25Scores(notes []*Note, query string, inbound map[string][]string) map[string]float64

BM25Scores returns BM25 scores for each note against the query terms. inbound maps note ID to annotation strings from notes that link to it; those tokens are included at inboundWeight relative to body tokens. Only notes matching at least one query term are included.

func GenerateID

func GenerateID() string

GenerateID returns a unique note ID in the format <14-digit-timestamp>-<4-digit-random>. crypto/rand provides the suffix. A process-local set detects and retries on the rare within-process collision (e.g. 200 concurrent goroutines in the same second).

func IsKnownLinkType

func IsKnownLinkType(t string) bool

IsKnownLinkType reports whether t is in the canonical link type set.

func Tokenize

func Tokenize(s string) []string

Tokenize splits text into lowercase tokens. Exported for use in match-reason computation.

func ValidTypes

func ValidTypes() []string

ValidTypes returns the list of recognised note type strings.

Types

type Link

type Link struct {
	TargetID   string
	Annotation string
	Type       string // optional relationship type, e.g. "refines", "contradicts"
	Status     string // "draft" or "reviewed"; empty = reviewed (backward-compat for old links)
}

Link is an annotated outgoing link from one note to another.

type Note

type Note struct {
	// Frontmatter fields
	ID          string
	Title       string
	Type        Type
	Status      Status
	Tags        []string
	AppliesWhen string
	ExpiresWhen string
	Expires     *time.Time
	Created     time.Time
	Modified    time.Time

	// Body is the Markdown content between the frontmatter and the ## Links section.
	Body string

	// Links are parsed from the ## Links section.
	Links []Link
}

Note is the in-memory representation of a single Zettelkasten note.

func Parse

func Parse(data []byte) (*Note, error)

Parse reads a Markdown file (with YAML frontmatter) and returns a Note. Returns an error if the frontmatter is invalid, the type is missing, or a bare link (without annotation) is found in the ## Links section.

func (*Note) Filename

func (n *Note) Filename() string

Filename returns the canonical filename for this note: <id>-<slug>.md

func (*Note) Marshal

func (n *Note) Marshal() ([]byte, error)

Marshal serialises the note back to Markdown with YAML frontmatter.

type Status

type Status string

Status is the review status of a note.

const (
	StatusDraft     Status = "draft"
	StatusReviewed  Status = "reviewed"
	StatusPermanent Status = "permanent"
)

func (Status) IsValid

func (s Status) IsValid() bool

IsValid reports whether s is one of the recognised note statuses.

type Type

type Type string

Type classifies the intellectual content of a note.

const (
	TypeConcept     Type = "concept"
	TypeArgument    Type = "argument"
	TypeModel       Type = "model"
	TypeHypothesis  Type = "hypothesis"
	TypeObservation Type = "observation"
	TypeQuestion    Type = "question"
	TypeProtocol    Type = "protocol"
)

func (Type) IsValid

func (t Type) IsValid() bool

IsValid reports whether t is one of the recognised note types.