frozen_slug feature.
When you run postwave build your post filenames (which control the post slugs) get updated based on the title. If you would like to use a slug that is not related to the post title you can now include a frozen_slug: use-this-slug field in the post header.
For example:
title: A New Title!
date: 2022-01-01
tags:
frozen_slug: keep-this-slug
The filename will remain 2022-01-01-keep-this-slug.md after running postwave build (rather than updating to 2022-01-01-a-new-title.md). Note that the date part of the filename still comes from the date field.
build process if the post title is blank..tags file is created in new blogs in the /_posts/meta/tags directory so that this directory is picked up by Git even when you don't have any tags. If this is causing an issue in existing blogs, just add an empty .tags file to that directory.This blog was just upgraded to use version 0.1.5 and you can too!
]]>postwave build will handle this just fine. It will rename your files yyyy-mm-dd-title.md and yyyy-mm-dd-title-1.md.
What happens if I use non alphanumeric characters in my post title?
Can Postwave generate an RSS feed?
It sure can!
Will updating the post title update the slug (and path) for the post?
Yep, so be careful if you're worried about an update breaking links to an old post.
If you want to freeze the slug you can use the frozen_slug: slug-you-want field in the post header.
Will updating the post date update the slug (and path) for the post?
Nope, but it will update the Markdown file name.
Why the name "Postwave"?
I'm a big fan of the Blue Meanies.
Seriously, another blog engine? WHY?!
Honestly, it scratches an itch I have. I wanted to write posts in a specific way and then build them into my site, rather than have my site be bolted on to a pre-built blog. After years of hacking together similar solutions with things like Wordpress and Jekyll I just built what I wanted. Maybe other people will find it useful, too!
So who built this?
Dave.
]]>Start By Including the Client In Your Project
require 'postwave/client'
Then Create a Postwave Client
postwave_client = Postwave::Client.new("path/to/config/postwave.yaml")
If you'd like to preload all the posts:
postwave_client = Postwave::Client.new("path/to/config/postwave.yaml", preload: true)
You Can Get a Single Post
Pass in the stub (the filename without the date and '.md') for the post.
post = postwave_client.post("my-great-post")
# , tags=["tag1"], body="bla bla bla">
puts post.title
# "My Great Post"
puts post.body
# "bla bla bla"
puts post.body_html # uses Redcarpt to convert body Markdown to HTML
# "bla bla bla
"
puts post.body_preview(8) # an HTML free preview of the post with optional `limit` and `ellipsis` params
# "bla bla..."
Or Get a Collection of Posts
This will give you a list of posts for displaying on a page.
You can also filter by tags and specify offsets and limits (useful for pagination).
posts = postwave_client.posts
# [, , ...]
tagged_posts = postwave_client.posts(tag: "lizards")
page2_posts = postwave_client.posts(offset: 10, limit: 10)
Posts will be in reverse chronological order.
Or Lots of Other Things!
Check out the documentation to learn about all the ways to use the Postwave client and check out the code for this site to see how a full working blog is implemented with Postwave.
]]>Step 1: Run postwave post
> postwave post
Run this command in your terminal (from within your Postwave project's directory).
This will generate at new Markdown file in the _posts/ directory. The title is set to a random string of characters. The filename will be the current timestamp. This will eventually be overwritten by the build command, so don't worry too much about it. The file will have a general structure like this:
title: FNJEXWZP
date: 2025-01-01
tags:
Start writing!
Tags should be comma separated(tag1, tag2, multiword tags work, tag3).
You can keep a post in "draft" status (meaning it won't get processed or added to the index) by adding draft: true to the top section of the post.
title: This Post Isn't Quite Ready
date: 2025-01-01
tags:
draft: true
Step 2: Write your post!
Now for the good part! You can actually write your post!
Just leave the post metadata information alone and get to work on your brilliant prose.
Step 3: Build the Blog
> postwave build
This will "build" the blog. Do this after you've finished writing and you're ready to publish. This involves:
/meta/index.csv fileyyyy-dd-mm-slug.md/meta/summary.yaml/tags/[tag-name].yaml files for each tag)/meta/rss file to create a feed for your postsNow you're ready to display your posts.
]]>Step 1: Install the gem
> gem install postwave
Step 2: Run postwave new
> postwave new
Run this from the root directory of your project. As a part of this set up you will be asked for a few things:
- name: the name of the blog
- url: the base url of the site (e.g. `https://yoursite.com` )
- posts path: the subdirectory on the site that your posts will be in (e.g. `posts` on this site )
- description: a description of the blog
One of the main areas this information will be used in is RSS feed generation.
When completed this command will create a postwave.yaml config file in the current directory and a /_posts/ directory. This is where you will write your posts.
Here is the directory structure that will be created:
|- _posts/
| |- meta/
| |- tags/
| |- index.csv
| |- summary.yaml
postwave.yaml
_posts/: This is where you write all your posts in Markdown
_posts/meta/tags/: This will contain files for every tag your define in your posts
_posts/meta/index.csv: This will contain an ordered list of all the posts
_posts/meta/summary.yaml: This file will contain some summary information about the posts. Total count, etc.
postwave.yaml: The config file for Postwave.
Step 3: Update Your Configs
If you don't have the information at the time of set up or need to change anything you can always update the postwave.yaml file.
Great! Now you're ready to start writing posts!
]]>And post things to that site...
And write those posts in Markdown.
Postwave is great if you want your posts to fit seamlessly into a site you're building, rather than try to customize or theme a blog to turn into your site.
Authoring in Postwave centers around your terminal and your text editor. New posts are started with a postwave post command, which creates a new Markdown file for you to start writing. Because posts are written as Markdown files, so there's no need for a database.
After writing your posts in Markdown you can then display them however you'd like on your site through the built in Postwave Ruby client. This is where Postwave differs from static blog engines like Jekyll or Hugo which take the Markdown posts and generate a site for you.
With Postwave, once you've written your posts, it's up to you how you'd like to incorporate them into your site. For example, a page to display a post might look like this:
<%= @post.title %>
<%= @post.body_html %>
Postwave is for writing posts for YOUR site.
]]>Postwave is a flat file based blogging system that lets you write posts staticly and display them dynamically.
This blog is meant to serve as an example implementation to help you understand how to work with Postwave. Check out the code for this site on GitHub and feel free to use it as the basis for your own sites.
To learn more check out the Postwave repo
If you want to just start using it, it's available on Rubygems.
]]>