# Bashticle

> Create interactive bash articles (bashticles) from markdown blog posts with streaming text, command execution, and user interaction

- Skill: `dimitrigilbert/bashticle` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add dimitrigilbert/bashticle`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dimitrigilbert/bashticle/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: dimitrigilbert (https://skillmd.com/u/dimitrigilbert)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dimitrigilbert/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:

```bash
# 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:
   ```bash
   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

```bash
# 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:

```markdown
## Getting Started
Content here...
```

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

AI fills in:
```bash
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:

```markdown
```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

```bash
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):

```bash
$_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:**
```bash
show_init() {
  print_section "Initialization"
  # TODO: AI fills this in
  prompt_continue
}
```

**AI converts to:**
```bash
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

```bash
# 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`