README
¶
go-mdbase
Go library implementing the mdbase specification v0.2.0 — a standard for treating folders of markdown files as typed, queryable data collections.
Conformance
This implementation targets conformance to mdbase Level 3 (Querying), which includes:
- Level 1 — Basic CRUD: Collection recognition, type loading, file matching, frontmatter validation, and create/read/update/delete operations.
- Level 2 — File Operations: File renaming with automatic reference updates.
- Level 3 — Querying: Query execution using an expression language for filtering and sorting, computed fields, and body content filtering.
The goal for this library is to reach full Level 6 (Migrations) conformance.
Installation
go get github.com/dstotijn/go-mdbase
Usage
package main
import (
"fmt"
"log"
"github.com/dstotijn/go-mdbase"
)
func main() {
c, err := mdbase.Open("./my-collection")
if err != nil {
log.Fatal(err)
}
fmt.Printf("Collection: %s\n", c.Config().Name)
fmt.Printf("Types: %d\n", len(c.Types()))
fmt.Printf("Records: %d\n", len(c.Records()))
for _, r := range c.Records() {
fmt.Printf(" %s\n", r.Path)
}
}
A collection is a directory containing an mdbase.yaml config file, optional
type definitions in _types/, and markdown files with YAML frontmatter:
my-collection/
├── mdbase.yaml
├── _types/
│ └── task.md
├── tasks/
│ ├── fix-bug.md
│ └── write-docs.md
└── notes/
└── idea.md
License
Documentation
¶
Overview ¶
Package mdbase implements the mdbase specification (https://mdbase.dev/spec.html), providing a typed, queryable interface over collections of markdown files.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Collection ¶
type Collection struct {
// contains filtered or unexported fields
}
Collection represents an opened mdbase collection.
func Open ¶
func Open(dir string) (*Collection, error)
Open opens an mdbase collection rooted at the given directory path.
func OpenFS ¶
func OpenFS(fsys fs.FS) (*Collection, error)
OpenFS opens a read-only mdbase collection from the given filesystem. This is useful for testing with testing/fstest.MapFS.
func (*Collection) Config ¶
func (c *Collection) Config() *Config
Config returns the parsed collection configuration.
func (*Collection) Records ¶
func (c *Collection) Records() []*Record
Records returns all discovered records in the collection.
func (*Collection) Types ¶
func (c *Collection) Types() map[string]*TypeDef
Types returns all loaded type definitions, keyed by name.
type Config ¶
type Config struct {
SpecVersion string `yaml:"spec_version"`
Name string `yaml:"name,omitempty"`
Description string `yaml:"description,omitempty"`
Settings Settings `yaml:"settings,omitempty"`
}
Config represents the contents of an mdbase.yaml file.
type Error ¶
type Error struct {
Code ErrorCode
Message string
// Path is the file path relative to the collection root, if applicable.
Path string
// Field is the field name, if applicable.
Field string
// Err is the underlying error, if any.
Err error
}
Error represents an operational error in the mdbase library.
type ErrorCode ¶
type ErrorCode string
ErrorCode represents a category of error from the mdbase specification.
const ( ErrMissingRequired ErrorCode = "missing_required" ErrTypeMismatch ErrorCode = "type_mismatch" ErrConstraintViolation ErrorCode = "constraint_violation" ErrDuplicateValue ErrorCode = "duplicate_value" ErrTypeConflict ErrorCode = "type_conflict" ErrUnknownType ErrorCode = "unknown_type" ErrInvalidTypeDefn ErrorCode = "invalid_type_definition" ErrDuplicateID ErrorCode = "duplicate_id" ErrInvalidPath ErrorCode = "invalid_path" ErrCircularComputed ErrorCode = "circular_computed" ErrCircularInheritance ErrorCode = "circular_inheritance" ErrInvalidConfig ErrorCode = "invalid_config" ErrUnsupportedVersion ErrorCode = "unsupported_version" ErrInvalidFrontmatter ErrorCode = "invalid_frontmatter" ErrUnknownField ErrorCode = "unknown_field" ErrFileNotFound ErrorCode = "file_not_found" ErrInvalidExpression ErrorCode = "invalid_expression" ErrLinkResolutionFailed ErrorCode = "link_resolution_failed" )
type FieldDef ¶
type FieldDef struct {
Type FieldType `yaml:"type"`
Required bool `yaml:"required,omitempty"`
Default any `yaml:"default,omitempty"`
Generated string `yaml:"generated,omitempty"`
Description string `yaml:"description,omitempty"`
Deprecated bool `yaml:"deprecated,omitempty"`
Unique bool `yaml:"unique,omitempty"`
Computed string `yaml:"computed,omitempty"`
// String constraints.
MinLength *int `yaml:"min_length,omitempty"`
MaxLength *int `yaml:"max_length,omitempty"`
Pattern string `yaml:"pattern,omitempty"`
// Number/integer constraints.
Min *float64 `yaml:"min,omitempty"`
Max *float64 `yaml:"max,omitempty"`
// Enum.
Values []string `yaml:"values,omitempty"`
// List.
Items *FieldDef `yaml:"items,omitempty"`
MinItems *int `yaml:"min_items,omitempty"`
MaxItems *int `yaml:"max_items,omitempty"`
// Object.
Fields map[string]*FieldDef `yaml:"fields,omitempty"`
// Link.
Target string `yaml:"target,omitempty"`
ValidateExists *bool `yaml:"validate_exists,omitempty"`
}
FieldDef describes a single field in a type schema.
type FieldType ¶
type FieldType string
FieldType represents the type of a field in a type definition.
const ( FieldTypeString FieldType = "string" FieldTypeInteger FieldType = "integer" FieldTypeNumber FieldType = "number" FieldTypeBoolean FieldType = "boolean" FieldTypeDate FieldType = "date" FieldTypeDatetime FieldType = "datetime" FieldTypeTime FieldType = "time" FieldTypeEnum FieldType = "enum" FieldTypeList FieldType = "list" FieldTypeObject FieldType = "object" FieldTypeLink FieldType = "link" FieldTypeAny FieldType = "any" )
type FileMetadata ¶
type FileMetadata struct {
// Path is the relative path from the collection root.
Path string
// Basename is the filename without extension.
Basename string
// Ext is the file extension (without leading dot).
Ext string
// Size is the file size in bytes.
Size int64
// Created is the file creation time (may equal Modified if unavailable).
Created time.Time
// Modified is the last modification time.
Modified time.Time
}
FileMetadata contains filesystem information about a record's file.
func NewFileMetadata ¶
func NewFileMetadata(filePath string, size int64, modTime time.Time) FileMetadata
NewFileMetadata constructs FileMetadata from a path, size, and modification time.
type MatchRule ¶
type MatchRule struct {
PathGlob string `yaml:"path_glob,omitempty"`
FieldsPresent []string `yaml:"fields_present,omitempty"`
Where map[string]any `yaml:"where,omitempty"`
}
MatchRule defines conditions for automatically matching files to a type.
type Record ¶
type Record struct {
// Path is the file path relative to the collection root.
Path string
// Frontmatter holds the parsed YAML frontmatter key-value pairs.
// Null semantics: key present with nil value = null; key absent = undefined.
Frontmatter map[string]any
// RawFrontmatter is the original YAML bytes, for round-tripping.
RawFrontmatter []byte
// Body is the markdown content after the frontmatter.
Body string
// File holds filesystem metadata about the record.
File FileMetadata
// Types lists the names of all types matched to this record.
Types []string
}
Record represents a single markdown file in the collection.
type Settings ¶
type Settings struct {
// File discovery.
Extensions []string `yaml:"extensions,omitempty"`
Exclude []string `yaml:"exclude,omitempty"`
IncludeSubfolders *bool `yaml:"include_subfolders,omitempty"`
// Types.
TypesFolder string `yaml:"types_folder,omitempty"`
ExplicitTypeKeys []string `yaml:"explicit_type_keys,omitempty"`
// Validation.
DefaultValidation *ValidationLevel `yaml:"default_validation,omitempty"`
DefaultStrict *Strictness `yaml:"default_strict,omitempty"`
// Timezone.
Timezone string `yaml:"timezone,omitempty"`
// Link resolution.
IDField string `yaml:"id_field,omitempty"`
// Writing.
WriteNulls *WriteNullMode `yaml:"write_nulls,omitempty"`
WriteDefaults *bool `yaml:"write_defaults,omitempty"`
WriteEmptyLists *bool `yaml:"write_empty_lists,omitempty"`
// Operations.
RenameUpdateRefs *bool `yaml:"rename_update_refs,omitempty"`
CacheFolder string `yaml:"cache_folder,omitempty"`
}
Settings holds all configurable collection settings.
type Strictness ¶
type Strictness int
Strictness controls how unknown fields are handled during validation.
const ( StrictOff Strictness = iota // Unknown fields allowed silently. StrictWarn // Unknown fields produce warnings. StrictOn // Unknown fields cause validation failure. )
func (*Strictness) UnmarshalYAML ¶
func (s *Strictness) UnmarshalYAML(unmarshal func(any) error) error
type TypeDef ¶
type TypeDef struct {
Name string `yaml:"name"`
Description string `yaml:"description,omitempty"`
Version int `yaml:"version,omitempty"`
Extends string `yaml:"extends,omitempty"`
Strict *Strictness `yaml:"strict,omitempty"`
Match *MatchRule `yaml:"match,omitempty"`
PathPattern string `yaml:"path_pattern,omitempty"`
Fields map[string]*FieldDef `yaml:"fields,omitempty"`
// contains filtered or unexported fields
}
TypeDef represents a type definition loaded from a file in the types folder.
type ValidationIssue ¶
ValidationIssue represents a single validation problem found in a record.
type ValidationLevel ¶
type ValidationLevel string
ValidationLevel controls how validation issues are reported.
const ( ValidationOff ValidationLevel = "off" ValidationWarn ValidationLevel = "warn" ValidationError ValidationLevel = "error" )
type ValidationResult ¶
type ValidationResult struct {
Issues []ValidationIssue
}
ValidationResult collects all validation issues for a record or operation.
func (*ValidationResult) AddIssue ¶
func (r *ValidationResult) AddIssue(code ErrorCode, path, field, message string)
AddIssue appends a validation issue.
func (*ValidationResult) Valid ¶
func (r *ValidationResult) Valid() bool
Valid returns true if there are no issues.
type WriteNullMode ¶
type WriteNullMode string
WriteNullMode controls how null values are written to frontmatter.
const ( WriteNullOmit WriteNullMode = "omit" WriteNullExplicit WriteNullMode = "explicit" )
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
frontmatter
Package frontmatter handles parsing and serializing YAML frontmatter in markdown files, preserving null/missing/empty semantics.
|
Package frontmatter handles parsing and serializing YAML frontmatter in markdown files, preserving null/missing/empty semantics. |
|
glob
Package glob provides glob pattern matching with ** (double-star) support, which Go's standard path.Match lacks.
|
Package glob provides glob pattern matching with ** (double-star) support, which Go's standard path.Match lacks. |