litepage

README

Litepage - build sites simple.

What is Litepage?

Litepage is a tiny library to help you build static sites in Go. Build your HTML templates in Go and Litepage can build your pages for production and serve them locally during development, while adding only one dependency into your project.

Features:

• 🎁 Builds your static site ready to be hosted on any static site platform like GitHub Pages, Cloudflare Pages, etc.
• ⚡ Serves your static site locally during development
• 🧹 Maintains zero additional dependencies
• 📍 Includes out of the box sitemap.xml
• 📖 Common recipes to help with Markdown, Tailwind CSS, live reloading and more
• 🐢 Stable API with no specific package knowledge required

Motivation

Litepage is more of a philosophy than a library. It is an approach to build your sites in native Go, leveraging its standard library. Litepage can then build your site for production, and serve it whilst you are developing. This gives you full control on how you build your site, and a stable project that will live longer than the average frontend framework.

If your site is serving static content with little client side interaction, you don't need a server and you don't need a framework.

In todays world of JS frameworks, the reality is that most of your time is spent on maintenance, not development. They promise performance, but the best way to build performant sites is to not ship bloat. A site does not inherently run faster on a users machine because you used a certain framework, but it can run slower.

The best way to give your users peformance, is to ship the bare minimum HTML, CSS and JS required.

Installation

go get github.com/man-on-box/litepage

Project structure

The only directories Litepage interacts with by default are:

• public/* - to place your static assets (js, css, icons, images, etc.)
• dist/* - contains the outputted site when built, ready to be hosted

Example

See an example project in ./example/main.go

As simple as it gets:

func main() {
	lp, _ := litepage.New("hello-world.com")

	lp.Page("/index.html", func(w io.Writer) {
		t := template.Must(template.New("helloWorld").Parse("<h1>Hello, World!</h1>"))
		t.Execute(w, nil)
	})

	lp.Build()
}

When built, index.html will be created in your /dist folder containing your parsed template, along with any static assets contained within your /public folder.

Installation

go get github.com/man-on-box/litepage

Usage

Initialization

Create a new Litepage instance:

lp, err := litepage.New("hello-world.com")

Optionally you can pass configuration options when creating the instance:

lp, err := litepage.New("hello-world.com",
    litepage.WithDistDir("custom_dist"),
    litepage.WithBasePath("/custom-base"),
    litepage.WithPublicDir("custom_public"),
    litepage.WithoutSitemap(),
)

Options

• WithDistDir - Specify a custom dist directory to be used, that is created/written to when building the static site. Default value is dist.
• WithBasePath - Specify the base path of your site, if it is not the root of the domain (for example, if deploying to GitHub Pages). If set, all static assets and links should add the base as a prefix. The path should always start with a / and not end with a trailing slash (otherwise an error will be returned).
• WithPublicDir - Specify a custom public directory to be used, that is read to retrieve static assets when building or serving the static site. Default value is public.
• WithoutSitemap - Do not create a sitemap of your site. By default a sitemap.xml is created mapping all pages of the static site. Disable this if you do not want this, or if you want to create your own sitemap.

Creating pages

Create a new page by passing in the relative filename that will be used when building the site, such as /index.html or nested pages like /articles/new-recipes.html. Note: Paths must start with a /, include a file extension and be a valid filepath.

Here you also pass a function that receives the standard io.Writer interface. Write your templates to this interface to generate your pages with content. This means you can use any html templating library that supports this interface, such as the Go standard html/template package or custom packages like templ.

lp, _ := litepage.New("hello-world.com")

err := lp.Page("/index.html", func (w io.Writer) {
	    t := template.Must(template.New("helloWorld").Parse("<h1>Hello, World!</h1>"))
	    t.Execute(w, nil)
})

An error is returned if the file path is not valid, or if you have already created a page with the same file path previously.

Building your site

Once you have created all your pages, you can build your site. The outputted contents will be placed in the /dist directory, including all your assets in the /public directory.

lp, _ := litepage.New("hello-world.com")

// ... add all your pages

err := lp.Build()

The result in /dist directory can then be used with your preferred static site hosting service like GitHub Pages or CloudFlare pages. It should be an easy process to automate your build and host the outputted files during continuous integration.

Previewing your site

So we know how to build, but what about when developing your site? Ideally instead of writing files to /dist, you could see your site hosted locally on your machine for a better developer experience. For this you can call Serve which serves your static site locally, instead of outputting it to your dist folder.

lp, _ := litepage.New("hello-world.com")

// ... add all your pages

err := lp.Serve("3000")

This will start a web server at http://localhost:3000 to preview your site.

Build or Serve

The above methods explicitly build or serve your site, however if you want to be able to serve your site locally, while building it during CI, you can take advantage of the BuildOrServe method.

lp, _ := litepage.New("hello-world.com")

// ... add all your pages

err := lp.BuildOrServe()

By default, this will build your site the same as if you had called Build, though you can optionally Serve your site with the use of environment variables.

The following environment variables are checked when calling this method:

• LP_MODE - set this to serve to serve your site
• LP_PORT - set this to customise the port to serve your site on (default '3000')

See the example Makefile on how you could build or serve by specifying environment variables when building your application.

Contributing

If you like this project, consider giving it a star ⭐, it is much appreciated!

If you have any feedback please raise it as an issue 🎁.

Documentation

Overview

Package litepage is a minimalist, zero dependency static site builder for Go, to help move towards a simpler web.

Create your pages with the Page() method to build out your site. Put your static assets like images, JS or CSS in the /public directory.

You can then use Build() to build the static site into your dist directory, or Serve() to host the site locally, useful for local development.

For convenience, you can use BuildOrServe() method to either build or serve, depending on environment variables. This allows you to serve locally, while build for production.

Index

• type Litepage
  • func New(domain string, options ...Option) (Litepage, error)
• type Option
  • func WithBasePath(basePath string) Option
  • func WithDistDir(distDis string) Option
  • func WithPublicDir(publicDir string) Option
  • func WithoutSitemap() Option

Types

type Litepage

type Litepage interface {
	// Build generates the static site in the dist directory using assets
	// from the public directory and pages registered in litepage instance,
	// ready to be hosted on your static site hosting service.
	Build() error
	// Serve hosts the static site on the specified port, instead of
	// writing the site to the dist directory. Use this for local development.
	Serve(port string) error
	// BuildOrServe by default will build the static site in the dist directory.
	// If LP_MODE env variable is set to 'serve', it will instead serve the static site on port
	// 3000, or on port specified if LP_PORT env variable was set.
	//
	// This is useful for when you want to serve the site during development and
	// build it for production without requiring changes to the code.
	BuildOrServe() error
	// Page registers a new page with the specified relative file path and handler.
	// Create a page by specifying the relative path the page should be created,
	// as well as the handler to render the page contents to the standard writer
	// interface.
	Page(filePath string, handler func(w io.Writer)) error
}

func New

func New(domain string, options ...Option) (Litepage, error)

New creates a new Litepage instance with the specified domain and optional configurations. The domain parameter is required and must be a non-empty string representing the site's domain. The options parameter allows for additional configurations to be applied to the Litepage instance.

type Option

type Option func(*litepage) error

func WithBasePath

func WithBasePath(basePath string) Option

Specify the base path of your site, if it is not the root of the domain. If set, all static assets and links should add the base as a prefix. The path should always start with a ”/” and not end with a trailing slash (otherwise an error will be returned).

func WithDistDir

func WithDistDir(distDis string) Option

Specify the directory to place your site when building. By default it is "dist".

func WithPublicDir

func WithPublicDir(publicDir string) Option

Specify the directory where your public assets are. By default it is "public".

func WithoutSitemap

func WithoutSitemap() Option

By default a sitemap.xml is created mapping all pages of the static site. You can disable this behavior by specifying without a sitemap.