Skip to content

how_to_post_to_the_blog.md

Latest commit

 

History

History
77 lines (52 loc) · 3.57 KB

how_to_post_to_the_blog.md

File metadata and controls

77 lines (52 loc) · 3.57 KB
Raw

How to post to the blog

DLD development group has a website hosted on GitHub, https://caltechlibrary.github.io. It contains links to Git based projects and documentation. It also hosts a simple blog built on FlatLake, flatlakeTools and a web component called <ul-flatlake-posts>. The web component will read the JSON API generated by FlatLake and render a list of recent posts.

The home page of the website is defined by the GitHub site's README.md, see https://github.com/caltechlibrary/caltechlibrary.github.io/blob/main/README.md. The blog's index of posts is held in blog.md which is created/updated by the flatlakeTools' comand line program called flt. The individual blog posts are stored in the posts directory which contains a standard blog layout (/YYYY/MM/DD/). The post needs to be valid CommonMark including some front matter.

The front matter schema.

title : (expected) Title of the post

abstract : (expected) Short description of the post

author : (optional) Author is email address with name in side parens, example jane.doe@example.edu (Jane Does). Why this format? Because RSS expects an author to be made up of an email address and name in parens.

datePublished : (expected) This is the date when you first post the blog item. It should be in YYYY-MM-DD format.

dateCreated : (good to have) The date you created the blog post

dateModified : (good to have) This is the date when you last modified the post.

keywords : (optional) A list of keywords

Here's a hello world post example

---
title: Hello World
abstract: This is a hello world post
datePublished: 2025-08-04
author: jane@doe (Jane Doe)
---

Hello World!

There are additional fields that my prove help

Requirements

Adding a blog post

  1. Checkout git@github.com:caltechlibrary/caltechlibrary.github.io if you haven't already.
  2. Change into the the caltechlibrary.github.io directory
  3. In this directory you'll see a "posts" sub directory, this is where the blog lives
  4. Create a path under "posts" formed by year, two digit month and two digit day, "posts/2025/08/04"
  5. Write and put your CommonMark blog post in that directory
  6. Double check the front matter for the required fields
  7. Run make to update your local copy of the website
  8. Using a local webserver view the website and make sure everthing works

When you are ready you can then do make save to update the website. If you need to update the project index run make publish.

How it works

The website content is presumed to be CommonMark (Markdown) documents. FlatLake is used to generate a JSON API. The flatlakeTools' flt program understands the FlatLake JSON API and can render the RSS file for the blog as well as the blog.md file.

Pandoc is being used to turn the CommonMark documents into HTML. It does this by applying the template named "page.tmpl".

Once the HTML is produced then PageFind is used to generated search indexes for the website and blog. The search page can use those indexes as well as ones in select GitHub project sites to provide search support.

The Makefile orchestrates everything base on a set of rules.