gemoire-0.1.0: README.md

# gemoire - yet another static gemlog generator

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,
- and generate Atom and Gemini feeds.

See the [example](https://codeberg.org/sena/gemoire/src/branch/main/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:

```hs
#!/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:

```bash
$ cabal run gemlog.hs
```

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

```bash
$ 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:

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

-- gemoire uses Data.Text underhood.
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`](https://hackage.haskell.org/package/gemoire/docs/Gemoire-Template.html).
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`](https://hackage.haskell.org/package/gemoire/docs/Gemoire-Gemlog.html).

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

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

## See also

- [Project Gemini](https://geminiprotocol.net)
  for more about the Gemini protocol itself.
- [Awesome Gemini](https://github.com/kr1sp1n/awesome-gemini)
  to discover more projects about Gemini.