DEV Community: Chase Fleming

Building a Go Static Site Generator Using elem-go and goldmark

Chase Fleming — Thu, 07 Dec 2023 21:43:40 +0000

In this tutorial, we'll build a static site generator using elem-go for HTML templating and goldmark for Markdown processing. This generator will convert Markdown files into HTML and create an index page listing all posts.

Note: You can clone this template to use or follow along with the tutorial.

Explaining the Dependencies

elem-go: A Go library for type-safe HTML element creation. It simplifies the process of building HTML templates in Go.
goldmark: A Markdown parser and renderer for Go. It converts Markdown files into HTML.

Creating Our Project

We'll structure our project with a main Go file, a posts directory for Markdown, a public directory for the generated HTML, and a Go module file. In the end, it will look like this:

my-static-site/
│
├── main.go             # Your main Go file
├── posts/              # Directory containing Markdown files
│   ├── post1.md
│   ├── post2.md
│   └── ...
├── public/             # Directory where generated HTML files will be stored
└── go.mod              # Go module file

To begin, let's create our project directory, navigate to it, and initialize a new Go project:

mkdir my-static-site
cd my-static-site
go mod init my-static-site

Next, we need to install our dependencies:

go get github.com/chasefleming/elem-go
go get github.com/yuin/goldmark

Adding Our Content

Next, create a posts directory and a hello-world.md Markdown file within it. This file will serve as your first post on the site.

mkdir posts
touch posts/hello-world.md

Let's also add some content:

# Hello, World!  

This is a sample post to get you started. You can edit or delete this post and begin adding your content.

Building Our Generator

Our generator code will take the Markdown files we have and convert them into HTML pages. The conversion of Markdown to HTML will happen with the goldmark library, but the templating of the pages will happen in elem-go. It enables writing type-safe Go code to generate HTML, eliminating the need to parse separate template files.

Let's first create our main.go file:

touch main.go

In main.go, let's import the dependencies we need:

package main  

import (  
    "github.com/chasefleming/elem-go"
    "github.com/chasefleming/elem-go/attrs"
    "github.com/chasefleming/elem-go/styles"
    "github.com/yuin/goldmark"
)

You'll notice the elem-go has two subpackages. These come with elem-go and provide type-safe ways of handling attributes and styles. They help avoid having to write common strings and come with other utility methods.

Next, let's make a layout function that takes a title and content and returns the html structure of our page using the arguments passed in:

func layout(title string, content elem.Node) string {  
    htmlPage := elem.Html(nil,  
       elem.Head(nil,  
          elem.Title(nil, elem.Text(title)),  
       ),       elem.Body(nil,  
          elem.Header(nil, elem.H1(nil, elem.Text(title))),  
          elem.Main(nil, content),  
          elem.Footer(nil, elem.Text("Footer content here")),  
       ),    )  
    return htmlPage.Render()  
}

You'll notice that instead of having to write HTML, you can use elem-go to generate HTML with methods like elem.Main which generates a <main> element.

After that, let's create another function to actually write the HTML generated with layout to a file based on the title. Since we generated a chunk of HTML using goldmark and it's not elem-go syntax, we'll pass it into elem.Raw which takes raw HTML and returns an elem.Node type which is compatible with the library:

func createHTMLPage(title, content string) string {  
    htmlOutput := layout(title, elem.Raw(content))  

    postFilename := title + ".html"  
    filepath := filepath.Join("public", postFilename)  
    os.WriteFile(filepath, []byte(htmlOutput), 0644)  
    return postFilename  
}

We also need a function that will take our Markdown and use goldmark to convert it to HTML. Let's add that:

func markdownToHTML(content string) string {  
    var buf bytes.Buffer  
    md := goldmark.New()  
    if err := md.Convert([]byte(content), &buf); err != nil {  
       log.Fatal(err)  
    }    return buf.String()  
}

Now that we have that, we'll additionally need a function that will walk through all of our posts, read the file, and pass the found markdown to the markdownToHTML function we just created. The return of the function should be an array of all the converted posts:

func readMarkdownPosts(dir string) []string {  
    var posts []string  
    err := filepath.Walk(dir, func(path string, info os.FileInfo, err error) error {  
       if !info.IsDir() {  
          content, err := os.ReadFile(path)  
          if err != nil {  
             return err  
          }  

          htmlContent := markdownToHTML(string(content))  
          title := strings.TrimSuffix(info.Name(), filepath.Ext(info.Name()))  
          postFilename := createHTMLPage(title, htmlContent)  

          posts = append(posts, postFilename)  
       }       return nil  
    })  
    if err != nil {  
       log.Fatal(err)  
    }    return posts  
}

All of our posts pages aren't great if we don't have an index page to find them all from. Again using elem-go, make a simple list of items with elem.A, elem.Ul, and elem.Ul and pass it to our layout. We also use the attrs subpackage to add the href using attrs.Href inside of attrs.Props{} to the <a> element. After that we'll save it to public/index.html:

func createIndexPage(postFilenames []string) {  
    listItems := make([]elem.Node, len(postFilenames))  
    for i, filename := range postFilenames {  
       link := elem.A(attrs.Props{attrs.Href: "./" + filename}, elem.Text(filename))  
       listItems[i] = elem.Li(nil, link)  
    }  
    indexContent := elem.Ul(nil, listItems...)  
    htmlOutput := layout("Home", indexContent)  

    filepath := filepath.Join("public", "index.html")  
    os.WriteFile(filepath, []byte(htmlOutput), 0644)  
}

When we run our project remember we'll not have created the posts or public directories yet, so let's make a function to create those directories if they don't exist:

func createDirIfNotExist(dir string) {  
    if _, err := os.Stat(dir); os.IsNotExist(err) {  
       err := os.Mkdir(dir, 0755) // or 0700 if you need it to be private  
       if err != nil {  
          log.Fatal(err)  
       }    }}

Now in our main function we can put it all together to first create the required directories, then read and create all the posts, then create our index page:

func main() {  
    createDirIfNotExist("posts")  
    createDirIfNotExist("public")  

    posts := readMarkdownPosts("posts")  
    createIndexPage(posts)  
}

Styling Our Site

elem-go's styles subpackage lets you create groups of style properties in a type-safe way. Let's create some styles to make our site look better:

headerStyle := styles.Props{  
    styles.BackgroundColor: "lightblue",  
    styles.Color:           "white",  
    styles.Padding:         "10px",  
    styles.TextAlign:       "center",  
}  

footerStyle := styles.Props{  
    styles.BackgroundColor: "lightgrey",  
    styles.Color:           "black",  
    styles.Padding:         "10px",  
    styles.TextAlign:       "center",  
}  

mainStyle := styles.Props{  
    styles.Padding: "20px",  
}

Then we'll use the attrs subpackage to add them as an inline-style and convert the style object to an inline style string using ToInline():

elem.Body(nil,  
    elem.Header(attrs.Props{attrs.Style: headerStyle.ToInline()},  
       elem.H1(nil, elem.Text(title)),  
    ),    elem.Main(attrs.Props{attrs.Style: mainStyle.ToInline()},  
       content,  
    ),    elem.Footer(attrs.Props{attrs.Style: footerStyle.ToInline()},  
       elem.Text("Footer content here"),  
    ),),

Opening Our Site

We did it! We now have a static site. Open public/index.html in your browser to see it working:

open public/index.html

Or if you're on Windows, run:

start public\index.html

Building a Counter App with htmx, Go Fiber, and elem-go

Chase Fleming — Fri, 06 Oct 2023 21:06:03 +0000

In this tutorial, we'll build a simple counter application using Go Fiber, htmx, and the elem-go library for type-safe HTML templating.

Explaining the Dependencies

We'll use three primary packages to build the app:

Go Fiber: An HTTP web server implementation inspired by Express.js's design in Node.js. Go Fiber facilitates the development of speedy and scalable web applications in Go.
htmx: Provides direct access to AJAX, WebSockets, and Server-Sent Events in HTML, simplifying dynamic updates of web pages without full reloads.
elem-go: A nimble Go library designed for programmatic and type-safe HTML element creation and management. It ensures you're working with valid HTML elements, attributes, and styles, helping to minimize potential runtime errors.

Setting Up the Project

Start by initializing a new Go project:

mkdir go-htmx-counter
cd go-htmx-counter
go mod init github.com/yourusername/go-htmx-counter

Next, install the required packages:

go get github.com/chasefleming/elem-go
go get github.com/gofiber/fiber/v2

Setting Up the Go Fiber Server

Create a new file named main.go. Here, set up a root route using Go Fiber, which listens on port 3000 and serves the "Hello, World!" message:

package main

import (
    "github.com/gofiber/fiber/v2"
)

func main() {
    app := fiber.New()

    app.Get("/", func(c *fiber.Ctx) error {
        c.Type("html")
        return c.SendString("Hello, world!")
    })

    app.Listen(":3000")
}

To start your server:

go run main.go

Navigate to http://localhost:3000, and you should be greeted by "Hello, world!".

Importing Subpackages from `elem-go`

Once you have installed the elem-go package, you also gain access to its subpackages, which are designed to enhance your development experience with type-safe utilities for attributes, styles, and htmx integration. Here’s how you can import them into your project:

import (
    //...[existing imports]...
    "github.com/chasefleming/elem-go/attrs"
    "github.com/chasefleming/elem-go/styles"
    "github.com/chasefleming/elem-go/htmx"
)

Make sure to include these imports in your main.go file or any other file where you are using the elem-go library. By importing these subpackages, you gain access to a suite of constants and helper functions that facilitate the creation of type-safe HTML elements. This structure helps prevent common mistakes such as typos in attribute names and ensures that style properties are correctly applied to your elements.

Each subpackage serves a specific purpose:

attrs: This subpackage contains constants for HTML attribute names, ensuring that you use valid attribute keys when creating elements.
styles: It provides constants for CSS property names, allowing you to apply styles with the correct property keys.
htmx: This subpackage includes constants for htmx-specific attributes, making it easier to work with htmx in your templates.

Create the Counter Page using `elem-go`

Begin by adding the script tag for the htmx source to our app's <head>. With elem-go, you can generate this HTML in a type-safe manner. Using elem. followed by the tag name lets you create the desired elements. The first argument in an elem-go element defines its attributes, while subsequent arguments denote child elements:

app.Get("/", func(c *fiber.Ctx) error {
    head := elem.Head(nil, elem.Script(attrs.Props{attrs.Src: "https://unpkg.com/htmx.org@1.9.6"}))
    //...[rest of the code]...
})

With elem-go, you can also utilize type-safe constants for both attribute and style keys. To define the styles, add the following after head:

bodyStyle := styles.Props{  
    styles.BackgroundColor: "#f4f4f4",
    styles.FontFamily:      "Arial, sans-serif",
    styles.Height:          "100vh",
    styles.Display:         "flex",
    styles.FlexDirection:   "column",
    styles.AlignItems:      "center",
    styles.JustifyContent:  "center",
}

buttonStyle := styles.Props{
    styles.Padding:       "10px 20px",
    styles.BackgroundColor: "#007BFF",
    styles.Color:         "#fff",
    styles.BorderColor:   "#007BFF",
    styles.BorderRadius:  "5px",
    styles.Margin:        "10px",
    styles.Cursor:        "pointer",
}

After defining the styles, we'll construct our body elements using the methods provided by the elem-go library. Additionally, the htmx subpackage we imported offers specific values, which are accessible with the htmx. prefix:

body := elem.Body(
    attrs.Props{
        attrs.Style: bodyStyle.ToInline(),
    },
    elem.H1(nil, elem.Text("Counter App")),
    elem.Div(attrs.Props{attrs.ID: "count"}, elem.Text("0")),
    elem.Button(
        attrs.Props{
            htmx.HXPost:   "/increment",
            htmx.HXTarget: "#count",
            attrs.Style:   buttonStyle.ToInline(),
        }, 
        elem.Text("+")
    ),
    elem.Button(
        attrs.Props{
            htmx.HXPost:   "/decrement",
            htmx.HXTarget: "#count",
            attrs.Style:   buttonStyle.ToInline(),
        }, 
        elem.Text("-")
    ),
)

Once the body content is defined, encapsulate it within the <html> tag using the elem.Html method followed by Render. Append this after defining the body:

pageContent := elem.Html(nil, head, body)  

html := pageContent.Render()

Adding Interactivity with htmx

Next, we'll establish handlers for the /increment and /decrement endpoints. These are invoked via htmx.HXPost, the programmatic equivalent of the hx-post attribute in HTML. To do this, integrate the following into your main function after initializing the app:

var count int

app.Post("/increment", func(c *fiber.Ctx) error {
    count++
    return c.SendString(fmt.Sprintf("%d", count))
})

app.Post("/decrement", func(c *fiber.Ctx) error {
    count--
    return c.SendString(fmt.Sprintf("%d", count))
})

The above routes will update and then send back the current value of the counter. Ensure you have imported the fmt package at the top of your file to use the Sprintf function.

Running the Counter App

Run the server, navigate to http://localhost:3000, and you'll be greeted with the Counter App. The "+" and "-" buttons will now seamlessly update the count value without a full page refresh.

Congratulations on successfully building a basic counter app using Go Fiber for the backend, htmx for frontend interactivity, and elem-go for type-safe HTML templating. Expand on this foundation for more advanced projects!

If you'd like to see the full code, check out this repo.

DEV Community: Chase Fleming

Building a Go Static Site Generator Using elem-go and goldmark

Explaining the Dependencies

Creating Our Project

Adding Our Content

Building Our Generator

Styling Our Site

Opening Our Site

Building a Counter App with htmx, Go Fiber, and elem-go

Explaining the Dependencies

Setting Up the Project

Setting Up the Go Fiber Server

Importing Subpackages from elem-go

Create the Counter Page using elem-go

Adding Interactivity with htmx

Running the Counter App

Importing Subpackages from `elem-go`

Create the Counter Page using `elem-go`