alex/goldsmith
1
Fork 0
Code Releases Activity

Update README

Browse Source
This commit is contained in:
Alex Yatskov 2023-12-30 19:50:32 -08:00
parent 9ecb479702
commit d2531e07e1
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

@ -8,7 +8,7 @@ anything from blogs to image galleries using the same tool.
Goldsmith does not use any configuration files, and all behavior customization happens in code. Goldsmith uses the 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 [builder pattern](https://en.wikipedia.org/wiki/Builder_pattern) to establish a chain, which modifies files as they pass
through it. Although the [Goldsmith](https://godoc.org/foosoft.net/projects/goldsmith) API is short and (hopefully) easy through it. Although the [Goldsmith](https://godoc.org/git.foosoft.net/alex/goldsmith) API is short and (hopefully) easy
to understand, it is often best to learn by example: to understand, it is often best to learn by example:
1. Start by copying files from a source directory to a destination directory (the simplest possible use case): 1. Start by copying files from a source directory to a destination directory (the simplest possible use case):
@ -20,7 +20,7 @@ to understand, it is often best to learn by example:
``` ```
2. Now let's convert any Markdown files to HTML fragments (while still copying the rest), using the 2. Now let's convert any Markdown files to HTML fragments (while still copying the rest), using the
[Markdown](https://godoc.org/foosoft.net/projects/goldsmith-components/plugins/markdown) plugin: [Markdown](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/markdown) plugin:
```go ```go
goldsmith. goldsmith.
@ -32,7 +32,7 @@ to understand, it is often best to learn by example:
3. If we have any 3. If we have any
[front matter](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 need to extract it using the, Markdown files, we need to extract it using the,
[FrontMatter](https://godoc.org/foosoft.net/projects/goldsmith-components/plugins/frontmatter) plugin: [FrontMatter](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/frontmatter) plugin:
```go ```go
goldsmith. goldsmith.
@ -45,7 +45,7 @@ to understand, it is often best to learn by example:
4. Next, we should run our barebones HTML through a 4. 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 elements like a header, footer, or 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/foosoft.net/projects/goldsmith-components/plugins/frontmatter) plugin: [Layout](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/frontmatter) plugin:
```go ```go
goldsmith. goldsmith.
@ -58,7 +58,7 @@ to understand, it is often best to learn by example:
5. Now, let's [minify](https://en.wikipedia.org/wiki/Minification_(programming)) our files to reduce data transfer and 5. 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 load times for our site's visitors using the
[Minify](https://godoc.org/foosoft.net/projects/goldsmith-components/plugins/minify) plugin: [Minify](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/minify) plugin:
```go ```go
goldsmith. goldsmith.
@ -71,7 +71,7 @@ to understand, it is often best to learn by example:
``` ```
6. Debugging problems in minified code can be tricky, so let's use the 6. Debugging problems in minified code can be tricky, so let's use the
[Condition](https://godoc.org/foosoft.net/projects/goldsmith-components/filters/condition) filter to make [Condition](https://godoc.org/git.foosoft.net/alex/goldsmith-components/filters/condition) filter to make
minification occur only when we are ready for distribution. minification occur only when we are ready for distribution.
```go ```go
@ -87,7 +87,7 @@ to understand, it is often best to learn by example:
``` ```
7. Now that we have all of our plugins chained up, let's look at a complete example which uses 7. Now that we have all of our plugins chained up, let's look at a complete example which uses
[DevServer](https://godoc.org/foosoft.net/projects/goldsmith-components/devserver) to bootstrap a complete [DevServer](https://godoc.org/git.foosoft.net/alex/goldsmith-components/devserver) to bootstrap a complete
development sever which automatically rebuilds the site whenever source files are updated. development sever which automatically rebuilds the site whenever source files are updated.
```go ```go
@ -97,13 +97,13 @@ to understand, it is often best to learn by example:
"flag" "flag"
"log" "log"
"foosoft.net/projects/goldsmith" "git.foosoft.net/alex/goldsmith"
"foosoft.net/projects/goldsmith-components/devserver" "git.foosoft.net/alex/goldsmith-components/devserver"
"foosoft.net/projects/goldsmith-components/filters/condition" "git.foosoft.net/alex/goldsmith-components/filters/condition"
"foosoft.net/projects/goldsmith-components/plugins/frontmatter" "git.foosoft.net/alex/goldsmith-components/plugins/frontmatter"
"foosoft.net/projects/goldsmith-components/plugins/layout" "git.foosoft.net/alex/goldsmith-components/plugins/layout"
"foosoft.net/projects/goldsmith-components/plugins/markdown" "git.foosoft.net/alex/goldsmith-components/plugins/markdown"
"foosoft.net/projects/goldsmith-components/plugins/minify" "git.foosoft.net/alex/goldsmith-components/plugins/minify"
) )
type builder struct { type builder struct {
@ -143,7 +143,7 @@ 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://foosoft.net/projects/goldsmith): I've been "dogfooding" Goldsmith by using it to build * [FooSoft.net](https://git.foosoft.net/alex/goldsmith): I've been "dogfooding" Goldsmith by using it to build
my homepage for years. my homepage for years.
## Components ## Components
@ -152,55 +152,55 @@ A growing set of plugins, filters, and other tools are provided to make it easie
### Plugins ### Plugins
* [Absolute](https://godoc.org/foosoft.net/projects/goldsmith-components/plugins/absolute): Convert relative HTML file * [Absolute](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/absolute): Convert relative HTML file
references to absolute paths. references to absolute paths.
* [Breadcrumbs](https://godoc.org/foosoft.net/projects/goldsmith-components/plugins/breadcrumbs): Generate metadata * [Breadcrumbs](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/breadcrumbs): Generate metadata
required to build breadcrumb navigation. required to build breadcrumb navigation.
* [Collection](https://godoc.org/foosoft.net/projects/goldsmith-components/plugins/collection): Group related pages * [Collection](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/collection): Group related pages
into named collections. into named collections.
* [Document](https://godoc.org/foosoft.net/projects/goldsmith-components/plugins/document): Enable simple DOM * [Document](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/document): Enable simple DOM
modification via an API similar to jQuery. modification via an API similar to jQuery.
* [Forward](https://godoc.org/foosoft.net/projects/goldsmith-components/plugins/forward): Create simple redirections * [Forward](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/forward): Create simple redirections
for pages that have moved to a new URL. for pages that have moved to a new URL.
* [FrontMatter](https://godoc.org/foosoft.net/projects/goldsmith-components/plugins/frontmatter): Extract the * [FrontMatter](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/frontmatter): Extract the
JSON, YAML, or TOML metadata stored in your files. JSON, YAML, or TOML metadata stored in your files.
* [Index](https://godoc.org/foosoft.net/projects/goldsmith-components/plugins/index): Create metadata for directory * [Index](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/index): Create metadata for directory
file listings and generate directory index pages. file listings and generate directory index pages.
* [Layout](https://godoc.org/foosoft.net/projects/goldsmith-components/plugins/layout): Transform your HTML files with * [Layout](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/layout): Transform your HTML files with
Go templates. Go templates.
* [LiveJs](https://godoc.org/foosoft.net/projects/goldsmith-components/plugins/livejs): Inject JavaScript code to * [LiveJs](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/livejs): Inject JavaScript code to
automatically reload pages when modified. automatically reload pages when modified.
* [Markdown](https://godoc.org/foosoft.net/projects/goldsmith-components/plugins/markdown): Render Markdown documents * [Markdown](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/markdown): Render Markdown documents
as HTML fragments. as HTML fragments.
* [Minify](https://godoc.org/foosoft.net/projects/goldsmith-components/plugins/minify): Remove superfluous data from a * [Minify](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/minify): Remove superfluous data from a
variety of web formats. variety of web formats.
* [Pager](https://godoc.org/foosoft.net/projects/goldsmith-components/plugins/pager): Split arrays of metadata into * [Pager](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/pager): Split arrays of metadata into
standalone pages. standalone pages.
* [Rule](https://godoc.org/foosoft.net/projects/goldsmith-components/plugins/rule): Update metadata and filter files * [Rule](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/rule): Update metadata and filter files
based on paths. based on paths.
* [Summary](https://godoc.org/foosoft.net/projects/goldsmith-components/plugins/summary): Extract summary and title * [Summary](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/summary): Extract summary and title
metadata from HTML files. metadata from HTML files.
* [Syndicate](https://godoc.org/foosoft.net/projects/goldsmith-components/plugins/syndicate): Generate RSS, Atom, and * [Syndicate](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/syndicate): Generate RSS, Atom, and
JSON feeds from existing metadata. JSON feeds from existing metadata.
* [Syntax](https://godoc.org/foosoft.net/projects/goldsmith-components/plugins/syntax): Enable syntax highlighting for * [Syntax](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/syntax): Enable syntax highlighting for
pre-formatted code blocks. pre-formatted code blocks.
* [Tags](https://godoc.org/foosoft.net/projects/goldsmith-components/plugins/tags): Generate tag clouds and indices * [Tags](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/tags): Generate tag clouds and indices
from file metadata. from file metadata.
* [Thumbnail](https://godoc.org/foosoft.net/projects/goldsmith-components/plugins/thumbnail): Build thumbnails for a * [Thumbnail](https://godoc.org/git.foosoft.net/alex/goldsmith-components/plugins/thumbnail): Build thumbnails for a
variety of common image formats. variety of common image formats.
### Filters ### Filters
* [Condition](https://godoc.org/foosoft.net/projects/goldsmith-components/filters/condition): Filter files based on a * [Condition](https://godoc.org/git.foosoft.net/alex/goldsmith-components/filters/condition): Filter files based on a
single condition. single condition.
* [Operator](https://godoc.org/foosoft.net/projects/goldsmith-components/filters/operator): Join filters using * [Operator](https://godoc.org/git.foosoft.net/alex/goldsmith-components/filters/operator): Join filters using
logical `AND`, `OR`, and `NOT` operators. logical `AND`, `OR`, and `NOT` operators.
* [Wildcard](https://godoc.org/foosoft.net/projects/goldsmith-components/filters/wildcard): Filter files using path * [Wildcard](https://godoc.org/git.foosoft.net/alex/goldsmith-components/filters/wildcard): Filter files using path
wildcards (`*`, `?`, etc.) wildcards (`*`, `?`, etc.)
### Other ### Other
* [DevServer](https://godoc.org/foosoft.net/projects/goldsmith-components/devserver): Simple framework for building, * [DevServer](https://godoc.org/git.foosoft.net/alex/goldsmith-components/devserver): Simple framework for building,
updating, and viewing your site. updating, and viewing your site.
* [Harness](https://godoc.org/foosoft.net/projects/goldsmith-components/harness): Unit test harness for verifying * [Harness](https://godoc.org/git.foosoft.net/alex/goldsmith-components/harness): Unit test harness for verifying
Goldsmith plugins and filters. Goldsmith plugins and filters.