jorge post

Add a blog post

Posts and pages

When jorge builds a website out of the contents of your src/ directory, it distinguishes between 3 types of files:

  1. Static files: any file that’s not a template. These are files that don’t contain a front matter header (that don’t start with a --- line).

  2. Template files, which can be further divided into:

    1. Posts: templates that include a date field in their front matter, and thus can be sorted chronologically.
    2. Pages: any other template file.

As you can see, the difference between posts and pages is subtle. Posts receive special treatment so their chronological nature can be used for things like building a blog archive page or publishing the most recent posts to RSS feeds1. In practical terms, this difference only affects how posts and pages are exposed as template variables:

  1. Pages are listed without a particular order in the site.pages variable2.
  2. Posts are listed in reverse chronological order (most recent first) in the site.posts variable.
  3. If they that declare tags in their front matter, posts are additionally included in the site.tags map.
  4. Posts expose an excerpt property with a summary of their contents. If excerpt is defined as a key in the post front matter, its value will be used; if not, the first paragraph of the post content will be used instead. Excerpts are useful for previewing posts in the blog archive, in social media links, and in RSS feeds.

jorge post

Each website has its own layout so it’s hard to predict what you may need to do with a page template. But blogs are different: once the site layout is in place, you more or less repeat the same steps every time you write a new post. For this reason, jorge provides the jorge post command to initialize blog post template files.

Let’s try it out:

$ jorge post "My own blog post"
added src/blog/my-own-blog-post.org

If you open this new file in your editor, you should see something like this:

---
title: My own blog post
date: 2024-02-23 11:45:30
layout: post
lang: en
tags: []
draft: true
---
#+OPTIONS: toc:nil num:nil
#+LANGUAGE: en

Let’s look at what the command did for us:

src/blog/my-own-blog-post.org The filename, a URL-friendly version of the post title (a “slug”), such that the post will be served at /blog/my-own-blog-post
title: My own blog post The title we passed to jorge. This will be available to templates as {{page.title}} and will be used by the default post layout to render the header of the page.
date: 2024-02-23 11:45:30 The date this post was created. It will affect the position it shows up in in {{site.posts}}
layout: post The rendered HTML of this template will be embedded as the {{contents}} of the layout defined in layouts/post.html.
lang: en The language code for the post. This is used by some of the default templates, for instance, to determine how to hyphenate the post content.
tags: [] The post tags, initially empty. The keywords in this list will determine which keys of the {{site.tags}} map this post will be associated with.
draft: true By default, posts created with jorge post are marked as drafts. Drafts are included in the site served locally but excluded from the production build. Remove this flag once your post is ready.
#+OPTIONS: toc:nil num:nil, #+LANGUAGE: en Some default org mode options, to skip the table of contents and define the post language.

With jorge serve running, you can start filling in some content on this new post and see it show up in the browser at http://localhost:4001/blog/my-own-blog-post.

Customizing the post format

As you may have noticed, the jorge post command makes a lot of assumptions about the post: where to put it, how to name it, and what format to use. You can control some of these decisions by redefining the post_format configuration key. The default is:

post_format: "blog/:title.org"

Let’s say that you want to put posts in the root folder, use the date as part of the url, and use markdown instead of org syntax. In that case you’d add this to your config.yml:

post_format: ":year-:month-:day-:title.md"

Thus, next time you add a post:

$ jorge post "Another kind of post"
added src/2024-02-23-another-kind-of-post.md

Notes

1

Both a blog archive and the RSS feed (technically Atom) are already implemented in the default site generated by jorge init.

2

index.html pages are excluded from this list.



powered by jorge | source