gemoire - yet another static gemlog generator + converter

gemoire is just a basic flexible gemini blog generator, that can:

• be configured using Haskell code,
• use custom templates written in an authentic syntax,
• set additional and overriding variables for formatting,
• generate Atom and Gemini feeds.
• and convert capsules to various formats, such as HTML and Markdown by default.

See the example directory in the repository to see how it looks like in "production".

Getting Started

Intended way for using gemoire is through Cabal scripts. To get started, you should organize your gemlog sources like so:

gemlog
├── content
│   ├── post1.gmi
│   └── post2.gmi
└── gemlog.hs

The contents directory can be as deep as you want, all posts will end up in a flat directory in the end. After setting up your files, you can start configuring your gemlog.hs, here is a simple template for you using the defaults:

#!/usr/bin/env cabal
{- cabal:
build-depends: base
             , gemoire
-}
{-# LANGUAGE OverloadedStrings #-}

import Gemoire

main :: IO ()
main = do
    let gemlog =
            Gemlog
                { title = "my gemlog"
                , author = "me"
                , sourceDir = "content"
                , baseURL = "gemini://my.website.com/path/to/gemlog"
                , postTemplate = defPost
                , gemfeedTemplates =
                      ( defGemfeed
                      , defGemfeedEntry
                      )
                , atomTemplates =
                      ( defAtom
                      , defAtomEntry
                      )
                , overrides = vempty
                }

    generatePosts gemlog "~/public_gemini/path/to/gemlog"
    generateGemfeed gemlog "~/public_gemini/path/to/gemlog/index.gmi"
    generateAtom gemlog "~/public_gemini/path/to/gemlog/atom.xml"

After setting up your configuration, you can just cd into the gemlog directory and run the generator:

$ cabal run gemlog.hs

If Cabal is causing problems, you can just install the library and use runghc instead, like so:

$ cabal install --lib gemoire
$ runghc gemlog.hs

Customizing

You can then customize your gemlog to your liking. To do that, you might want to start with changing the templates, like so:

#!/usr/bin/env cabal
{- cabal:
build-depends: base
             , text
             , gemoire
-}
{-# LANGUAGE OverloadedStrings #-}

-- gemoire uses Data.Text under the hood.
import Data.Text (unlines)
import Prelude hiding (unlines)
import Gemoire

-- The line endings will be taken care of by gemoire.
-- ...
                , postTemplate = template . unlines $
                      [ "By {$author$}."
                      , ""
                      , "{$post$}"
                      ]
-- ...

There are various variables and different useful compounds you can use in the templates. A detailed list can be found in the documentation of Gemoire.Template. Also check the default templates in the source for some inspiration!

Different special variables are available to the formatters for feeds and posts. You can see a list of those and how you can set overrides per post in the page for Gemoire.Gemlog.

Additionally, you can set overriding variables globally using the overrides variable, like so:

-- ...
                , overrides = vlist
                      [ ("variable", "new value")
                      , ("another", "overridden")
                      ]
-- ...

Converting

After generating a Gemini capsule, you might want to convert your art into different formats, e.g. to publish on the web as well. To do so, you can use something like the following:

#!/usr/bin/env cabal
{- cabal:
build-depends: base
             , gemoire
-}

import Gemoire

main :: IO ()
main = do
    let web = defWebConversion

    convertCapsule web "~/public_gemini" "~/public_html"

You can also somewhat customize this behaviour, like so:

#!/usr/bin/env cabal
{- cabal:
build-depends: base
             , gemoire
-}
{-# LANGUAGE OverloadedStrings #-}

import Gemoire

main :: IO ()
main = do
    let web = defWebConversion
                  { textTemplate = template "<p class=\"something\">{$text$}</p>"
                  , rewriteRules =
                        [ -- Rewrite .gmi links in the domain example.com as .html.
                          ( ".*\\.gmi" -- input files in which the rewriting will occur
                          , "((https*)|(gemini))://example.com/(.*)\\.gmi" -- the RegEx to match
                          , "https://example.com/\\4.html" -- the replacement text
                          , True -- multiline
                          , True -- case senstive
                          )
                        ]
                  , conversionOverrides = vlist [("title", "every title is this now")]
                  }

    convertCapsule web "~/public_gemini" "~/public_html"

You can also define your own conversion rules using the Conversion struct. See the documentation of Gemoire.Converter for more on what else you can do and the template variables.

See also

• Project Gemini for more about the Gemini protocol itself.
• Awesome Gemini to discover more projects about Gemini.