sakusei 0.2.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1912283c38c05cc3a9f23d05a0ac73eca6846943ee32af42952478e6db89a04
-  data.tar.gz: 7d96c876d140e466e81e7aa6a34f4cb8f0a113da11b70ee454edd755469944ae
+  metadata.gz: 51994014be2b8900d793d1954389a52a2726b54703cd60673886f7b85cfbeaa2
+  data.tar.gz: d650c71e17c76b74f770dd32cc83b45848cacd0b1f7a8f49c3d4eb98185fee50
 SHA512:
-  metadata.gz: 015ce01c509c0b73107501e9a0ab8c0167b032ad3b51712b1c3f511c79dc7687ace68f0f4871972f7efd691642d8a7e72d99114c65f5abe74a97ed9b56bcc873
-  data.tar.gz: 574528be0428bfd65b7d6bf473febc0c202c26c6677d3e6a33bdd9cc582394537e7bca141a956e2824d30a1f40231ce2f4f54ab165ddf6b108bb84d80ba1ec9a
+  metadata.gz: 0c8a398207d15178355e2da253dd4e3d20e9e524a044125214e7c074f264892a5ae9749b2773cf42c4de353532d731a8798d52eb922da38f6d0e5e5185940f8c
+  data.tar.gz: 0b8970fdb542f9fe5f2b81bda13019be3893501735c62962f7a66e60c2acc8f38672ccf74fc4df08ece6b149796d84da52a4207b1ccde31793d079856c426ce7

data/.gitignore

@@ -1,5 +1,6 @@
 *.gem
 .DS_Store
 *.pdf
+!examples/*.pdf
 node_modules/
 .worktrees/

data/README.md

@@ -1,14 +1,5 @@
 # Sakusei
 
-**Sakusei** (作成) — from the Japanese words meaning "creation," "making," or "craft."
-
-Like a master artisan refining their craft, Sakusei transforms raw Markdown into beautifully crafted PDF documents. Every document is an act of creation — structured, styled, and brought to life with precision.
-
-The name embodies the philosophy behind this tool: documents aren't just generated, they're _crafted_.
-
-
-## Overview
-
 Sakusei is a build system for creating PDF documents from Markdown source files. It supports:
 
 - **Markdown to PDF conversion** via `md-to-pdf`
@@ -17,16 +8,16 @@ Sakusei is a build system for creating PDF documents from Markdown source files.
 - **File inclusion** for multi-file documents
 - **PDF concatenation** for combining multiple documents
 
+---
 
-## Installation
+**Sakusei** (作成) — from the Japanese words meaning "creation," "making," or "craft."
 
-### macOS (Homebrew)
+Like a master artisan refining their craft, Sakusei transforms raw Markdown into beautifully crafted PDF documents. Every document is an act of creation — structured, styled, and brought to life with precision.
+
+The name embodies the philosophy behind this tool: documents aren't just generated, they're _crafted_.
 
-```bash
-# Add the tap and install
-brew tap keithrowell/sakusei https://github.com/keithrowell/sakusei/homebrew-tap
-brew install sakusei
-```
+
+## Installation
 
 ### Ruby Gem
 
@@ -86,6 +77,142 @@ sakusei init my_company
 sakusei concat part1.pdf part2.pdf -o combined.pdf
 ```
 
+## Examples
+
+### Basic usage
+
+Plain Markdown — headings, lists, a table, a blockquote — built with the default style pack:
+
+```markdown
+# Project Kickoff Notes
+
+**Date:** 14 April 2026
+**Attendees:** Sarah Chen, Marcus Webb, Priya Nair
+
+---
+
+## Goals for This Sprint
+
+The team aligned on three priorities for the next two weeks:
+
+1. Finalise the data model and get sign-off from the product team
+2. Stand up the staging environment so QA can begin testing early
+3. Resolve the outstanding API authentication issues before the client demo
+
+## Key Decisions
+
+- **Database:** Sticking with PostgreSQL — the migration cost to Mongo isn't justified at this scale
+- **Auth:** Moving to OAuth 2.0 with JWT refresh tokens; existing session-based auth deprecated end of month
+- **Deployment:** Staging mirrors production (same instance type, same region) to avoid environment surprises
+
+## Action Items
+
+| Owner  | Task                                | Due    |
+|--------|-------------------------------------|--------|
+| Marcus | Finalise schema and create migration | 17 Apr |
+| Priya  | Provision staging environment       | 16 Apr |
+| Sarah  | Draft OAuth integration spec        | 18 Apr |
+| All    | Review and comment on API auth RFC  | 15 Apr |
+
+> The client demo is locked in for the 25th — that date is immovable.
+> Flag anything at risk by end of day Wednesday.
+```
+
+Built with `sakusei build getting-started.md`:
+
+[![Project Kickoff Notes PDF](examples/getting-started-screenshot.png)](examples/getting-started.pdf)
+
+The full source is at [`examples/getting-started.md`](examples/getting-started.md).
+
+
+### Style packs and Vue components
+
+The source for a one-page consulting proposal, using a custom style pack with `DocMeta`, `ProcessSteps`, and `DeliverableCards` components:
+
+```markdown
+# Meridian Property Group — Operations Automation Assessment
+
+<vue-component name="DocMeta"
+  client="Meridian Property Group"
+  preparedBy="KD Consulting"
+  date="<%= today('%d %B %Y') %>"
+  status="Proposal"
+  />
+
+
+## Opportunity
+
+Meridian Property Group manages a portfolio of 340 residential and commercial tenancies
+across Southeast Queensland. The business runs on strong fundamentals, but operational
+bandwidth is a growing constraint: leasing coordinators spend the majority of their week
+on routine correspondence, manual data entry, and chasing approvals through email chains.
+This is work that AI and automation can largely eliminate.
+
+KD Consulting proposes a focused **Operations Automation Assessment** — a two-week
+engagement to map current workflows, identify the highest-impact automation opportunities,
+and deliver a clear implementation roadmap.
+
+
+## How We Work
+
+Our methodology is structured around rapid discovery and focused analysis. We do not run
+open-ended workshops or produce lengthy process documentation for its own sake. Every
+step is oriented toward the output: a prioritised set of recommendations the business
+can act on.
+
+<vue-component name="ProcessSteps" steps='[
+  {
+    "title": "Discovery",
+    "description": "Structured interviews with leasing coordinators, property managers,
+    and leadership. We map the full lifecycle of a tenancy — from enquiry through to
+    renewal or exit — and identify where time goes and where friction accumulates."
+  },
+  {
+    "title": "Analysis & Opportunity Mapping",
+    "description": "We analyse workflows against current AI and automation capabilities,
+    assessing each opportunity for feasibility, integration requirements, and business
+    impact."
+  },
+  {
+    "title": "Roadmap & Report",
+    "description": "Prioritised recommendations delivered as a practical implementation
+    roadmap — phased by effort and impact, with clear next steps for each initiative and
+    indicative investment requirements."
+  }
+]' />
+
+
+## Deliverables
+
+<vue-component name="DeliverableCards" columns="3" items='[
+  {
+    "title": "Workflow Assessment",
+    "description": "A clear map of current operations across leasing, tenancy management,
+    and communications — documenting where time is spent and where the significant
+    friction points lie."
+  },
+  {
+    "title": "Automation Opportunity Register",
+    "description": "A structured register of identified automation opportunities, each
+    assessed for business impact, implementation effort, and integration requirements
+    with existing systems."
+  },
+  {
+    "title": "Implementation Roadmap",
+    "description": "A phased, prioritised action plan with recommended sequencing,
+    indicative timelines, and investment estimates — ready to brief a delivery team or
+    internal stakeholders."
+  }
+]' />
+```
+
+Built with `sakusei build meridian-proposal.md -s kd-consulting`:
+
+[![Meridian Property Group proposal PDF](examples/meridian-proposal-screenshot.png)](examples/meridian-proposal.pdf)
+
+The full source is at [`examples/meridian-proposal.md`](examples/meridian-proposal.md).
+
+
 ## Style Packs
 
 Style packs are stored in `.sakusei/style_packs/` directories. Sakusei searches for style packs by walking up the directory tree from your source file.
@@ -126,20 +253,22 @@ Environment: <%= env('RAILS_ENV', 'development') %>
 
 ### Manual Page Breaks
 
-Insert page breaks in your markdown using HTML:
+Insert a page break with the `::break::` shorthand:
 
 ```markdown
 # Chapter 1
 
 Content here...
 
-<div class="page-break"></div>
+::break::
 
 # Chapter 2
 
 More content...
 ```
 
+This expands to `<div class="page-break"></div>` before rendering. You can also use that HTML directly if you prefer.
+
 Available classes:
 - `.page-break` or `.page-break-after` - Break after this element
 - `.page-break-before` - Break before this element

data/examples/getting-started.md

@@ -0,0 +1,31 @@
+# Project Kickoff Notes
+
+**Date:** 14 April 2026  
+**Attendees:** Sarah Chen, Marcus Webb, Priya Nair
+
+---
+
+## Goals for This Sprint
+
+The team aligned on three priorities for the next two weeks:
+
+1. Finalise the data model and get sign-off from the product team
+2. Stand up the staging environment so QA can begin testing early
+3. Resolve the outstanding API authentication issues before the client demo
+
+## Key Decisions
+
+- **Database:** Sticking with PostgreSQL — the migration cost to Mongo isn't justified at this scale
+- **Auth:** Moving to OAuth 2.0 with JWT refresh tokens; existing session-based auth deprecated end of month
+- **Deployment:** Staging mirrors production (same instance type, same region) to avoid environment surprises
+
+## Action Items
+
+| Owner  | Task                               | Due    |
+|--------|------------------------------------|--------|
+| Marcus | Finalise schema and create migration | 17 Apr |
+| Priya  | Provision staging environment      | 16 Apr |
+| Sarah  | Draft OAuth integration spec       | 18 Apr |
+| All    | Review and comment on API auth RFC | 15 Apr |
+
+> The client demo is locked in for the 25th — that date is immovable. Flag anything at risk by end of day Wednesday.

data/examples/meridian-proposal.md

@@ -0,0 +1,61 @@
+# Meridian Property Group — Operations Automation Assessment
+
+<vue-component name="DocMeta"
+  client="Meridian Property Group"
+  preparedBy="KD Consulting"
+  date="<%= today('%d %B %Y') %>"
+  status="Proposal"
+  />
+
+
+Report Generated <%= today %>
+
+## Opportunity
+
+Meridian Property Group manages a portfolio of 340 residential and commercial tenancies across Southeast Queensland. The business runs on strong fundamentals, but operational bandwidth is a growing constraint: leasing coordinators spend the majority of their week on routine correspondence, manual data entry, and chasing approvals through email chains. This is work that AI and automation can largely eliminate.
+
+KD Consulting proposes a focused **Operations Automation Assessment** — a two-week engagement to map current workflows, identify the highest-impact automation opportunities, and deliver a clear implementation roadmap. The outcome is a practical action plan, not a theoretical report. Meridian's team will finish the engagement knowing exactly what to build, in what order, and what it will take to get there.
+
+
+## How We Work
+
+Our methodology is structured around rapid discovery and focused analysis. We do not run open-ended workshops or produce lengthy process documentation for its own sake. Every step is oriented toward the output: a prioritised set of recommendations the business can act on.
+
+<vue-component name="ProcessSteps" steps='[
+  {
+    "title": "Discovery",
+    "description": "Structured interviews with leasing coordinators, property managers, and leadership. We map the full lifecycle of a tenancy — from enquiry through to renewal or exit — and identify where time goes and where friction accumulates."
+  },
+  {
+    "title": "Analysis & Opportunity Mapping",
+    "description": "We analyse workflows against current AI and automation capabilities, assessing each opportunity for feasibility, integration requirements, and business impact. We distinguish quick wins from longer-horizon initiatives."
+  },
+  {
+    "title": "Roadmap & Report",
+    "description": "Prioritised recommendations delivered as a practical implementation roadmap — phased by effort and impact, with clear next steps for each initiative and indicative investment requirements."
+  }
+]' />
+
+
+## Deliverables
+
+<vue-component name="DeliverableCards" columns="3" items='[
+  {
+    "title": "Workflow Assessment",
+    "description": "A clear map of current operations across leasing, tenancy management, and communications — documenting where time is spent and where the significant friction points lie."
+  },
+  {
+    "title": "Automation Opportunity Register",
+    "description": "A structured register of identified automation opportunities, each assessed for business impact, implementation effort, and integration requirements with existing systems."
+  },
+  {
+    "title": "Implementation Roadmap",
+    "description": "A phased, prioritised action plan with recommended sequencing, indicative timelines, and investment estimates — ready to brief a delivery team or internal stakeholders."
+  }
+]' />
+
+---
+
+*This proposal is valid for 30 days from the date above. Prepared in confidence for Meridian Property Group.*
+
+**KD Consulting**

data/lib/sakusei/builder.rb

@@ -30,6 +30,9 @@ module Sakusei
       $stderr.puts "[sakusei] processing ERB..."
       processed_content = process_erb(resolved_content)
 
+      # 3.5. Expand shorthand syntax (e.g. ::break:: → page-break div)
+      processed_content = expand_break_syntax(processed_content)
+
       # 4. Process Vue components (if available)
       processed_content = process_vue(processed_content, style_pack)
 
@@ -67,6 +70,10 @@ module Sakusei
       VueProcessor.new(content, @source_dir, style_pack: style_pack).process
     end
 
+    def expand_break_syntax(content)
+      content.gsub(/::break::/, '<div class="page-break"></div>')
+    end
+
     def wrap_headings(content)
       HeadingWrapper.new(content).wrap
     end

data/lib/sakusei/heading_wrapper.rb

@@ -10,15 +10,65 @@ module Sakusei
   # Raw HTML in the markdown (html: true) passes through md-to-pdf untouched.
   class HeadingWrapper
     HEADING_PATTERN = /\A[ \t]*(##|###) /
+    FENCE_PATTERN = /\A`{3,}/
 
     def initialize(content)
       @content = content
     end
 
     def wrap
+      code_blocks = []
+      text_lines = []
+      in_code = false
+      code_buffer = []
+
+      @content.each_line do |line|
+        if line.match?(FENCE_PATTERN)
+          if in_code
+            # End of code block
+            code_buffer << line
+            code_blocks << code_buffer.join
+            text_lines << "#{placeholder_for(code_blocks.length - 1)}\n\n"
+            code_buffer = []
+            in_code = false
+          else
+            # Start of code block
+            in_code = true
+            code_buffer << line
+          end
+        elsif in_code
+          code_buffer << line
+        else
+          text_lines << line
+        end
+      end
+
+      # Handle unclosed code block
+      if in_code
+        code_blocks << code_buffer.join
+        text_lines << "#{placeholder_for(code_blocks.length - 1)}\n\n"
+      end
+
+      wrapped = wrap_text(text_lines.join)
+
+      # Restore code blocks
+      code_blocks.each_with_index do |block, i|
+        wrapped = wrapped.sub(placeholder_for(i), block)
+      end
+
+      wrapped
+    end
+
+    private
+
+    def placeholder_for(index)
+      "__SAKUSEI_CODE_BLOCK_#{index}__"
+    end
+
+    def wrap_text(content)
       # Split on two-or-more blank lines to get top-level blocks.
       # Preserve the separator length so rejoining is faithful.
-      blocks = @content.split(/(\n{2,})/)
+      blocks = content.split(/(\n{2,})/)
       # split with a capture group gives us [block, sep, block, sep, ...]
       result = []
       i = 0
@@ -47,8 +97,6 @@ module Sakusei
       result.join
     end
 
-    private
-
     def heading_block?(block)
       return false unless block
       block.match?(HEADING_PATTERN)

data/lib/sakusei/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sakusei
-  VERSION = '0.2.2'
+  VERSION = '0.4.0'
 end

data/lib/templates/default_style_pack/config.js

@@ -17,7 +17,7 @@ module.exports = {
     `,
     footerTemplate: `
       <div style="font-size: 9px; width: 100%; text-align: center; color: #666;">
-        Page <span class="pageNumber"></span> of <span class="totalPages"></span>
+        <span class="pageNumber"></span>
       </div>
     `
   },

data/lib/templates/default_style_pack/footer.html

@@ -1,5 +1,5 @@
 <!-- Custom footer template - used when configured in config.js -->
 <!-- Available classes: date, title, url, pageNumber, totalPages -->
 <div style="font-size: 9px; width: 100%; text-align: center; color: #666;">
-  Page <span class="pageNumber"></span> of <span class="totalPages"></span>
+  <span class="pageNumber"></span>
 </div>

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sakusei
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Keith Rowell
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-14 00:00:00.000000000 Z
+date: 2026-04-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -80,6 +80,12 @@ files:
 - README.md
 - Rakefile
 - bin/sakusei
+- examples/getting-started-screenshot.png
+- examples/getting-started.md
+- examples/getting-started.pdf
+- examples/meridian-proposal-screenshot.png
+- examples/meridian-proposal.md
+- examples/meridian-proposal.pdf
 - lib/sakusei.rb
 - lib/sakusei/builder.rb
 - lib/sakusei/cli.rb