Documentation
¶
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.
TODO: Add usage examples
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.
The Generator is safe for concurrent use once created, though Generate operations should not be run concurrently on the same Generator instance.
Example ¶
Example demonstrates basic usage of the generator package.
package main
import (
"context"
"fmt"
"os"
"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, generator.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)
Example (RawOutput) ¶
Example_rawOutput demonstrates using raw output mode.
package main
import (
"context"
"fmt"
"os"
"github.com/harrydayexe/GoBlog/v2/pkg/generator"
)
func main() {
// Raw output mode generates HTML without templates
fsys := os.DirFS("testdata")
gen := generator.New(fsys, generator.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
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type GeneratedBlog ¶
type GeneratedBlog struct {
Posts map[string][]byte // Posts maps a slug to raw HTML bytes for each post
Index []byte // Index contains the raw HTML for the blog index page
Tags map[string][]byte // Tags maps each tag name to its tag page HTML
}
GeneratedBlog contains all the HTML content for a complete static blog site.
It includes individual post pages, the main index page, and tag pages. All content is stored as raw HTML bytes ready to be written to files or served via HTTP.
Post slugs are derived from markdown filenames. Tag names are extracted from post front matter. For more info see pkg/models/Post.
Example ¶
ExampleGeneratedBlog demonstrates working with a GeneratedBlog.
package main
import (
"context"
"fmt"
"os"
"github.com/harrydayexe/GoBlog/v2/pkg/generator"
)
func main() {
fsys := os.DirFS("testdata")
gen := generator.New(fsys, generator.WithRawOutput())
ctx := context.Background()
blog, err := gen.Generate(ctx)
if err != nil {
fmt.Println("Error:", err)
return
}
// Access posts map and verify structure
fmt.Printf("Total posts: %d\n", len(blog.Posts))
fmt.Printf("Has Posts map: %t\n", blog.Posts != nil)
fmt.Printf("Has Tags map: %t\n", blog.Tags != nil)
}
Output: Total posts: 3 Has Posts map: true Has Tags map: true
func NewEmptyGeneratedBlog ¶ added in v2.0.3
func NewEmptyGeneratedBlog() *GeneratedBlog
type Generator ¶
type Generator struct {
// contains filtered or unexported fields
}
Generator produces HTML output based on its input configuration. It reads markdown files from a configured filesystem and renders them as HTML using templates.
A Generator is safe for concurrent use after creation, but Generate operations should not be called concurrently on the same instance.
func New ¶
New creates a new Generator with the specified options. It returns an error if the configuration is invalid or if required resources cannot be initialized.
Options can be provided to customize behavior such as template directories, posts per page, and other generation parameters.
Example ¶
ExampleNew demonstrates creating a new generator.
package main
import (
"fmt"
"os"
"github.com/harrydayexe/GoBlog/v2/pkg/generator"
)
func main() {
// Create a generator with default configuration
fsys := os.DirFS("testdata")
gen := generator.New(fsys)
if gen != nil {
fmt.Println("Generator created")
}
}
Output: Generator created
func NewWithConfig ¶ added in v2.0.3
func NewWithConfig(config *GeneratorConfig) *Generator
Example ¶
ExampleNewWithConfig demonstrates creating a generator with custom configuration.
package main
import (
"fmt"
"os"
"github.com/harrydayexe/GoBlog/v2/pkg/generator"
)
func main() {
fsys := os.DirFS("testdata")
// Create a custom configuration
config := &generator.GeneratorConfig{
PostsDir: fsys,
RawOutput: true,
}
gen := generator.NewWithConfig(config)
if gen != nil {
fmt.Println("Generator created with custom config")
}
}
Output: Generator created with custom config
func (*Generator) DebugConfig ¶ added in v2.0.3
DebugConfig logs the current generator configuration at the debug level.
This method is useful for troubleshooting and verifying configuration settings during development or when diagnosing issues. The output includes all generator configuration details and respects the provided context for structured logging.
The log output will only appear if the logger is configured to show debug level messages.
Example ¶
ExampleGenerator_DebugConfig demonstrates debugging generator configuration.
package main
import (
"context"
"fmt"
"os"
"github.com/harrydayexe/GoBlog/v2/pkg/generator"
)
func main() {
fsys := os.DirFS("testdata")
gen := generator.New(fsys, generator.WithRawOutput())
ctx := context.Background()
gen.DebugConfig(ctx)
fmt.Println("Debug output logged")
}
Output: Debug output logged
func (*Generator) Generate ¶
func (g *Generator) Generate(ctx context.Context) (*GeneratedBlog, error)
Generate reads markdown post files from the configured filesystem and generates a complete static blog site as HTML.
It returns a GeneratedBlog containing all rendered HTML content including individual post pages, tag pages, and the index page. The returned content is in-memory only; callers are responsible for writing to disk or serving via HTTP as needed.
Generate respects the provided context and will return early with context.Canceled or context.DeadlineExceeded if the context is canceled or times out.
It returns an error if markdown files cannot be read, parsing fails, or template rendering encounters an error.
Example ¶
ExampleGenerator_Generate demonstrates generating a blog.
package main
import (
"context"
"fmt"
"os"
"github.com/harrydayexe/GoBlog/v2/pkg/generator"
)
func main() {
fsys := os.DirFS("testdata")
gen := generator.New(fsys, generator.WithRawOutput())
ctx := context.Background()
blog, err := gen.Generate(ctx)
if err != nil {
fmt.Println("Error:", err)
return
}
fmt.Println("Blog generation complete")
fmt.Printf("Total posts: %d\n", len(blog.Posts))
}
Output: Blog generation complete Total posts: 3
type GeneratorConfig ¶
type GeneratorConfig struct {
PostsDir fs.FS // The filesystem containing the input posts in markdown
TemplatesDir fs.FS // The filesystem containing the templates to use
// When true, output should contain only the raw HTML and not be inserted
// into a template
RawOutput bool
ParserConfig parser.Config // The config to use when parsing
}
GeneratorConfig contains all the configuration to control how a Generator operates.
PostsDir specifies the filesystem containing markdown post files. Each file should contain front matter metadata and post content.
TemplatesDir specifies the filesystem containing HTML templates for rendering the blog. If not specified, default templates will be used.
func (GeneratorConfig) String ¶ added in v2.0.3
func (c GeneratorConfig) String() string
type Option ¶
type Option func(*GeneratorConfig)
Option is a function which modifies a GeneratorConfig. Options are used to configure optional parameters when creating a new Generator.
func WithRawOutput ¶ added in v2.0.3
func WithRawOutput() Option
WithRawOutput sets the config to only generate the raw HTML for each post without inserting it into a template.
Example ¶
ExampleWithRawOutput demonstrates using the WithRawOutput option.
package main
import (
"context"
"fmt"
"os"
"github.com/harrydayexe/GoBlog/v2/pkg/generator"
)
func main() {
fsys := os.DirFS("testdata")
// Enable raw output mode (no templates)
gen := generator.New(fsys, generator.WithRawOutput())
ctx := context.Background()
blog, err := gen.Generate(ctx)
if err != nil {
fmt.Println("Error:", err)
return
}
fmt.Println("Raw output enabled")
fmt.Printf("Generated posts: %d\n", len(blog.Posts))
}
Output: Raw output enabled Generated posts: 3
Source Files