gdn

README

gdn

Gemini digital garden static site generator.

A digital garden is like a personal knowledge-base or wiki. Rather than a blog where you write articles that are tied to a moment in time, a digital garden encourages revisiting pages and changing them as you grow.

gdn expects your digital garden to be written in Gemini text files (with file extension .gmi or .gemini) organized in folders. gdn renders the digital Garden into a static HTML site that can be served over HTTP/HTTPS by most web servers.

Gemini is both a network protocol and a text format. gdn renders your digital garden to HTML so it can be viewed by a normal web browser on the web.

• https://gemini.circumlunar.space/

gdn renders Gemini text formatted files into HTML to produce a static site.

Work in Progress

This is currently a work in progress. Not all features work.

Building and Installing from Source Code

Dependencies

This project has the following dependencies:

• Go the programming language and standard libraries.
• Mage a build tool similar to make, but uses Go.
• git for version control.

You need to install these before building or installing.

Fetching Code

Clone this repository using git and change directory:

git clone https://git.sr.ht/~kiba/gdn
cd gdn

Building from Source

The build target compiles from source and places the executable in the ./dist/ directory.

mage -v build

Installing from Source

The install target compiles from source and places the executable into your $GOPATH/bin directory via go install. This must be in your PATH if you wish to execute gdn without specifying the full path of gdn.

mage -v install

Contributing

Contributions are welcome. Please read the CONTRIBUTING.md guide.

License

This project is licensed by the MIT License. See: LICENSE.

Documentation

Overview

Package gdn provides tools for generating a static website from a source of pages written in the Gemini text and organized in directories.

Index

• Constants
• Variables
• func ChExt(path, ext string) string
• func CopyFile(src, dest string) error
• type Branch
  • func NewTree(inputPath, outputPath string) Branch
  • func (b Branch) Grow() error
  • func (b *Branch) Scan() error
• type FileType
  • func TypeByExtension(ext string) FileType
  • func (t FileType) String() string
• type Leaf
  • func (l Leaf) Dst() string
  • func (l Leaf) Grow() error

Constants

const BranchPerm os.FileMode = 0750

BranchPerm sets the permission for the directories produced when growing.

const LeafPerm os.FileMode = 0640

LeafPerm is the permission to set for the generated file the leaf produces.

Variables

var (
	// ErrSrcNotSet occurs when the source path is not set.
	ErrSrcNotSet = errors.New("source path is not set")
	// ErrDstNotSet occurs when the destinatio path is not set.
	ErrDstNotSet = errors.New("destination path is not set")
	// ErrNotScanned occurs when Scan was not called before Grow.
	ErrNotScanned = errors.New("need to scan tree before growing it")
	// ErrEmptyTree occurs when Scan results in an empty tree.
	ErrEmptyTree = errors.New("scan resulted in an empty tree")
)

var KnownFileTypes = map[string]FileType{
	".md":       Markdown,
	".mkd":      Markdown,
	".markdown": Markdown,
}

KnownFileTypes is a map of extensions to their FileType.

Functions

func ChExt

func ChExt(path, ext string) string

ChExt takes a path and replaces any file extension that path has with the the given new extension.

func CopyFile

func CopyFile(src, dest string) error

CopyFile will copy a file from the given source to the destination.

Types

type Branch

type Branch struct {
	Src      string
	Dst      string
	Path     string
	Branches []*Branch
	Leaves   []*Leaf
}

Branch represents a directory tree used to generate the pages.

func NewTree

func NewTree(inputPath, outputPath string) Branch

NewTree creates the root of the tree. The input path is the path with all the source files and directories (e.g. Markdown, images, etc). The output path is the destination for the generated site. This returns a single Branch with no Leaves which an be used to Scan the input path to populate the tree.

func (Branch) Grow

func (b Branch) Grow() error

Grow generates the site from the branch.

func (*Branch) Scan

func (b *Branch) Scan() error

Scan will scan the input path for items to generate the site and build the tree. Directories are added as Branches. Files are added as Leaves. Hidden files and directories are ignored.

type FileType

type FileType uint

FileType represents a high level file type.

const (
	// Unknown is an unknown file type.
	Unknown FileType = iota
	// Markdown is a markdown file type.
	Markdown
)

func TypeByExtension

func TypeByExtension(ext string) FileType

TypeByExtension will look up the type by its extension.

func (FileType) String

func (t FileType) String() string

String returns the string representation of FileType. For example, if the FileType is Markdown it will return the string "Markdown".

type Leaf

type Leaf struct {
	Src    string
	DstDir string
	Path   string
	Typ    FileType
}

Leaf represnts a file. If it is a Markdown file it will be generated into a page.

func (Leaf) Dst

func (l Leaf) Dst() string

Dst is the destination file path for the leaf when Grow is executed.

func (Leaf) Grow

func (l Leaf) Grow() error

Grow will generate a page for the leaf.