alex/goldsmith
1
Fork 0
Code Releases Activity

Updating README.md

Browse Source
This commit is contained in:
Alex Yatskov 2019-04-08 16:17:12 -07:00
parent 1b69ddd80e
commit b84dbb7155
1 changed files with 38 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
README.md
View File

@ -1,17 +1,17 @@
# Goldsmith # # Goldsmith #
Goldsmith is a fast and easily extensible static website generator written in Go. In contrast to other generators, 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 organizational schemes on the user, making it possible to create Goldsmith does not force any design paradigms or file organization rules on the user, making it possible to generate
anything from blogs to image galleries using the same tool. anything from blogs to image galleries using the same tool.
## Tutorial ## ## Tutorial ##
Goldsmith does not use any configuration files, and all generation behavior is described through code. Goldsmith uses Goldsmith does not use any configuration files, and all behavior customization happens in code. Goldsmith uses the
the [builder pattern](https://en.wikipedia.org/wiki/Builder_pattern) to establish a chain, which modifies files as they [builder pattern](https://en.wikipedia.org/wiki/Builder_pattern) to establish a chain, which modifies files as they pass
pass through it. Although the [Goldsmith](https://godoc.org/github.com/FooSoft/goldsmith) is short and (hopefully) easy through it. Although the [Goldsmith](https://godoc.org/github.com/FooSoft/goldsmith) is short and (hopefully) easy to
to understand, I find it is best to learn by example: understand, it is often best to learn by example:
* Start by copying files from a source directory to a destination directory (simplest possible use case): * Start by copying files from a source directory to a destination directory (the simplest possible use case):
```go ```go
goldsmith. goldsmith.
@ -19,7 +19,7 @@ to understand, I find it is best to learn by example:
End(dstDir) // write files to dstDir End(dstDir) // write files to dstDir
``` ```
* Now let's convert any Markdown files to HTML (while copying the rest), using the * Now let's convert any Markdown files to HTML fragments (while still copying the rest), using the
[Markdown](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/markdown) plugin: [Markdown](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/markdown) plugin:
```go ```go
@ -30,9 +30,9 @@ to understand, I find it is best to learn by example:
``` ```
* If we have any * If we have any
[frontmatter](https://raw.githubusercontent.com/FooSoft/goldsmith-samples/master/basic/content/index.md) in our [front matter](https://raw.githubusercontent.com/FooSoft/goldsmith-samples/master/basic/content/index.md) in our
Markdown files, we should extract it using the, Markdown files, we need to extract it using the,
[Frontmatter](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/frontmatter) plugin: [FrontMatter](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/frontmatter) plugin:
```go ```go
goldsmith. goldsmith.
@ -42,9 +42,9 @@ to understand, I find it is best to learn by example:
End(dstDir) // write files to dstDir End(dstDir) // write files to dstDir
``` ```
* Next we want to run our barebones HTML through a * Next, we should run our barebones HTML through a
[template](https://raw.githubusercontent.com/FooSoft/goldsmith-samples/master/basic/content/layouts/basic.gohtml) to [template](https://raw.githubusercontent.com/FooSoft/goldsmith-samples/master/basic/content/layouts/basic.gohtml) to
add a header, footer, and a menu; for this we can use the add elements like a header, footer, or a menu; for this we can use the
[Layout](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/frontmatter) plugin: [Layout](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/frontmatter) plugin:
```go ```go
@ -56,7 +56,8 @@ to understand, I find it is best to learn by example:
End(dstDir) // write files to dstDir End(dstDir) // write files to dstDir
``` ```
* Now, let's minify our files to reduce data transfer and load times for our site's visitors using the * Now, let's [minify](https://en.wikipedia.org/wiki/Minification_(programming)) our files to reduce data transfer and
load times for our site's visitors using the
[Minify](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/minify) plugin: [Minify](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/minify) plugin:
```go ```go
@ -69,9 +70,9 @@ to understand, I find it is best to learn by example:
End(dstDir) // write files to dstDir End(dstDir) // write files to dstDir
``` ```
* Debugging problems in minified code can be annoying, so let's use the * Debugging problems in minified code can be tricky, so let's use the
[Condition](https://godoc.org/github.com/FooSoft/goldsmith-components/filters/condition) filter to make it happen [Condition](https://godoc.org/github.com/FooSoft/goldsmith-components/filters/condition) filter to make minification
only when we are ready for final distribution. occur only when we are ready for distribution.
```go ```go
goldsmith. goldsmith.
@ -142,8 +143,6 @@ Below are some examples of Goldsmith usage which can used to base your site on:
sample site from the tutorial. sample site from the tutorial.
* [Bootstrap Sample](https://github.com/FooSoft/goldsmith-samples/tree/master/bootstrap): a slightly more advanced * [Bootstrap Sample](https://github.com/FooSoft/goldsmith-samples/tree/master/bootstrap): a slightly more advanced
sample using [Bootstrap](https://getbootstrap.com/). sample using [Bootstrap](https://getbootstrap.com/).
* [FooSoft.net](https://github.com/FooSoft/foosoft.net): the source for [my homepage](http://foosoft.net),
using most plugins and filters.
## Components ## ## Components ##
@ -154,31 +153,32 @@ A growing set of plugins, filters, and other tools are provided to make it easie
* [Absolute](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/absolute): Convert relative HTML file * [Absolute](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/absolute): Convert relative HTML file
references to absolute paths. references to absolute paths.
* [Breadcrumbs](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/breadcrumbs): Generate metadata * [Breadcrumbs](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/breadcrumbs): Generate metadata
required to enable breadcrumb navigation. required to build breadcrumb navigation.
* [Collection](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/collection): Group related pages * [Collection](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/collection): Group related pages
into named collections. into named collections.
* [Document](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/document): Enable simple DOM * [Document](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/document): Enable simple DOM
modification via an API similar to jQuery. modification via an API similar to jQuery.
* [FrontMatter](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/frontmatter): Extract the metadata * [FrontMatter](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/frontmatter): Extract the
stored in your files. JSON, YAML, or TOML metadata stored in your files.
* [Index](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/index): Create metadata for file * [Index](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/index): Create metadata for directory file
listings and generate directory index pages. listings and generate directory index pages.
* [Layout](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/layout): Transform your HTML with Go * [Layout](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/layout): Transform your HTML files with
templates. Go templates.
* [LiveJs](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/livejs): Inject code to automatically * [LiveJs](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/livejs): Inject JavaScript code to
reload pages when they are modified. automatically reload pages when modified.
* [Markdown](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/markdown): Render Markdown documents * [Markdown](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/markdown): Render Markdown documents
to HTML fragments. as HTML fragments.
* [Minify](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/minify): Remove superfluous data from a * [Minify](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/minify): Remove superfluous data from a
variety of web formats. variety of web formats.
* [Pager](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/pager): Split arrays of metadata into * [Pager](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/pager): Split arrays of metadata into
standalone pages. standalone pages.
* [Summary](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/summary): Generate summary and title * [Summary](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/summary): Extract summary and title
metadata for HTML files. metadata from HTML files.
* [Syntax](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/syntax): Generate syntax highlighting for * [Syntax](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/syntax): Enable syntax highlighting for
preformatted code blocks. pre-formatted code blocks.
* [Tags](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/tags): Build tag clouds from file metadata. * [Tags](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/tags): Generate tag clouds and indices
* [Thumbnail](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/thumbnail): Generate thumbnails for a from file metadata.
* [Thumbnail](https://godoc.org/github.com/FooSoft/goldsmith-components/plugins/thumbnail): Build thumbnails for a
variety of common image formats. variety of common image formats.
### Filters ### ### Filters ###
@ -192,10 +192,10 @@ A growing set of plugins, filters, and other tools are provided to make it easie
### Other ### ### Other ###
* [DevServer](https://godoc.org/github.com/FooSoft/goldsmith-components/devserver): Simple framework for generating * [DevServer](https://godoc.org/github.com/FooSoft/goldsmith-components/devserver): Simple framework for building,
and viewing your site. updating, and viewing your site.
* [Harness](https://godoc.org/github.com/FooSoft/goldsmith-components/harness): Unit test harness for Goldsmith * [Harness](https://godoc.org/github.com/FooSoft/goldsmith-components/harness): Unit test harness for verifying
plugins and filters. Goldsmith plugins and filters.
## License ## ## License ##