builder

README

Builder: Static Site Generation Tool

Builder is a streamlined static site generation tool designed with a focus on convention over configuration. Say goodbye to maintaining endless YAML files and embrace a more straightforward approach to building your website.

Features

• No Configuration Files: Avoid the hassle of managing configuration files.
• Simple Directory Layout: Organize your content easily with a straightforward directory structure.
• Asset Management: Easily manage images, JavaScript, CSS, and other assets.
• Enhanced Markdown Rendering: Builder provides a rich markdown rendering experience:

  • Feeds: Outputs RSS, Atom, and Sitemap feeds based on the content.

    <link
      rel="alternate"
      type="application/rss+xml"
      href="https://example.com/rss.xml"
    />
    <link
      rel="alternate"
      type="application/atom+xml"
      href="https://example.com/atom.xml"
    />
    

  • GitHub Flavored Markdown: Write markdown the GitHub way.

    ```javascript
    function hello() {
      console.log("Hello, GitHub!");
    }
    ```
    

  • Emoji Support: Add a touch of fun with emoji support in your content.

    I love coding! :heart:
    

  • Mermaid Diagrams: Visualize your ideas with Mermaid diagrams.

    ```mermaid
    graph TD;
        A-->B;
        A-->C;
        B-->D;
        C-->D;
    ```
    

  • Syntax Highlighting: Make your code snippets stand out.

    ```python
    def greet():
        print("Hello, World!")
    ```
    

  • Definition Lists, Footnotes, and Typographer: Add rich details to your content.

    Term 1 : Definition 1
    
    Term 2 : Definition 2[^1]
    
    [^1]: This is a footnote.
    

• Templating Power: Harness the power of Go's html/template package:

  • Sprig Functions: Use of sprig

  • Embed Dynamic Content:

    {{.VariableName}}
    

  • Loop Through Lists:

    {{range .List}}
    
    - {{.}} {{end}}
    

• SEO-Friendly URLs: Builder generates SEO-friendly URLs by creating slugs from your markdown file titles. For a markdown file titled "My Awesome Post", Builder might generate a URL like /my-awesome-post.
• Optimized Output: With built-in HTML minification, your site will be optimized for faster load times. No additional configuration is needed; Builder handles this automatically.
• Comprehensive Error Handling: Builder ensures you're always in the know. If there's an issue during the build process, Builder will provide a detailed error message to help you troubleshoot.

Getting Started

Installation

1. Download Builder:

   Using Homebrew:

   brew tap jtarchie/builder https://github.com/jtarchie/builder
   brew install builder
   

2. Install Mermaid CLI (for server-side mermaid rendering):

   npm install -g @mermaid-js/mermaid-cli
   

Setting Up Your Project

1. Directory Structure:

   • layout.html: This is the main template used to render the content of your site.
   • public/: Place all your assets here (images, JavaScript, CSS, etc.). These will be copied to the output directory during the build process.
   • **/*.md: Write your content in markdown files. Organize them in any directory structure you prefer. They will be rendered and placed in the corresponding location in the output directory.

2. Building Your Site:

   builder --source-path <source-directory> --build-path <output-directory>
   

Example Directory Breakdown

To get a clearer idea, check out the example/ directory:

• example: The root directory for the sample project.
• example/markdown.md: A sample markdown file showcasing content creation.
• example/posts: A directory for organizing blog posts or articles.
• example/posts/2023-01-01.md: A sample blog post dated January 1, 2023.
• example/layout.html: The main template file defining the site's structure and appearance.
• example/public: A directory for static assets like images, stylesheets, and scripts.
• example/public/404.html: A custom 404 error page for handling missing pages.

To run the example:

go run cmd/main.go --source-path ./example --build-path build/ --serve

Sites Using Builder

• https://jtarchie.com with source. It uses a custom Github Action to deploy this to Cloudflare Pages.

Documentation

Index

• type CLI
  • func (c *CLI) Run() error
• type Doc
  • func NewDoc(filename string, sourcePath string) (*Doc, error)
  • func (d *Doc) Basename() string
  • func (d *Doc) Contents() string
  • func (d *Doc) Description() string
  • func (d *Doc) Filename() string
  • func (d *Doc) Metadata() *DocMetadata
  • func (d *Doc) Path() string
  • func (d *Doc) RelativePath() string
  • func (d *Doc) SlugPath() string
  • func (d *Doc) Title() string
• type DocMetadata
• type Docs
  • func NewDocs(sourcePath string, pattern string, limit int, filterIndexes bool) (Docs, error)
• type Render
  • func NewRender(layoutPath string, sourcePath string, assetsPath string, buildPath string, ...) *Render
  • func (r *Render) Execute(docsGlob string, feedGlob string) error
• type Watcher
  • func NewWatcher(sourceDir string) *Watcher
  • func (w *Watcher) Execute(watchFn func(string) error) error

Types

type CLI

type CLI struct {
	AssetsPath     string `help:"path to static assets (default with be source-path/public)"`
	BaseURL        string `help:"the URL which the contents will be served from, this is only used for generating feeds"`
	BuildPath      string `` /* 134-byte string literal not displayed */
	FeedGlob       string `help:"glob patterns for documents to feature in feeds"`
	LayoutFilename string `` /* 134-byte string literal not displayed */
	Serve          bool   `help:"serve when done building"`
	SourcePath     string `` /* 134-byte string literal not displayed */
}

func (*CLI) Run

func (c *CLI) Run() error

type Doc

type Doc struct {
	times.Timespec
	// contains filtered or unexported fields
}

func NewDoc

func NewDoc(
	filename string,
	sourcePath string,
) (*Doc, error)

func (*Doc) Basename

func (d *Doc) Basename() string

func (*Doc) Contents

func (d *Doc) Contents() string

func (*Doc) Description

func (d *Doc) Description() string

func (*Doc) Filename

func (d *Doc) Filename() string

func (*Doc) Metadata

func (d *Doc) Metadata() *DocMetadata

func (*Doc) Path

func (d *Doc) Path() string

func (*Doc) RelativePath

func (d *Doc) RelativePath() string

func (*Doc) SlugPath

func (d *Doc) SlugPath() string

func (*Doc) Title

func (d *Doc) Title() string

type DocMetadata

type DocMetadata struct {
	Title       string `yaml:"title"`
	Description string `yaml:"description"`
}

type Docs

type Docs []*Doc

func NewDocs

func NewDocs(
	sourcePath string,
	pattern string,
	limit int,
	filterIndexes bool,
) (Docs, error)

type Render

type Render struct {
	// contains filtered or unexported fields
}

func NewRender

func NewRender(
	layoutPath string,
	sourcePath string,
	assetsPath string,
	buildPath string,
	baseURL string,
) *Render

func (*Render) Execute

func (r *Render) Execute(
	docsGlob string,
	feedGlob string,
) error

type Watcher

type Watcher struct {
	// contains filtered or unexported fields
}

func NewWatcher

func NewWatcher(
	sourceDir string,
) *Watcher

func (*Watcher) Execute

func (w *Watcher) Execute(watchFn func(string) error) error