mirror of
https://github.com/hanzoskill/substack-formatter.git
synced 2026-10-30 21:10:22 +00:00
388 lines
13 KiB
Python
388 lines
13 KiB
Python
#!/usr/bin/env python3
|
|
"""
|
|
Substack Article Formatter - Transform plain text using viral Substack patterns
|
|
Based on analysis of 80+ viral Substack posts
|
|
"""
|
|
|
|
import re
|
|
import sys
|
|
import html
|
|
|
|
class SubstackFormatter:
|
|
def __init__(self):
|
|
self.engagement_questions = [
|
|
"What's your experience with this?",
|
|
"How does this land for you?",
|
|
"What would you add?",
|
|
"Does this resonate?",
|
|
"What's your take?",
|
|
"Have you noticed this too?",
|
|
"What am I missing here?",
|
|
"Share your story below 👇"
|
|
]
|
|
|
|
self.contrarian_hooks = [
|
|
"Everyone says",
|
|
"Most people think",
|
|
"The conventional wisdom is",
|
|
"You've probably heard",
|
|
"The popular belief is"
|
|
]
|
|
|
|
def format_text(self, text, structure="minimal", target_length="optimal"):
|
|
"""Apply Substack formatting to input text"""
|
|
# Clean and analyze input
|
|
text = self.clean_input(text)
|
|
word_count = len(text.split())
|
|
|
|
# Determine structure if auto
|
|
if structure == "auto":
|
|
structure = self.detect_best_structure(text, word_count)
|
|
|
|
# Format based on structure type
|
|
if structure == "punchy-wisdom":
|
|
return self.format_punchy_wisdom(text)
|
|
elif structure == "micro-story":
|
|
return self.format_micro_story(text)
|
|
elif structure == "list":
|
|
return self.format_list(text)
|
|
elif structure == "contrarian":
|
|
return self.format_contrarian(text)
|
|
elif structure == "relatable":
|
|
return self.format_relatable(text)
|
|
elif structure == "poetic":
|
|
return self.format_poetic(text)
|
|
else:
|
|
return self.format_general(text, target_length)
|
|
|
|
def clean_input(self, text):
|
|
"""Basic cleanup of input text"""
|
|
# Remove extra whitespace but preserve intentional breaks
|
|
lines = text.split('\n')
|
|
cleaned_lines = []
|
|
|
|
for line in lines:
|
|
cleaned = line.strip()
|
|
if cleaned:
|
|
cleaned_lines.append(cleaned)
|
|
elif cleaned_lines and cleaned_lines[-1]:
|
|
cleaned_lines.append('')
|
|
|
|
return '\n'.join(cleaned_lines)
|
|
|
|
def detect_best_structure(self, text, word_count):
|
|
"""Auto-detect the best structure based on content"""
|
|
text_lower = text.lower()
|
|
|
|
# Very short = punchy wisdom
|
|
if word_count < 40:
|
|
return "punchy-wisdom"
|
|
|
|
# Contains story elements = micro-story
|
|
story_indicators = ['i was', 'last week', 'yesterday', 'then i', 'suddenly', 'but then']
|
|
if any(indicator in text_lower for indicator in story_indicators):
|
|
return "micro-story"
|
|
|
|
# Contains contrarian language = contrarian
|
|
if any(hook.lower() in text_lower for hook in self.contrarian_hooks):
|
|
return "contrarian"
|
|
|
|
# Contains list patterns = list
|
|
list_indicators = ['first', 'second', 'third', '1.', '2.', '3.', '•', '-']
|
|
if any(indicator in text_lower for indicator in list_indicators):
|
|
return "list"
|
|
|
|
# Contains humor indicators = relatable
|
|
humor_indicators = ['lol', 'haha', 'funny', 'hilarious', 'ridiculous']
|
|
if any(indicator in text_lower for indicator in humor_indicators):
|
|
return "relatable"
|
|
|
|
# Default to general formatting
|
|
return "general"
|
|
|
|
def format_punchy_wisdom(self, text):
|
|
"""Format as punchy wisdom (30-60 words)"""
|
|
sentences = self.split_sentences(text)
|
|
|
|
if len(sentences) < 2:
|
|
# Single powerful statement
|
|
return f"<p><strong>{html.escape(sentences[0])}</strong></p>"
|
|
|
|
# First sentence as hook, rest as context
|
|
hook = sentences[0]
|
|
context = '. '.join(sentences[1:])
|
|
|
|
return f"""<p><strong>{html.escape(hook)}</strong></p>
|
|
|
|
<p>{html.escape(context)}</p>"""
|
|
|
|
def format_micro_story(self, text):
|
|
"""Format as micro-story with twist ending"""
|
|
sentences = self.split_sentences(text)
|
|
|
|
if len(sentences) < 3:
|
|
return self.format_general(text, "optimal")
|
|
|
|
# Group into story parts
|
|
setup = sentences[:len(sentences)//2]
|
|
twist = sentences[len(sentences)//2:-1]
|
|
revelation = sentences[-1]
|
|
|
|
html_parts = []
|
|
|
|
# Setup (hook the reader)
|
|
for sentence in setup[:2]: # Max 2 setup sentences
|
|
html_parts.append(f"<p>{html.escape(sentence)}</p>")
|
|
|
|
# Twist/action (short paragraphs)
|
|
if twist:
|
|
twist_text = '. '.join(twist)
|
|
# Break into short lines for tension
|
|
twist_parts = self.break_into_short_lines(twist_text)
|
|
for part in twist_parts:
|
|
html_parts.append(f"<p>{html.escape(part)}</p>")
|
|
|
|
# Revelation (emphasized)
|
|
html_parts.append(f"<p><strong>{html.escape(revelation)}</strong></p>")
|
|
|
|
# Add engagement question
|
|
html_parts.append(f"<p><em>{self.get_random_question()}</em></p>")
|
|
|
|
return '\n\n'.join(html_parts)
|
|
|
|
def format_list(self, text):
|
|
"""Format as bulleted/numbered list"""
|
|
items = self.extract_list_items(text)
|
|
intro = self.extract_intro_text(text)
|
|
|
|
html_parts = []
|
|
|
|
# Add intro if exists
|
|
if intro:
|
|
html_parts.append(f"<p><strong>{html.escape(intro)}</strong></p>")
|
|
|
|
# Format items
|
|
if len(items) > 1:
|
|
html_parts.append("<ul>")
|
|
for item in items[:5]: # Max 5 items for optimal length
|
|
clean_item = self.clean_list_item(item)
|
|
html_parts.append(f"<li><strong>{html.escape(clean_item)}</strong></li>")
|
|
html_parts.append("</ul>")
|
|
|
|
# Add CTA
|
|
html_parts.append(f"<p><em>{self.get_random_question()}</em></p>")
|
|
|
|
return '\n'.join(html_parts)
|
|
|
|
def format_contrarian(self, text):
|
|
"""Format contrarian take with hook-evidence-conclusion"""
|
|
sentences = self.split_sentences(text)
|
|
|
|
if len(sentences) < 2:
|
|
return self.format_punchy_wisdom(text)
|
|
|
|
# First sentence should be the contrarian hook
|
|
hook = sentences[0]
|
|
evidence = sentences[1:-1] if len(sentences) > 2 else []
|
|
conclusion = sentences[-1] if len(sentences) > 1 else ""
|
|
|
|
html_parts = []
|
|
|
|
# Bold contrarian statement
|
|
html_parts.append(f"<p><strong>{html.escape(hook)}</strong></p>")
|
|
|
|
# Evidence (if any)
|
|
if evidence:
|
|
evidence_text = '. '.join(evidence)
|
|
html_parts.append(f"<p>{html.escape(evidence_text)}</p>")
|
|
|
|
# Conclusion
|
|
if conclusion:
|
|
html_parts.append(f"<p><em>{html.escape(conclusion)}</em></p>")
|
|
|
|
# Engagement question
|
|
html_parts.append(f"<p>{self.get_random_question()}</p>")
|
|
|
|
return '\n\n'.join(html_parts)
|
|
|
|
def format_relatable(self, text):
|
|
"""Format relatable humor with setup-scenario-punchline"""
|
|
sentences = self.split_sentences(text)
|
|
|
|
if len(sentences) < 2:
|
|
return self.format_general(text, "optimal")
|
|
|
|
# Structure: setup, scenario(s), punchline
|
|
setup = sentences[0]
|
|
scenario = sentences[1:-1] if len(sentences) > 2 else []
|
|
punchline = sentences[-1]
|
|
|
|
html_parts = []
|
|
|
|
# Setup
|
|
html_parts.append(f"<p>{html.escape(setup)}</p>")
|
|
|
|
# Scenario (short lines for comedic timing)
|
|
for sentence in scenario:
|
|
html_parts.append(f"<p>{html.escape(sentence)}</p>")
|
|
|
|
# Punchline (emphasized)
|
|
html_parts.append(f"<p><strong>{html.escape(punchline)}</strong></p>")
|
|
|
|
# Light engagement
|
|
html_parts.append(f"<p><em>Can you relate? 😅</em></p>")
|
|
|
|
return '\n\n'.join(html_parts)
|
|
|
|
def format_poetic(self, text):
|
|
"""Format as poetic reflection with rhythm"""
|
|
lines = text.split('. ')
|
|
|
|
html_parts = []
|
|
html_parts.append("<p>")
|
|
|
|
# Each phrase on its own line with <br> tags
|
|
for i, line in enumerate(lines):
|
|
if i > 0:
|
|
html_parts.append("<br>")
|
|
html_parts.append(html.escape(line.strip()))
|
|
|
|
html_parts.append("</p>")
|
|
|
|
# Add reflective CTA
|
|
html_parts.append(f"<p><em>What resonates with you?</em></p>")
|
|
|
|
return '\n'.join(html_parts)
|
|
|
|
def format_general(self, text, target_length):
|
|
"""General formatting with viral patterns applied"""
|
|
sentences = self.split_sentences(text)
|
|
|
|
# Optimize for target length (50-120 words optimal)
|
|
word_count = len(text.split())
|
|
|
|
html_parts = []
|
|
|
|
# Strong opening
|
|
if sentences:
|
|
html_parts.append(f"<p><strong>{html.escape(sentences[0])}</strong></p>")
|
|
|
|
# Body with short paragraphs
|
|
body_sentences = sentences[1:-1] if len(sentences) > 2 else sentences[1:]
|
|
for sentence in body_sentences:
|
|
# Emphasize key insights
|
|
if self.is_key_insight(sentence):
|
|
html_parts.append(f"<p><em>{html.escape(sentence)}</em></p>")
|
|
else:
|
|
html_parts.append(f"<p>{html.escape(sentence)}</p>")
|
|
|
|
# Strong conclusion if available
|
|
if len(sentences) > 1:
|
|
conclusion = sentences[-1]
|
|
html_parts.append(f"<p><strong>{html.escape(conclusion)}</strong></p>")
|
|
|
|
# Engagement CTA
|
|
html_parts.append(f"<p>{self.get_random_question()}</p>")
|
|
|
|
return '\n\n'.join(html_parts)
|
|
|
|
def split_sentences(self, text):
|
|
"""Split text into sentences"""
|
|
sentences = re.split(r'[.!?]+', text)
|
|
return [s.strip() for s in sentences if s.strip()]
|
|
|
|
def break_into_short_lines(self, text, max_words=8):
|
|
"""Break text into short lines for tension/readability"""
|
|
words = text.split()
|
|
lines = []
|
|
current_line = []
|
|
|
|
for word in words:
|
|
current_line.append(word)
|
|
if len(current_line) >= max_words or word.endswith('.'):
|
|
lines.append(' '.join(current_line))
|
|
current_line = []
|
|
|
|
if current_line:
|
|
lines.append(' '.join(current_line))
|
|
|
|
return lines
|
|
|
|
def extract_list_items(self, text):
|
|
"""Extract list items from text"""
|
|
patterns = [
|
|
r'^\d+[.)]\s*(.+)', # 1. or 1)
|
|
r'^\*\s*(.+)', # * bullets
|
|
r'^\-\s*(.+)', # - bullets
|
|
r'(?:First|Second|Third|Fourth|Fifth)[,\s]+(.+?)(?=(?:First|Second|Third|Fourth|Fifth|$))'
|
|
]
|
|
|
|
items = []
|
|
for pattern in patterns:
|
|
matches = re.findall(pattern, text, re.MULTILINE | re.IGNORECASE)
|
|
if matches:
|
|
items.extend(matches)
|
|
break
|
|
|
|
# Fallback: split by periods if no clear list pattern
|
|
if not items:
|
|
sentences = self.split_sentences(text)
|
|
if len(sentences) > 2:
|
|
items = sentences[1:] # Skip intro sentence
|
|
|
|
return items[:5] # Max 5 items
|
|
|
|
def extract_intro_text(self, text):
|
|
"""Extract introductory text before list items"""
|
|
first_item_match = re.search(r'(^\d+[.)]|^\*|^\-|First|Here are)', text, re.MULTILINE | re.IGNORECASE)
|
|
if first_item_match:
|
|
intro = text[:first_item_match.start()].strip()
|
|
if intro:
|
|
return intro
|
|
|
|
# Fallback: first sentence
|
|
sentences = self.split_sentences(text)
|
|
if sentences:
|
|
return sentences[0]
|
|
|
|
return ""
|
|
|
|
def clean_list_item(self, item):
|
|
"""Clean up list item text"""
|
|
# Remove any residual numbering or bullets
|
|
item = re.sub(r'^\d+[.)]\s*', '', item)
|
|
item = re.sub(r'^[*\-]\s*', '', item)
|
|
return item.strip()
|
|
|
|
def is_key_insight(self, sentence):
|
|
"""Detect if sentence contains key insight worthy of emphasis"""
|
|
insight_indicators = [
|
|
'the key is', 'the secret', 'here\'s why', 'the truth is',
|
|
'what i learned', 'the lesson', 'remember this', 'most important'
|
|
]
|
|
sentence_lower = sentence.lower()
|
|
return any(indicator in sentence_lower for indicator in insight_indicators)
|
|
|
|
def get_random_question(self):
|
|
"""Get random engagement question"""
|
|
import random
|
|
return random.choice(self.engagement_questions)
|
|
|
|
def main():
|
|
formatter = SubstackFormatter()
|
|
|
|
if len(sys.argv) < 2:
|
|
print("Usage: python3 formatter.py 'your text here' [structure] [length]")
|
|
print("Structures: auto, punchy-wisdom, micro-story, list, contrarian, relatable, poetic")
|
|
print("Lengths: short, optimal, long")
|
|
return
|
|
|
|
text = sys.argv[1]
|
|
structure = sys.argv[2] if len(sys.argv) > 2 else "auto"
|
|
length = sys.argv[3] if len(sys.argv) > 3 else "optimal"
|
|
|
|
formatted = formatter.format_text(text, structure, length)
|
|
print(formatted)
|
|
|
|
if __name__ == "__main__":
|
|
main() |