README

gdn

builds.sr.ht status

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.

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.

Expand ▾ Collapse ▴

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

    View Source
    const BranchPerm os.FileMode = 0750

      BranchPerm sets the permission for the directories produced when growing.

      View Source
      const LeafPerm os.FileMode = 0640

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

        Variables

        View Source
        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")
        )
        View Source
        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.

                                  Directories

                                  Path Synopsis
                                  cmd
                                  gdn
                                  Package gmi provides tools for reading Gemini text and converting it to HTML.
                                  Package gmi provides tools for reading Gemini text and converting it to HTML.