jorge/README.md

jorge

A personal (small + opinionated) site generator with org-mode (and markdown) support.

Installation

Download the latest release binary for your platform, for example:

$ wget https://github.com/facundoolano/jorge/releases/latest/download/jorge-darwin-amd64  \
    -O jorge && chmod +x jorge && mv jorge /usr/local/bin

Alternatively, install with go:

$ go install github.com/facundoolano/jorge@latest

Example usage

Create a new website with jorge init:

$ jorge init myblog
site name: My Blog
site url: https://myblog.olano.dev
author: Facundo Olano
added myblog/.gitignore
added myblog/includes/post_preview.html
added myblog/layouts/base.html
added myblog/layouts/default.html
added myblog/layouts/post.html
added myblog/src/assets/css/main.css
added myblog/src/blog/goodbye-markdown.md
added myblog/src/blog/hello-org.org
added myblog/src/blog/index.html
added myblog/src/blog/tags.html
added myblog/src/feed.xml
added myblog/src/index.html

This initializes a new project with default configuration, styles and layouts, and a couple of sample posts. (You can, of course, use a different site structure or just skip the init command altogether).

To preview your site locally, use jorge serve:

$ cd myblog
$ jorge serve
wrote target/feed.xml
wrote target/blog/goodbye-markdown.html
wrote target/blog/my-first-post.html
wrote target/blog/hello-org.html
wrote target/blog/index.html
wrote target/index.html
wrote target/blog/tags.html
serving at http://localhost:4001

The site is renders the files found at src/ in the target/ directory. You can add new pages by just adding files to src/ but, for the common case of adding blog posts, the jorge post creates files with the proper defaults:

$ jorge post "My First Post"
added src/blog/my-first-post.org
$ cat src/blog/my-first-post.org
---
title: My First Post
date: 2024-02-21 13:39:59
layout: post
lang: en
tags: []
---
#+OPTIONS: toc:nil num:nil
#+LANGUAGE: en

(Posts are created as .org files by default, but you can chage it to prefer markdown or another text format).

If you still have jorge serve running, you can see the new post by browsing to http://localhost:4001/blog/my-first-post. You can then add some content and the browser tab will automatically refresh to reflect your changes:

$ cat >> src/blog/my-first-post.org <<EOF
*** Hello world!

this is my *first* post.
EOF

Finally, you can render a minified version of your site with jorge build:

$ jorge build
  wrote target/index.html
  wrote target/assets/css/main.css
  wrote target/blog/hello.html
  wrote target/blog/my-first-post.html
  wrote target/feed.xml
  wrote target/tags.html

And that's about it. For more details see the:

• Tutorial
• Docs
• Development blog

Acknowledgements

jorge started as a Go learning project and was largely inspired by Jekyll. Most of the heavy lifting is done by external libraries:

• osteele/liquid to render liquid templates. Some Jekyll-specific filters were copied from osteele/gojekyll.
• niklasfasching/go-org to render org-mode files as HTML.
• yuin/goldmark to render Markdown as HTML.
• go-yaml to parse YAML files and template headers.
• tdewolff/minify to minify HTML, CSS, XML and JavaScript files.