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
[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:
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
[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
goldsmith.
@ -32,7 +32,7 @@ to understand, it is often best to learn by example:
3. If we have any
[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,
[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
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
[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
[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
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
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
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
[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.
```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
[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.
```go
@ -97,13 +97,13 @@ to understand, it is often best to learn by example:
"flag"
"log"
"foosoft.net/projects/goldsmith"
"foosoft.net/projects/goldsmith-components/devserver"
"foosoft.net/projects/goldsmith-components/filters/condition"
"foosoft.net/projects/goldsmith-components/plugins/frontmatter"
"foosoft.net/projects/goldsmith-components/plugins/layout"
"foosoft.net/projects/goldsmith-components/plugins/markdown"
"foosoft.net/projects/goldsmith-components/plugins/minify"
"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"
)
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.
* [Bootstrap Sample](https://github.com/FooSoft/goldsmith-samples/tree/master/bootstrap): a slightly more advanced
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.
## Components
@ -152,55 +152,55 @@ A growing set of plugins, filters, and other tools are provided to make it easie
### 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.
* [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.
* [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.
* [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.
* [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.
* [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.
* [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.
* [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.
* [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.
* [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.
* [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.
* [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.
* [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.
* [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.
* [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.
* [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.
* [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.
* [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.
### 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.
* [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.
* [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.)
### 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.
* [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.