goldsmith/README.md

207 lines
10 KiB
Markdown
Raw Normal View History

2021-06-09 03:53:41 +00:00
# Goldsmith
2016-01-12 10:24:19 +00:00
2019-04-08 23:17:12 +00:00
Goldsmith is a fast and easily extensible static website generator written in Go. In contrast to many other generators,
Goldsmith does not force any design paradigms or file organization rules on the user, making it possible to generate
2019-04-08 19:02:18 +00:00
anything from blogs to image galleries using the same tool.
2016-01-12 10:24:19 +00:00
2021-06-09 03:53:41 +00:00
## Tutorial
2016-09-07 04:50:46 +00:00
2019-04-08 23:17:12 +00:00
Goldsmith does not use any configuration files, and all behavior customization happens in code. Goldsmith uses the
[builder pattern](https://en.wikipedia.org/wiki/Builder_pattern) to establish a chain, which modifies files as they pass
2023-12-31 03:50:32 +00:00
through it. Although the [Goldsmith](https://godoc.org/git.foosoft.net/alex/goldsmith) API is short and (hopefully) easy
2022-07-04 17:18:36 +00:00
to understand, it is often best to learn by example:
2016-07-12 03:52:43 +00:00
2019-04-09 00:50:19 +00:00
1. Start by copying files from a source directory to a destination directory (the simplest possible use case):
2018-02-22 03:14:55 +00:00
2019-04-08 19:02:18 +00:00
```go
goldsmith.
Begin(srcDir). // read files from srcDir
End(dstDir) // write files to dstDir
```
2016-01-12 10:24:19 +00:00
2019-04-09 00:50:19 +00:00
2. Now let's convert any Markdown files to HTML fragments (while still copying the rest), using the
2023-12-31 03:50:32 +00:00
[Markdown](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/markdown) plugin:
2016-09-07 04:13:37 +00:00
2017-09-30 00:03:53 +00:00
```go
2019-04-08 19:02:18 +00:00
goldsmith.
Begin(srcDir). // read files from srcDir
Chain(markdown.New()). // convert *.md files to *.html files
End(dstDir) // write files to dstDir
2016-01-12 10:24:19 +00:00
```
2019-04-09 00:50:19 +00:00
3. If we have any
2019-04-08 23:17:12 +00:00
[front matter](https://raw.githubusercontent.com/FooSoft/goldsmith-samples/master/basic/content/index.md) in our
Markdown files, we need to extract it using the,
2023-12-31 03:50:32 +00:00
[FrontMatter](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/frontmatter) plugin:
2016-09-07 04:13:37 +00:00
2017-09-30 00:03:53 +00:00
```go
2019-04-08 19:02:18 +00:00
goldsmith.
Begin(srcDir). // read files from srcDir
Chain(frontmatter.New()). // extract frontmatter and store it as metadata
Chain(markdown.New()). // convert *.md files to *.html files
End(dstDir) // write files to dstDir
2016-01-12 10:24:19 +00:00
```
2019-04-09 00:50:19 +00:00
4. Next, we should run our barebones HTML through a
2019-04-08 19:02:18 +00:00
[template](https://raw.githubusercontent.com/FooSoft/goldsmith-samples/master/basic/content/layouts/basic.gohtml) to
2019-04-08 23:17:12 +00:00
add elements like a header, footer, or a menu; for this we can use the
2023-12-31 03:50:32 +00:00
[Layout](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/frontmatter) plugin:
2016-09-07 04:13:37 +00:00
2017-09-30 00:03:53 +00:00
```go
2019-04-08 19:02:18 +00:00
goldsmith.
Begin(srcDir). // read files from srcDir
Chain(frontmatter.New()). // extract frontmatter and store it as metadata
Chain(markdown.New()). // convert *.md files to *.html files
Chain(layout.New()). // apply *.gohtml templates to *.html files
End(dstDir) // write files to dstDir
2016-01-12 10:24:19 +00:00
```
2019-04-09 00:50:19 +00:00
5. Now, let's [minify](https://en.wikipedia.org/wiki/Minification_(programming)) our files to reduce data transfer and
2019-04-08 23:17:12 +00:00
load times for our site's visitors using the
2023-12-31 03:50:32 +00:00
[Minify](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/minify) plugin:
2016-09-07 04:13:37 +00:00
2017-09-30 00:03:53 +00:00
```go
2019-04-08 19:02:18 +00:00
goldsmith.
Begin(srcDir). // read files from srcDir
Chain(frontmatter.New()). // extract frontmatter and store it as metadata
Chain(markdown.New()). // convert *.md files to *.html files
Chain(layout.New()). // apply *.gohtml templates to *.html files
Chain(minify.New()). // minify *.html, *.css, *.js, etc. files
End(dstDir) // write files to dstDir
2016-01-12 10:24:19 +00:00
```
2019-04-09 00:50:19 +00:00
6. Debugging problems in minified code can be tricky, so let's use the
2023-12-31 03:50:32 +00:00
[Condition](https://godoc.org/git.foosoft.net/alex/goldsmith-components/filters/condition) filter to make
2022-07-04 17:18:36 +00:00
minification occur only when we are ready for distribution.
2016-09-07 04:13:37 +00:00
2017-09-30 00:03:53 +00:00
```go
2019-04-08 19:02:18 +00:00
goldsmith.
Begin(srcDir). // read files from srcDir
Chain(frontmatter.New()). // extract frontmatter and store it as metadata
Chain(markdown.New()). // convert *.md files to *.html files
Chain(layout.New()). // apply *.gohtml templates to *.html files
FilterPush(condition.New(dist)). // push a dist-only conditional filter onto the stack
Chain(minify.New()). // minify *.html, *.css, *.js, etc. files
FilterPop(). // pop off the last filter pushed onto the stack
End(dstDir) // write files to dstDir
2016-01-12 10:24:19 +00:00
```
2019-04-09 00:50:19 +00:00
7. Now that we have all of our plugins chained up, let's look at a complete example which uses
2023-12-31 03:50:32 +00:00
[DevServer](https://godoc.org/git.foosoft.net/alex/goldsmith-components/devserver) to bootstrap a complete
2022-07-04 17:18:36 +00:00
development sever which automatically rebuilds the site whenever source files are updated.
2016-09-07 04:13:37 +00:00
2017-09-30 00:03:53 +00:00
```go
2016-09-07 04:13:37 +00:00
package main
import (
2019-04-08 19:02:18 +00:00
"flag"
2016-09-07 04:13:37 +00:00
"log"
2023-12-31 03:50:32 +00:00
"git.foosoft.net/alex/goldsmith"
"git.foosoft.net/alex/goldsmith-components/devserver"
"git.foosoft.net/alex/goldsmith-components/filters/condition"
"git.foosoft.net/alex/goldsmith-components/plugins/frontmatter"
"git.foosoft.net/alex/goldsmith-components/plugins/layout"
"git.foosoft.net/alex/goldsmith-components/plugins/markdown"
"git.foosoft.net/alex/goldsmith-components/plugins/minify"
2016-09-07 04:13:37 +00:00
)
2019-04-08 19:02:18 +00:00
type builder struct {
dist bool
}
2016-09-07 04:13:37 +00:00
2019-04-08 19:02:18 +00:00
func (b *builder) Build(srcDir, dstDir, cacheDir string) {
errs := goldsmith.
Begin(srcDir). // read files from srcDir
Chain(frontmatter.New()). // extract frontmatter and store it as metadata
Chain(markdown.New()). // convert *.md files to *.html files
Chain(layout.New()). // apply *.gohtml templates to *.html files
FilterPush(condition.New(b.dist)). // push a dist-only conditional filter onto the stack
Chain(minify.New()). // minify *.html, *.css, *.js, etc. files
FilterPop(). // pop off the last filter pushed onto the stack
End(dstDir) // write files to dstDir
2016-09-07 04:13:37 +00:00
for _, err := range errs {
log.Print(err)
}
}
func main() {
2019-04-08 19:02:18 +00:00
port := flag.Int("port", 8080, "server port")
dist := flag.Bool("dist", false, "final dist mode")
flag.Parse()
devserver.DevServe(&builder{*dist}, *port, "content", "build", "cache")
2016-09-07 04:13:37 +00:00
}
```
2021-06-09 03:53:41 +00:00
## Samples
2019-04-08 19:02:18 +00:00
Below are some examples of Goldsmith usage which can used to base your site on:
2023-12-31 19:54:56 +00:00
* [Basic Sample](https://git.foosoft.net/alex/goldsmith-samples/src/branch/master/basic): a great starting point, this
is the sample site from the tutorial.
* [Bootstrap Sample](https://git.foosoft.net/alex/goldsmith-samples/src/branch/master/bootstrap): a slightly more
advanced sample using [Bootstrap](https://getbootstrap.com/).
* [FooSoft.net](https://git.foosoft.net/alex/goldsmith): I've been "dogfooding" Goldsmith by using it to [generate my
homepage](/posts/generating-the-foosoft.net-homepage) for nearly a decade.
2019-04-08 19:02:18 +00:00
2021-06-09 03:53:41 +00:00
## Components
2019-04-08 19:02:18 +00:00
A growing set of plugins, filters, and other tools are provided to make it easier to get started with Goldsmith.
2021-06-09 03:53:41 +00:00
### Plugins
2019-04-08 19:02:18 +00:00
2023-12-31 03:50:32 +00:00
* [Absolute](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/absolute): Convert relative HTML file
2019-04-08 19:02:18 +00:00
references to absolute paths.
2023-12-31 03:50:32 +00:00
* [Breadcrumbs](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/breadcrumbs): Generate metadata
2019-04-08 23:17:12 +00:00
required to build breadcrumb navigation.
2023-12-31 03:50:32 +00:00
* [Collection](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/collection): Group related pages
2019-04-09 00:50:19 +00:00
into named collections.
2023-12-31 03:50:32 +00:00
* [Document](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/document): Enable simple DOM
2019-04-08 19:02:18 +00:00
modification via an API similar to jQuery.
2023-12-31 03:50:32 +00:00
* [Forward](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/forward): Create simple redirections
2022-07-04 00:53:05 +00:00
for pages that have moved to a new URL.
2023-12-31 03:50:32 +00:00
* [FrontMatter](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/frontmatter): Extract the
2019-04-08 23:17:12 +00:00
JSON, YAML, or TOML metadata stored in your files.
2023-12-31 03:50:32 +00:00
* [Index](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/index): Create metadata for directory
2022-07-04 00:53:05 +00:00
file listings and generate directory index pages.
2023-12-31 03:50:32 +00:00
* [Layout](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/layout): Transform your HTML files with
2019-04-08 23:17:12 +00:00
Go templates.
2023-12-31 03:50:32 +00:00
* [LiveJs](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/livejs): Inject JavaScript code to
2019-04-08 23:17:12 +00:00
automatically reload pages when modified.
2023-12-31 03:50:32 +00:00
* [Markdown](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/markdown): Render Markdown documents
2019-04-08 23:17:12 +00:00
as HTML fragments.
2023-12-31 03:50:32 +00:00
* [Minify](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/minify): Remove superfluous data from a
2019-04-08 19:02:18 +00:00
variety of web formats.
2023-12-31 03:50:32 +00:00
* [Pager](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/pager): Split arrays of metadata into
2019-04-08 19:02:18 +00:00
standalone pages.
2023-12-31 03:50:32 +00:00
* [Rule](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/rule): Update metadata and filter files
2022-07-06 02:33:40 +00:00
based on paths.
2023-12-31 03:50:32 +00:00
* [Summary](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/summary): Extract summary and title
2019-04-08 23:17:12 +00:00
metadata from HTML files.
2023-12-31 03:50:32 +00:00
* [Syndicate](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/syndicate): Generate RSS, Atom, and
2022-04-10 03:46:10 +00:00
JSON feeds from existing metadata.
2023-12-31 03:50:32 +00:00
* [Syntax](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/syntax): Enable syntax highlighting for
2019-04-08 23:17:12 +00:00
pre-formatted code blocks.
2023-12-31 03:50:32 +00:00
* [Tags](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/tags): Generate tag clouds and indices
2019-04-08 23:17:12 +00:00
from file metadata.
2023-12-31 03:50:32 +00:00
* [Thumbnail](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/thumbnail): Build thumbnails for a
2019-04-08 19:02:18 +00:00
variety of common image formats.
2021-06-09 03:53:41 +00:00
### Filters
2019-04-08 19:02:18 +00:00
2023-12-31 03:50:32 +00:00
* [Condition](https://godoc.org/git.foosoft.net/alex/goldsmith-components/filters/condition): Filter files based on a
2019-04-08 19:02:18 +00:00
single condition.
2023-12-31 03:50:32 +00:00
* [Operator](https://godoc.org/git.foosoft.net/alex/goldsmith-components/filters/operator): Join filters using
2019-04-08 19:02:18 +00:00
logical `AND`, `OR`, and `NOT` operators.
2023-12-31 03:50:32 +00:00
* [Wildcard](https://godoc.org/git.foosoft.net/alex/goldsmith-components/filters/wildcard): Filter files using path
2019-04-08 19:02:18 +00:00
wildcards (`*`, `?`, etc.)
2021-06-09 03:53:41 +00:00
### Other
2016-01-12 10:24:19 +00:00
2023-12-31 03:50:32 +00:00
* [DevServer](https://godoc.org/git.foosoft.net/alex/goldsmith-components/devserver): Simple framework for building,
2019-04-08 23:17:12 +00:00
updating, and viewing your site.
2023-12-31 03:50:32 +00:00
* [Harness](https://godoc.org/git.foosoft.net/alex/goldsmith-components/harness): Unit test harness for verifying
2019-04-08 23:17:12 +00:00
Goldsmith plugins and filters.