pub

package module
v0.14.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 22, 2025 License: BSL-1.0 Imports: 10 Imported by: 0

README

pub

  • Easy to use static site generator that also supports creating RSS feeds, EPUBs, etc. from your Markdown files (WIP)
  • Highly customizable and extensible: modify the underlying layout to your heart's content using go's advanced text templating engine
  • Zero/minimal configuration necessary: pub comes with great defaults that emphasize user accessibility and system compatibility
  • Local and private: use the program and browse the documentation (WIP) locally without an internet connection
  • No lock-in to any service or ecosystem
  • Backward and forward-compatible (at and after version 1.0.0)

Description

pub is an easy-to-use static site generator specifically designed for independently publishing your Markdown-based written works on the web. pub also supports generating other popular open formats such as PDFs and EPUBs (WIP), which are supported across almost all machines and e-readers.

pub requires minimal configuration, allowing you to put all your focus on the act of writing itself. These great defaults emphasize user accessibility and widespread compatibility with many systems, letting you produce works that are comfortable to read in with little effort. Nevertheless, pub is also extremely configurable and extensible, with an embedded text templating engine (go's text/template and html/template) and support for custom configuration fields that allows you to develop and utilize custom themes to modify the overall presentation of the output.

Additionally, pub is permissively licensed. You can use the program and browse the documentation locally without internet, and with all your writing being done in open plain-text formats, there is little potential lock-in to any single service/ecosystem.

The upcoming pub version 1.0.0 is also committed to not only be backward-compatible but also forward-compatible. Old book projects should be able to be successfully built in the future.

Install

Go

Install the latest version with go itself.

go install github.com/JessebotX/pub/cmd/pub@latest

Usage

For help using the CLI utility, run program with -h or --help flag like so:

pub --help

OR access the man page on a unix-like system (WIP):

man pub

Documentation

Index

Constants

View Source 
const (
	BookConfigFileName         = "pub.yml"
	BookChaptersConfigFileName = "nav.yml"
	BookAssetsDirName          = "assets"
	BookChaptersDirName        = "chapters"
)

Variables

View Source 
var (
	ErrAssetMissingObjects        = errors.New("asset: could not find objects/descriptors")
	ErrAssetDescriptorMissingName = errors.New("asset descriptor: missing Name")
)
View Source 
var (
	ErrBookMissingLanguageCode = errors.New("missing LanguageCode")
	ErrBookMissingUniqueID     = errors.New("missing UniqueID (value must contain at least 1 non-space character)")
	ErrBookMissingTitle        = errors.New("missing Title")
)
View Source 
var (
	ErrChapterMissingBookPointer = errors.New("missing pointer to Book")
	ErrChapterMissingUniqueID    = errors.New("missing UniqueID (must have at least 1 non-space character)")
)
View Source 
var (
	ErrContentParsedUninitialized = errors.New("parsed content map is not initialized")
	ErrContentFormatNotFound      = errors.New("parsed content format does not exist")
)
View Source 
var (
	DateTimeLayouts = []string{
		"2006-01-02T15:04:05Z07:00",
		"2006-01-02 15:04:05Z07:00",
		"2006-01-02T15:04Z07:00",
		"2006-01-02 15:04Z07:00",
		"2006-01-02TZ07:00",
		"2006-01-02 Z07:00",
		"2006-01TZ07:00",
		"2006-01 Z07:00",
		"2006TZ07:00",
		"2006 Z07:00",
		"2006-01-02T15:04:05",
		"2006-01-02 15:04:05",
		"2006-01-02T15:04",
		"2006-01-02 15:04",
		"2006-01-02",
		"2006-01",
		"2006",
	}
)
View Source 
var (
	ErrProfileMissingName = errors.New("profile: missing Name")
)
View Source 
var (
	ErrReferenceMissingName = errors.New("reference: missing Name")
)
View Source 
var (
	ErrSeriesMissingTitle = errors.New("series: missing title")
)
View Source 
var (
	StatusMap = map[string]Status{
		"completed": Completed,
		"ongoing":   Ongoing,
		"hiatus":    Hiatus,
		"inactive":  Inactive,
	}
)

Functions

This section is empty.

Types

type Asset 

type Asset struct {
	Objects         []AssetDescriptor
	AlternativeText string
	Caption         Content
}

Asset represents a media element such as an image or video. Supports specifying multiple [AssetDescriptor]s which will be used as fallback formats (in the specified order) when the asset is not supported by the application.

func (*Asset) EnsureValid 

func (a *Asset) EnsureValid() error

func (*Asset) MainDescriptor 

func (a *Asset) MainDescriptor() AssetDescriptor

func (*Asset) OtherDescriptors 

func (a *Asset) OtherDescriptors() []AssetDescriptor

type AssetDescriptor 

type AssetDescriptor struct {
	Name   string
	Type   string
	Format string
}

AssetDescriptor represents an individual file format of a media element.

func (*AssetDescriptor) CheckValid 

func (a *AssetDescriptor) CheckValid() error

type Book 

type Book struct {
	UniqueID           string         `json:"unique_id"`
	Title              string         `json:"title"`
	Subtitle           string         `json:"subtitle"`
	TitlesAlternate    []string       `json:"titles_alternate"`
	Description        string         `json:"description"`
	Tagline            string         `json:"tagline"`
	Content            Content        `json:"content"`
	Authors            []Profile      `json:"authors"`
	Contributors       []Profile      `json:"contributors"`
	Publishers         []Profile      `json:"publishers"`
	Tags               []string       `json:"tags"`
	Status             Status         `json:"status"`
	Series             []Series       `json:"series"`
	Edition            string         `json:"edition"`
	URL                string         `json:"url"`
	LanguageCode       string         `json:"language_code"`
	DatePublishedStart *DateTime      `json:"date_published_start"`
	DatePublishedEnd   *DateTime      `json:"date_published_end"`
	LinksFunding       []Reference    `json:"links_funding"`
	LinksMirrors       []Reference    `json:"links_mirrors"`
	LinksOther         []Reference    `json:"links_other"`
	Assets             []Asset        `json:"assets"`
	IDs                map[string]any `json:"ids"`
	Copyright          Copyright      `json:"copyright"`
	Chapters           []Chapter      `json:"chapters"`
	Extra              map[string]any `json:"extra"`

	InputPath string
}

Book represents a written work, which generally has an ordered list of 1 or more [Chapter]s.

func NewBook 

func NewBook(inputPath string) (Book, error)

func (*Book) AddTag 

func (b *Book) AddTag(tag string) error

func (Book) ChaptersAndSubchapters 

func (b Book) ChaptersAndSubchapters() []*Chapter

func (*Book) EnsureValid 

func (b *Book) EnsureValid() error

func (*Book) NormalizeAllTags 

func (b *Book) NormalizeAllTags() error

Trim trailing spaces/newlines and remove duplicates in book tags list

func (*Book) SetDatePublishedEndFromString 

func (b *Book) SetDatePublishedEndFromString(input string) error

func (*Book) SetDatePublishedStartFromString 

func (b *Book) SetDatePublishedStartFromString(input string) error

func (*Book) SetInputPath 

func (b *Book) SetInputPath(inputPath string) error

func (*Book) SetUniqueID 

func (b *Book) SetUniqueID(uniqueID string)

type Chapter 

type Chapter struct {
	UniqueID          string            `json:"unique_id"`
	Title             string            `json:"title"`
	Subtitle          string            `json:"subtitle"`
	Authors           []Profile         `json:"authors"`
	Contributors      []Profile         `json:"contributors"`
	Publishers        []Profile         `json:"publishers"`
	ContentFileName   string            `json:"content_file_name"`
	Content           Content           `json:"content"`
	AuthorsNotePrefix Content           `json:"authors_note_prefix"`
	AuthorsNoteSuffix Content           `json:"authors_note_suffix"`
	URL               string            `json:"url"`
	LanguageCode      string            `json:"language_code"`
	DatePublished     *DateTime         `json:"date_published"`
	DateUpdated       *DateTime         `json:"date_updated"`
	IDs               map[string]string `json:"ids"`
	Copyright         Copyright         `json:"copyright"`
	Extra             map[string]any    `json:"extra"`
	Chapters          []Chapter         `json:"chapters"`

	Previous  *Chapter
	Next      *Chapter
	Book      *Book
	InputPath string
}

Chapter represents a division in a Book that contains its primary Content.

func (*Chapter) EnsureValid 

func (c *Chapter) EnsureValid() error

func (Chapter) GetAbsoluteInputPath 

func (c Chapter) GetAbsoluteInputPath() (string, error)

func (Chapter) HasSubchapters 

func (c Chapter) HasSubchapters() bool

func (*Chapter) SetBook 

func (c *Chapter) SetBook(book *Book) error

func (*Chapter) SetDatePublishedFromString 

func (c *Chapter) SetDatePublishedFromString(input string) error

func (*Chapter) SetDateUpdatedFromString 

func (c *Chapter) SetDateUpdatedFromString(input string) error

func (*Chapter) SetInputPath 

func (c *Chapter) SetInputPath(inputPath string) error

func (*Chapter) SetUniqueID 

func (c *Chapter) SetUniqueID(uniqueID string)

func (Chapter) Subchapters 

func (c Chapter) Subchapters() []*Chapter

type Content 

type Content struct {
	Raw []byte
	// contains filtered or unexported fields
}

Content represents a body of text that is/can be parsed into different formats (e.g. Markdown to HTML, etc.).

func (*Content) AddFormat 

func (c *Content) AddFormat(format string, content any)

func (*Content) Format 

func (c *Content) Format(format string) (any, error)

func (*Content) MarshalJSON 

func (c *Content) MarshalJSON() ([]byte, error)

func (*Content) MarshalText 

func (c *Content) MarshalText() ([]byte, error)

func (*Content) MarshalYAML 

func (c *Content) MarshalYAML() ([]byte, error)

func (*Content) UnmarshalJSON 

func (c *Content) UnmarshalJSON(text []byte) error

func (*Content) UnmarshalText 

func (c *Content) UnmarshalText(text []byte) error

func (*Content) UnmarshalYAML 

func (c *Content) UnmarshalYAML(text []byte) error
type Copyright struct {
	Notice   string    `json:"notice"`
	Licenses []License `json:"licenses"`
}

type DateTime 

type DateTime struct {
	time.Time
}

func (DateTime) MarshalJSON 

func (d DateTime) MarshalJSON() ([]byte, error)

func (DateTime) MarshalText 

func (d DateTime) MarshalText() ([]byte, error)

func (DateTime) MarshalYAML 

func (d DateTime) MarshalYAML() ([]byte, error)

func (*DateTime) UnmarshalJSON 

func (d *DateTime) UnmarshalJSON(text []byte) error

func (*DateTime) UnmarshalText 

func (d *DateTime) UnmarshalText(text []byte) error

func (*DateTime) UnmarshalYAML 

func (d *DateTime) UnmarshalYAML(text []byte) error

type ErrAssetMismatchedDescriptorType 

type ErrAssetMismatchedDescriptorType struct {
	AssetType      string
	DescriptorName string
	DescriptorType string
}

func (ErrAssetMismatchedDescriptorType) Error 

func (e ErrAssetMismatchedDescriptorType) Error() string

type ErrBookEmptyTag 

type ErrBookEmptyTag struct {
	Input string
	Index int
}

func (ErrBookEmptyTag) Error 

func (e ErrBookEmptyTag) Error() string

type ErrReferenceMissingAddress 

type ErrReferenceMissingAddress struct {
	Name string
}

func (ErrReferenceMissingAddress) Error 

func (e ErrReferenceMissingAddress) Error() string

type ErrReferenceTooManyNestedDomains 

type ErrReferenceTooManyNestedDomains struct {
	TopLevelName        string
	DomainAlternateName string
}

func (ErrReferenceTooManyNestedDomains) Error 

func (e ErrReferenceTooManyNestedDomains) Error() string

type ErrStatusMarshalUnrecognized 

type ErrStatusMarshalUnrecognized struct {
	Value Status
}

func (ErrStatusMarshalUnrecognized) Error 

func (e ErrStatusMarshalUnrecognized) Error() string

type ErrStatusUnmarshalUnrecognized 

type ErrStatusUnmarshalUnrecognized struct {
	StatusString string
}

func (ErrStatusUnmarshalUnrecognized) Error 

func (e ErrStatusUnmarshalUnrecognized) Error() string

type License 

type License struct {
	FileName string `json:"file_name"`
	Text     string `json:"text"`
}

type Profile 

type Profile struct {
	Name           string      `json:"name"`
	NamesAlternate []string    `json:"names_alternate"`
	Content        Content     `json:"content"`
	External       []Reference `json:"external"`
}

Profile may represent an individual or an organization that is credited as either an author, contributor or publisher affliated with a Book.

func (*Profile) EnsureValid 

func (p *Profile) EnsureValid() error

type Reference 

type Reference struct {
	Name             string      `json:"name"`
	Address          string      `json:"address"`
	NotClickable     bool        `json:"not_clickable"`
	DomainsAlternate []Reference `json:"domains_alternate"`
}

Reference represents an external link/address that is generally clickable.

func (*Reference) EnsureValid 

func (r *Reference) EnsureValid() error

type Series 

type Series struct {
	Title           string      `json:"title"`
	TitlesAlternate []string    `json:"titles_alternate"`
	Number          float64     `json:"number"`
	Description     string      `json:"description"`
	Content         Content     `json:"content"`
	External        []Reference `json:"external"`
}

Series describes a Book's relation to a set of other Book objects (i.e. prequels, sequels, side stories, sharing the same world/universe, etc.)

func (Series) EnsureValid 

func (s Series) EnsureValid() error

type Status 

type Status int
const (
	Completed Status = iota
	Ongoing
	Hiatus
	Inactive
)

func (Status) MarshalText 

func (s Status) MarshalText() ([]byte, error)

func (Status) String 

func (s Status) String() (string, error)

func (*Status) UnmarshalText 

func (s *Status) UnmarshalText(text []byte) error

Source Files

View all Source files

Directories

Path Synopsis
cmd
pub command
renderer
html

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.