generator

Overview ¶

Package generator provides functionality for generating static HTML blog sites from markdown files.

The generator uses the functional options pattern for configuration. Required parameters are passed as positional arguments, while optional parameters are configured via option functions.

Basic Usage ¶

Create a generator and generate a blog:

import (
	"context"
	"os"
	"github.com/harrydayexe/GoBlog/v2/pkg/generator"
	"github.com/harrydayexe/GoBlog/v2/pkg/config"
	"github.com/harrydayexe/GoBlog/v2/pkg/templates"
)

fsys := os.DirFS("posts/")
renderer, err := generator.NewTemplateRenderer(templates.Default)
if err != nil {
	log.Fatal(err)
}
gen := generator.New(fsys, renderer)

// Generate the blog
blog, err := gen.Generate(context.Background())
if err != nil {
	log.Fatal(err)
}

In raw output mode no templates are applied, so the renderer may be nil:

gen := generator.New(fsys, nil, config.WithRawOutput())

Custom Template Functions ¶

Additional template functions can be registered via config.WithFuncs and passed to NewTemplateRenderer. Once registered, the function is available in every template as a regular call:

import (
	"html/template"
	"strings"
)

renderer, err := generator.NewTemplateRenderer(
	templates.Default,
	config.WithFuncs(template.FuncMap{
		"upper": strings.ToUpper,
	}),
)

In a template:

<h1>{{upper .Post.Title}}</h1>

The built-in helpers (formatDate, shortDate, year) remain available unless intentionally replaced. Registering a function whose name matches a built-in silently replaces that built-in — useful for custom date formats but a potential footgun if done accidentally. See config.WithFuncs for the full list of reserved names.

Custom Template Data ¶

Arbitrary key-value data from the calling application can be injected into every rendered page via config.WithCustomData. The data is accessible in templates as {{.Custom.key}}:

gen := generator.New(fsys, renderer,
	config.WithCustomData(map[string]any{
		"author":      "Jane Smith",
		"analyticsID": "UA-12345",
	}),
)

In a template:

{{with .Custom}}
    <meta name="author" content="{{.author}}">
{{end}}

.Custom is nil when no WithCustomData option is supplied; templates should guard access with {{with .Custom}} or {{if .Custom}} to avoid nil-map errors. Multiple WithCustomData calls merge their maps; later values overwrite earlier ones for duplicate keys.

Page Path ¶

Every rendered page receives a Path field on its template data containing the URL path for that page. It is accessible in templates as {{.Path}}:

<link rel="canonical" href="https://example.com{{.Path}}">
<meta property="og:url" content="https://example.com{{.Path}}">

By default (clean-URL mode) the value includes BlogRoot and no .html suffix:

• Index page: / (or /blog/ when BlogRoot = "/blog/")
• Post page: /posts/<slug>
• Tag page: /tags/<tag>
• Tags index page: /tags

When config.WithHTMLPaths is applied (automatically set by the goblog generate CLI), paths include the .html extension to match the files written to disk:

• Index page: /index.html (or /blog.html when BlogRoot = "/blog/")
• Post page: /posts/<slug>.html
• Tag page: /tags/<tag>.html
• Tags index page: /tags.html

The pkg/server package accepts both clean URLs and .html URLs via its built-in StripHTMLExtension middleware, so the server always uses clean-URL paths regardless of the generating option.

Output ¶

The Generator returns all generated content in memory via GeneratedBlog. Callers are responsible for I/O operations such as writing files to disk or serving content via HTTP.

See the examples_test.go file for more usage examples.

Concurrency ¶

The Generator is safe for concurrent use once created, though Generate operations should not be run concurrently on the same Generator instance.

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/harrydayexe/GoBlog/v2/pkg/config"
	"github.com/harrydayexe/GoBlog/v2/pkg/generator"
)

func main() {
	// Create a generator with posts from testdata directory
	fsys := os.DirFS("testdata")
	gen := generator.New(fsys, nil, config.WithRawOutput())

	// Generate the blog
	ctx := context.Background()
	blog, err := gen.Generate(ctx)
	if err != nil {
		fmt.Println("Error:", err)
		return
	}

	fmt.Printf("Generated %d post(s)\n", len(blog.Posts))
}

Output:
Generated 3 post(s)

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/harrydayexe/GoBlog/v2/pkg/config"
	"github.com/harrydayexe/GoBlog/v2/pkg/generator"
)

func main() {
	// Raw output mode generates HTML without templates
	fsys := os.DirFS("testdata")
	gen := generator.New(fsys, nil, config.WithRawOutput())

	ctx := context.Background()
	blog, err := gen.Generate(ctx)
	if err != nil {
		fmt.Println("Error:", err)
		return
	}

	fmt.Println("Raw HTML mode enabled")
	fmt.Printf("Posts generated: %d\n", len(blog.Posts))
}

Output:
Raw HTML mode enabled
Posts generated: 3