Bashticle

Bashticle

Transform markdown blog posts into interactive bash scripts that users can read and execute directly from their terminal.

When to Use

Use this skill when a user asks to:

• "Create a bashticle from this markdown"
• "Turn this article into an interactive bash script"
• "Make a terminal-based interactive article"
• "Convert blog.md to a bash article"

Two-Phase Approach

Bashticle creation uses a two-phase approach:

Phase 1: Generator Script (Boring, Structural)

The bashticle-generator.sh script does the structural work:

# Run the generator
bashticle-generator.sh article.md
# Or with custom output:
bashticle-generator.sh article.md --output-file custom.sh

What it does:

• Parses markdown for structure (title, sections)
• Generates basic bashticle with STANDARD options only
• Creates section function stubs
• Builds main navigation flow

Standard options included:

• --step - Jump to specific section
• --run-command / -r - Execute commands vs echo
• --dry-run / -d - Echo only (default: ON)
• --stream / -s - Enable streaming (default: ON)
• --verbose / -v - Verbose output

Phase 2: AI (Smart, Context-Aware)

The AI (via this skill) enhances the bashticle:

1. Read both files: Original markdown + generated bashticle
2. Use parseArger parse to add article-specific options:

   parseArger parse bashticle.sh --inplace \
     --opt 'ai-provider "AI provider" --short p --default-value "openrouter"' \
     --opt 'ai-model "AI model" --short m' \
     --opt 'api-key "API key" --short k' \
     --opt 'project-name "Project name"' \
     --opt 'reasoning "Reasoning tokens" --default-value "4096"'
   

3. Fill in section functions with actual content
4. Convert code blocks to command arrays with proper variable injection

What Gets Generated

A .sh file with:

• parseArger CLI - Full argument parsing with sensible defaults
• Helper functions - stream_text, print_section, prompt_continue, run_cmd, show_cmd
• Section stubs - One function per markdown section (AI fills these)
• Main flow - Navigation with --step support

Example Workflow

# Step 1: Generate basic structure
bashticle-generator.sh article.md

# Step 2: AI enhances it (via this skill)
# - Adds article-specific options with parseArger parse
# - Fills in section content
# - Converts code blocks to command arrays

Converting Markdown to Bash

Sections (## headers)

Each ## or ### header becomes a bash function:

## Getting Started
Content here...

Generated stub:

show_getting_started() {
  print_section "Getting Started"
  # TODO: AI fills this in with actual content
  prompt_continue
}

AI fills in:

show_getting_started() {
  print_section "Getting Started"

  stream_text "Content here..."

  # Convert code blocks to command arrays
  local init_cmd=(npm install)
  show_cmd "Install dependencies" npm install
  run_cmd "${init_cmd[@]}"

  prompt_continue
}

Code Blocks (```bash)

Code blocks are converted to command arrays with variable injection:

```bash
npx task-o-matic@latest init --project-name my-project

AI converts to:
```bash
local init_cmd=(
  npx task-o-matic@latest init
  --project-name "$_arg_project_name"  # Variable injection
)
run_cmd "${init_cmd[@]}"

Helper Functions

stream_text "text" [delay]           # Typewriter effect (5ms default)
print_section "title"                # Cyan section header
print_subsection "title"             # Yellow subsection
prompt_continue                      # Green "Press Enter" prompt
run_cmd arg1 arg2 ...               # Execute or echo based on flags
show_cmd "explanation" cmd ...      # Display command with description

Available Variables

Variables from CLI arguments (after AI adds them):

$_arg_ai_provider     # --ai-provider value (if AI article)
$_arg_ai_model        # --ai-model value (if AI article)
$_arg_api_key         # --api-key value (if AI article)
$_arg_project_name    # --project-name value (if applicable)
$_arg_reasoning       # --reasoning value (if AI article)
$_arg_stream          # --stream flag
$_arg_run_command     # --run-command flag
$_arg_dry_run         # --dry-run flag
$_arg_verbose         # --verbose flag
$_arg_step            # Section to jump to

Color Scheme

• Cyan (36): Section headers
• Yellow (33): Subsections
• Green (32): User prompts
• Magenta (35): Commands
• White (37): Explanations
• Gray (90): Dry-run messages

Examples

Generator creates:

show_init() {
  print_section "Initialization"
  # TODO: AI fills this in
  prompt_continue
}

AI converts to:

show_init() {
  print_section "Initialization"

  stream_text "Let's initialize the project..."
  echo ""

  show_cmd "Initialize with task-o-matic" \
    npx task-o-matic@latest init init \
    --project-name "$_arg_project_name" \
    --frontend tanstack-router

  run_cmd npx task-o-matic@latest init init \
    --project-name "$_arg_project_name" \
    --frontend tanstack-router

  echo ""
  stream_text "Project initialized!"
  echo ""

  prompt_continue
}

Running Generated Bashticles

# View help
./bashticle.sh --help

# Run full article (dry-run mode - default)
./bashticle.sh

# Jump to specific section
./bashticle.sh init

# Run with actual command execution (use in test directory!)
./bashticle.sh --run-command --ai-provider anthropic

# Disable streaming for faster output
./bashticle.sh --no-stream

Implementation Notes

What the Generator Does (Deterministic)

• Extract title from frontmatter or first heading
• Find all ## and ### sections
• Generate basic parseArger CLI with standard options
• Create section function stubs
• Build main navigation flow
• Always include helper functions

What the AI Does (Context-Aware)

• Analyze article content to determine needed options
• Use parseArger parse to add relevant CLI options
• Fill in section functions with actual content
• Convert code blocks to command arrays
• Inject CLI variables into commands appropriately
• Handle article-specific patterns and conventions

Files

• Generator: scripts/bashticle-generator.sh
• Example bashticle: apps/web/content/blog/Black hole/From ralph to Eric/bashticle.sh
• Helpers reference: references/helpers.md