genster generates a static family history website from a GEDCOM or Gramps database. It uses a two-step pipeline: gen writes markdown content files, then build renders them into a complete HTML site ready to serve or rsync to a server.

I created it for myself so it makes many assumptions about my particular style of using GEDCOM, especially around Ancestry exports.

As of Go 1.19, install the latest genster executable using:

go install github.com/iand/genster@latest

This will download and build a binary in $GOBIN.

genster gen   --gedcom family.ged --config mytree.kdl --output content/
genster build --content content/ --pub pub/
npx serve pub/           # or: rsync pub/ user@host:/var/www/html/

Step 1 — gen reads the genealogy data and writes markdown files with YAML front matter into the content directory. These files represent every person, place, source, family, citation, list page, and chart in the tree. Manual content (the research diary, stories, a home page) lives alongside generated files in the same content directory.

Step 2 — build walks the content directory, parses each markdown file, renders the body through goldmark, applies an HTML template based on the layout front-matter field, and writes complete HTML pages to the pub directory. Non-markdown files (images, media) are copied verbatim.

The pub directory is self-contained and can be deployed directly with rsync, scp, or any static hosting service.

Reads a GEDCOM or Gramps file and writes markdown content files to a directory. Exactly one of --gedcom or --gramps must be supplied.

When the MAPTILER_API_KEY environment variable is set and a place has coordinates, gen downloads a static map image and embeds it inline on the place page. Maps are sourced from MapTiler Cloud, which hosts the National Library of Scotland historic map layers as well as OpenStreetMap raster tiles.

The map layer and zoom level are chosen automatically based on place type:

Each place map includes a downward-pointing arrow marking the place's coordinates and a figcaption with a link to the interactive map viewer (NLS Geo/Explore for historic layers, OpenStreetMap for the OSM fallback).

Tile cache — individual map tiles are cached in $XDG_CACHE_HOME/genster/maptiles/ (defaulting to ~/.cache/genster/maptiles/ when XDG_CACHE_HOME is not set), organised as {layer}/{z}/{x}/{y}.jpg. Cached tiles are reused on subsequent runs.

Image cache — stitched 800×600 JPEG map images are cached in $XDG_CACHE_HOME/genster/maps/ as place-map-{id}.jpg. If the cached image exists it is copied directly to the output media directory without re-downloading any tiles. Delete a cached image to force it to be regenerated.

Walks a content directory and renders every markdown file into a complete HTML page.

Produces an SVG family tree chart directly from a GEDCOM or Gramps file without generating a full site. Chart types: descendant, ancestor, butterfly, fan, focus.

Outputs a plain-text descendant or familyline report to stdout.

Walks a directory of hand-authored markdown files and replaces bare footnote references ([^label]) with fully-rendered citation links drawn from the genealogy database. Pass --undo to strip the generated citations and restore original syntax.

All commands that load genealogy data accept --config/-c pointing to a KDL 1.0 file. The file has three top-level nodes: tree, surname-groups, and annotations.

tree id="weston" {
    name "The Weston and Pryor Family Tree"
    description r#"
        The Westons were a farming family from rural Shropshire, England, working
        the same land from the mid-17th century until the agricultural depression
        of the 1870s drove the younger sons into the Midlands coalfields.

        The Pryors came from South Wales and moved to Birmingham in the 1890s,
        where Thomas Pryor met and married Alice Weston in 1903.
        "#
}

id may also be written as a property on the tree node: tree id="weston" { ... }.

Groups spelling variants under a single canonical surname for surname list pages and relationship display.

surname-groups {
    Weston "Wheston" "Westen"
    Pryor "Prior" "Pryer" "Priar"
    Griffiths "Griffith" "Gryffith"
    Hughes "Hughs" "Hewes"
}

Each child node names the canonical surname; its arguments are the variants that should be merged into that group.

Overrides and supplements data from the source GEDCOM or Gramps file. Organised into people, places, and sources sections.

annotations {
    people {
        person id="A3KMNP2XWQR8T" {
            // Thomas Weston (1847-1921)
            nickname "Tom"
            olb "Agricultural labourer turned coal miner from Shropshire."
            wikitreeid "Weston-4521"
        }
        person id="B7YQZR4VNDX2L" {
            // Alice Pryor (1882-1954)
            preferredgivenname "Alice"
            preferredfamilyname "Weston"
        }
        person id="C9WLFT6HJMS3K" {
            // Living relative
            redacted true
        }
        person id="D2PXNK8GRVC5M" {
            // William Griffiths (1801-1879)
            tags "Direct Ancestor" "Shropshire"
        }
    }

    places {
        place id="E5QRTB9YNWJ7H" {
            // Shifnal, Shropshire — missing coordinates
            latlong "52.669, -2.368"
        }
        place id="F1MVZK3DCXP4G" {
            // Historical variant name
            name "Brewood, Staffordshire, England"
        }
    }

    sources {
        source id="G8HNWQ2YBXR6T" { iscivilregistration }
        source id="H4KCJP7FMVZ3L" { iscivilregistration }
        source id="J6TRWB5SDXN9Q" { iscensus }
        source id="K2LQMF8PVYC4H" { iscensus }
        source id="M9ZXDN3JWKR7B" {
            title "Shropshire Parish Records 1600–1900"
            repositoryname "Shropshire Archives"
        }
    }
}

All fields use replace semantics (overwrite the loaded value) except tags, which appends.

The content directory holds both generated and hand-authored files. gen writes into trees/<tree-id>/; manual content sits at the top level alongside it.

content/
├── index.md                          # site home page  (layout: home)
├── images/                           # generic feature images — see below
├── diary/                            # hand-authored research diary
│   ├── index.md                      # diary home      (layout: diary)
│   └── 2024/
│       ├── index.md                  # year index      (layout: diary)
│       └── 2024-03-15/
│           └── index.md              # daily entry     (layout: single)
├── stories/                          # hand-authored narrative articles
│   ├── index.md
│   └── my-story/
│       └── index.md                  #                 (layout: single)
└── trees/
    └── <tree-id>/                    # one subtree per --id value
        ├── index.md                  # tree overview   (layout: treeoverview)
        ├── person/<id>/index.md      #                 (layout: person)
        ├── place/<id>/index.md       #                 (layout: place)
        ├── source/<id>/index.md      #                 (layout: source)
        ├── citation/<id>/index.md    #                 (layout: citation)
        ├── family/<id>/index.md      #                 (layout: family)
        ├── chart/<id>/index.md       #                 (layout: chartancestors)
        └── list/
            ├── people/               #                 (layout: listpeople)
            ├── surnames/             #                 (layout: listsurnames)
            ├── places/               #                 (layout: listplaces)
            ├── sources/              #                 (layout: listsources)
            ├── todo/                 #                 (layout: listtodo)
            ├── changes/              #                 (layout: listchanges)
            ├── anomalies/            #                 (layout: listanomalies)
            ├── inferences/           #                 (layout: listinferences)
            ├── families/             #                 (layout: listfamilies)
            └── familylines/          #                 (layout: listfamilylines)

The build command also generates /tags/ pages automatically from front-matter tags — do not create these manually.

build looks for generic images in content/images/. These are never embedded in the binary, so you can supply your own. The expected filename conventions are:

For person pages, build tries the five person patterns from most to least specific and uses the first file it finds. If nothing matches, no image is rendered.

Person-specific photos (actual photographs from Gramps) are set via the image: front-matter field by gen and take priority over all generic images.

Every content file begins with a YAML front-matter block delimited by ---. gen sets these automatically on generated pages; hand-authored files may set any field explicitly.

The build command uses Go's html/template package. All templates live in genster/build/templates/ and are embedded into the binary at compile time.

Every template receives a PageData value as its dot (.):

type PageData struct {
    FrontMatter        // all front-matter fields promoted onto dot
    Body  template.HTML // rendered HTML from the markdown body
    Tree  TreeData      // tree-level metadata
}

type TreeData struct {
    Title    string // title of the tree's index page
    BasePath string // base URL path (e.g. /trees/mytree/)
}

Because FrontMatter is embedded, all front-matter fields are accessible directly — for example {{.Title}}, {{.Category}}, {{.Gender}}. The embedded struct itself is also accessible as {{.FrontMatter}} when you need to pass it to a template function.

The layout front-matter field selects the template. gen sets this on all generated pages; hand-authored files must set it explicitly (or leave it blank for a plain content page with no sidebar).

Layout templates compose these named blocks via {{template "name" .}}:

Override the embedded templates by passing --assets <dir> to build, where <dir> contains a templates/ subdirectory with replacement .html files. Only the files you provide are replaced; all others use the built-in versions.

To add new template functions, add them to buildSiteTemplates in genster/build/template.go and reference them from a template file.

Genster understands several Ancestry-specific GEDCOM extensions:

• _APID — Ancestry source citation identifier, translated to an Ancestry URL
• _TREE — Ancestry tree reference in the GEDCOM header

Custom EVEN fact labels with specific handling:

• Nickname — preferred nickname for the person
• OLB — one-line biography: a short sentence summarising the person's life

Events whose values begin with certain phrases are included verbatim in the generated narrative:

• He was recorded as
• She was recorded as
• It was recorded that

This is free and unencumbered software released into the public domain. For more information, see http://unlicense.org/ or the accompanying UNLICENSE file.