postwave 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d05bcd73c7411550217ca5ecbeed284b472a25aac71493b401bac88b8c756cab
-  data.tar.gz: 58b7c971cc36fe07783176414d530ec96962d9b921a854d2d1580322fc9fb718
+  metadata.gz: 72de9f3a0519b58b611d16948184ca006efe255192165adb12daa63acc2f4a5b
+  data.tar.gz: 7cda4aa860cd5e1fddd8b627f404c690d8517d0d11b81c1531f145a3e6cf1fac
 SHA512:
-  metadata.gz: 9ea1bcd8a913e043d49b99a3687fd3d97c12a1dbc60d938b3f35ceb3995df7eec1b33801f2f1adcc2295ebde903d5be6d90c21655b4bc23b19f137b7195d6130
-  data.tar.gz: 7b52272bb286fe4ed33490e70ed541a9853e1d8191a5f5397292ecb38e45bbae4dffaa8b20a5828423f81bca88c14468a5ee16ff588833741db6d429d3d8f02d
+  metadata.gz: e78c9dbe00a6e5f69d7a40e45e5aac96c2d9cf86debace476e7b6f89a5060dfb089eaa789def679a660108d62bcf813f33cb7bcaae2b84b761548175042914a0
+  data.tar.gz: 0da1d0e033986bd2c3654a94c5dac1e9bf590bca2105489d1982282289658cbca62424267468ed6345c9925325ef2d743cad841cddb204a9daaf90f2c1b4f640

data/README.md

@@ -4,12 +4,16 @@
 
 Write your posts statically. Interact with them dynamically.
 
+[postwave.blog](https://postwave.blog/)
+
 ## What is Postwave?
 
 Postwave is an opinionated flat-file based based blog engine.
 
 It lets you write posts in Markdown and then display them on a dynamic site using the client functionality.
 
+Read more about the philosophy behind [what Postwave is for](https://postwave.blog/posts/what-is-postwave-for).
+
 ## Installation
 
 ```
@@ -32,6 +36,7 @@ Here is what will be created:
 |- _posts/
 |  |- meta/
 |     |- tags/
+|       |- .tags
 |     |- index.csv
 |     |- summary.yaml
 postwave.yaml
@@ -39,7 +44,7 @@ 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/tags/`: This will contain files for every tag your define in your posts. It contains a `.tags` file to make sure the directory gets picked up by git even if you have no tags.
 
 `_posts/meta/index.csv`: This will contain an ordered list of all the posts
 
@@ -77,6 +82,15 @@ draft: true
 ---
 ```
 
+You can freeze the slug of a post by adding `frozen_slug: post-slug` to the top section of the post.
+```
+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 the Blog
 
 ```
@@ -86,14 +100,14 @@ draft: true
 This will "build" the blog. This involves:
 - regenerating the `/meta/index.csv` file
 - generating slugs for each posts based on the post title and ensuring that there are no duplicate slugs
-- changing the post file names to match `yyyy-dd-mm-slug.md`
+- changing the post file names to match `yyyy-mm-dd-slug.md`
 - updating the `/meta/summary.yaml`
 - creating and updating tag files (which will be `/tags/[tag-name].yaml` files for each tag)
 - updating the `/meta/rss` file to create a feed for your posts
 
 ## Displaying Posts
 
-You can now use Postwave's build in client to display this posts in your project.
+You can use Postwave's built in Ruby client to display these posts in your project.
 
 ### Include the Client In Your Project
 
@@ -131,7 +145,7 @@ puts post.body_preview(8) # an HTML free preview of the post with optional `limi
 
 ### Get a Collection of Posts
 
-This will give you a list of posts for displaying on a page.
+This will give you a list of posts.
 
 You can also filter by tags and specify offsets and limits (useful for pagination).
 
@@ -148,7 +162,7 @@ Posts will be in reverse chronological order.
 
 ### Get an Index of Posts
 
-This will give you a quick list of post summaries containing the title, date, and stub, useful for building an archive page or quick index of posts.
+This will give you a quick list of post summaries containing the title, date, and stub, useful for building a summary page or quick index of posts.
 
 You can also specify offsets and limits (useful for pagination).
 ```ruby
@@ -229,6 +243,10 @@ archive = postwave_client.archive(by: "month")
 # }
 ```
 
+## Example Site
+
+The code for [postwave.blog](https://postwave.blog/) is available at [github.com/dorkrawk/postwave-site](https://github.com/dorkrawk/postwave-site) and serves as a good example of how to use Postwave in a real world project.
+
 ## Run Tests
 
 ```

data/lib/postwave/blog_builder.rb

@@ -7,6 +7,7 @@ require_relative "blog_utilities"
 require_relative "display_helper"
 require_relative "rss_helper"
 require_relative "post"
+require_relative "errors"
 
 module Postwave
   class BlogBuilder
@@ -30,12 +31,13 @@ module Postwave
       # load, rename, and sort post file names
       posts = load_posts
       posts = ensure_unique_slugs(posts).sort_by { |p| p.date }.reverse
-      draft_posts, published_posts = posts.partition { |p| p.respond_to?(:draft) ? p.draft : false }
+      draft_posts, published_posts = posts.partition { |p| p.draft? }
       tags = {}
 
       CSV.open(File.join(Dir.pwd, POSTS_DIR, META_DIR, INDEX_FILE_NAME), "w") do |csv|
         csv << INDEX_HEADERS
         published_posts.each do |post|
+          raise BlogBuilderError, "Post slug cannot be blank." if post.slug.empty?
           post.update_file_name!
 
           csv << [post.slug, post.date, post.title]
@@ -73,12 +75,13 @@ module Postwave
       slug_count = {}
 
       posts.sort_by { |p| p.date }.each do |post|
-        title_slug = post.title_slug
-        if slug_count.key?(title_slug)
-          slug_count[title_slug] += 1
-          post.slug = "#{title_slug}-#{slug_count[title_slug]}"
+        post_slug = post.frozen_slug? ? post.frozen_slug : post.title_slug
+        if slug_count.key?(post_slug)
+          raise BlogBuilderError, "Duplicate frozen slug: #{post_slug}" if post.frozen_slug?
+          slug_count[post_slug] += 1
+          post.slug = "#{post_slug}-#{slug_count[post_slug]}"
         else
-          slug_count[title_slug] = 0
+          slug_count[post_slug] = 0
         end
       end
 

data/lib/postwave/blog_creator.rb

@@ -21,6 +21,7 @@ module Postwave
       build_directories
       build_files
       write_initial_summary_contents
+      write_tag_file_contents
 
       configure_blog
 
@@ -48,6 +49,11 @@ module Postwave
       File.write(File.join(Dir.pwd, POSTS_DIR, META_DIR, SUMMARY_FILE_NAME), summary.transform_keys(&:to_s).to_yaml)
     end
 
+    def write_tag_file_contents
+      # just put something in the file
+      File.write(File.join(Dir.pwd, POSTS_DIR, META_DIR, TAGS_DIR, TAG_FILE_NAME), "[]")
+    end
+
     def configure_blog
       config = {}
 

data/lib/postwave/blog_utilities.rb

@@ -3,6 +3,7 @@ module Postwave
     CONFIG_FILE_NAME = "postwave.yaml"
     INDEX_FILE_NAME = "index.csv"
     SUMMARY_FILE_NAME = "summary.yaml"
+    TAG_FILE_NAME = ".tags"
     RSS_FILE_NAME = "rss"
     POSTS_DIR = "_posts"
     META_DIR = "meta"
@@ -18,6 +19,7 @@ module Postwave
         File.join(blog_root, CONFIG_FILE_NAME),
         File.join(blog_root, POSTS_DIR, META_DIR, INDEX_FILE_NAME),
         File.join(blog_root, POSTS_DIR, META_DIR, SUMMARY_FILE_NAME),
+        File.join(blog_root, POSTS_DIR, META_DIR, TAGS_DIR, TAG_FILE_NAME),
       ]
     end
 

data/lib/postwave/client.rb

@@ -18,7 +18,11 @@ module Postwave
       raise MissingConfigError unless is_valid_config?(config_path)
       
       @blog_root = File.dirname(config_path)
-      raise InvalidBlogError unless is_set_up?(@blog_root)
+      missing_paths = find_missing_paths(@blog_root)
+      unless missing_paths.empty?
+        missing_paths_message = "Your blog is missing the following files/directories: #{missing_paths.join(',')}"
+        raise InvalidBlogError, missing_paths_message
+      end
 
       @all_posts = get_all_posts if preload
     end

data/lib/postwave/errors.rb

@@ -13,4 +13,7 @@ module Postwave
 
   class TagNotFoundError < PostwaveError
   end
+
+  class BlogBuilderError < PostwaveError
+  end
 end

data/lib/postwave/post.rb

@@ -68,7 +68,21 @@ module Postwave
         self.class.send(:attr_reader, field) unless self.public_methods.include?(field.to_sym)
       end
 
-      @slug = file_name_slug&.empty? ? title_slug : file_name_slug
+      @slug = if frozen_slug?
+                frozen_slug
+              elsif file_name_slug&.empty?
+                title_slug
+              else
+                file_name_slug
+              end
+    end
+
+    def draft?
+      respond_to?(:draft) && draft
+    end
+
+    def frozen_slug?
+      respond_to?(:frozen_slug) && !!frozen_slug
     end
 
     def title_slug

data/lib/postwave/rss_helper.rb

@@ -15,16 +15,17 @@ module Postwave
     end
     
     def feed_content(posts)
-      link = config_values[:url]
+      link = config_values[:url].chomp("/")
       updated = Time.now.iso8601.to_s
       title = config_values[:name]
       description = config_values[:description]
 
       markdown = Redcarpet::Markdown.new(Redcarpet::Render::HTML, fenced_code_blocks: true)
       feed_posts = posts.map do |post|
-        post_link = "#{config_values[:url]}/#{config_values[:posts_path]}/#{post.slug}"
+        post_link = "#{link}/#{config_values[:posts_path]}/#{post.slug}"
         html_body = CGI.unescapeHTML(markdown.render(post.body))
-        FeedPost.new(post.title, post_link, html_body, post.date.iso8601, post.tags)
+        post_title = CGI.escapeHTML(post.title)
+        FeedPost.new(post_title, post_link, html_body, post.date.iso8601, post.tags)
       end
 
       path = File.join(__dir__, "templates/feed.erb")

data/lib/postwave/version.rb

@@ -1,3 +1,3 @@
 module Postwave
-  VERSION = "0.1.3"
+  VERSION = "0.1.5"
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: postwave
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 platform: ruby
 authors:
 - Dave Schwantes
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-01-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redcarpet
@@ -138,6 +139,7 @@ homepage: https://github.com/dorkrawk/postwave
 licenses:
 - MIT
 metadata: {}
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -152,7 +154,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.1
+rubygems_version: 3.4.10
+signing_key:
 specification_version: 4
 summary: An opinionated flatfile based blog engine.
 test_files: []