I’ve released v4 of md-lipsum, my API for generating Markdown Lorem Ipsum. This update introduces expanded source options, new query parameters for enhanced functionality, and is powered by the new ‘random-words’ Ruby gem.

Try the new API: https://brettterpstra.com/md-lipsum

Share Your Shortcuts!

If you use the API to create any Apple Shortcuts, System Services, command line scripts, or other automations, please share in the comments/forum! I’d love to highlight any use cases out there.

What’s New in API v4

Expanded Source Options

The biggest change in v4 is the expansion of available text sources. While previous versions were limited to basic Lorem Ipsum, v4 now offers 14 different source languages and themes:

  • lipsum - Lorem Ipsum (default)
  • 1984 - George Orwell’s 1984
  • alice - Alice in Wonderland
  • bacon - Bacon ipsum
  • corporate - Corporate Buzzwords
  • doctor - Doctor Who
  • english - English text
  • foulmouth - Foulmouth ipsum
  • hipster - Hipster ipsum
  • latin - Latin text
  • spanish - Spanish text
  • veggie - Vegetarian ipsum
  • walken - Christopher Walken
  • random - Random source

You can use any of these sources by appending ?source=SOURCE_NAME to your API calls:

https://brettterpstra.com/md-lipsum/api/4/6/short/all/?source=1984

New Query Parameters

API v4 introduces several new query parameters for enhanced functionality:

?preview=true

This parameter enables preview mode, which renders the HTML output in a styled format instead of returning raw HTML. Perfect for seeing how your generated content will look when styled.

?style=PATH

Allows you to specify a custom stylesheet for the HTML output. The path should be URL-encoded:

?style=%2Fmd-lipsum%2Fstylesheets%2Fpreview.css

You can also use full URLs to external stylesheets:

?style=https://example.com/styles.css
?html=true

This option returns raw HTML instead of Markdown.

?complete=true

When combined with html=true, this parameter returns a complete HTML document with proper <html>, <head>, and <body> tags, making it ready for direct use.

Example API Calls

Here are some examples of the new v4 API in action:

# Generate HTML with 1984
curl 'https://brettterpstra.com/md-lipsum/api/4/6/short/all/?html=true&source=1984'

# Preview mode with corporate buzzwords
curl 'https://brettterpstra.com/md-lipsum/api/4/5/medium/header/link/bq/?preview=true&source=corporate'

# Raw Markdown with long sentencs and Doctor Who source
curl 'https://brettterpstra.com/md-lipsum/api/4/3/long/all/?source=doctor'

The random-words gem

The Markdown Lipsum API v4 is now powered by the new random-words Ruby gem, which provides a comprehensive solution for generating random text content. This gem is available for both command-line use and as a Ruby library.

Full documentation can be found on RubyDocs and the source is on GitHub.

Installation

gem install random-words

Depending on your setup, you may need:

gem install --user-install random-words

Or in worst case scenario:

sudo gem install random-words

You can also use brew gem install random-words if you use Homebrew.

Using as a Ruby Library

The random-words gem provides a clean Ruby API for generating random content:

require 'random-words'

# Create a generator with a specific source
rw = RandomWords::Generator.new(:corporate)

# List all available dictionaries
puts rw.sources

# Change source dictionary
rw.source = :bacon

# Configure paragraph and sentence lengths
rw.paragraph_length = 5 # Number of sentences in a paragraph (default 3)
rw.sentence_length = :short # :short, :medium, :long, :verylong (default :medium)

# Generate different types of content
puts rw.sentence                    # Single sentence
puts rw.sentences(3)               # Array of 3 sentences
puts rw.paragraph                  # Single paragraph
puts rw.paragraph(2)               # Paragraph with 2 sentences
puts rw.characters(100)            # Text limited to 100 characters
puts rw.characters(100, whole_words: false) # Allow truncation

# Access parts of speech directly
puts rw.adjectives.sample
puts rw.nouns.sample
puts rw.verbs.sample

Available Sources

The gem comes with the same 14 sources available in the API:

rw = RandomWords::Generator.new(:lipsum)    # Lorem Ipsum
rw = RandomWords::Generator.new(:'1984')    # George Orwell's 1984
rw = RandomWords::Generator.new(:alice)     # Alice in Wonderland
rw = RandomWords::Generator.new(:bacon)     # Bacon ipsum
rw = RandomWords::Generator.new(:corporate) # Corporate Buzzwords
rw = RandomWords::Generator.new(:doctor)    # Doctor Who
rw = RandomWords::Generator.new(:english)   # English text
rw = RandomWords::Generator.new(:foulmouth) # Foulmouth ipsum
rw = RandomWords::Generator.new(:hipster)   # Hipster ipsum
rw = RandomWords::Generator.new(:latin)     # Latin text
rw = RandomWords::Generator.new(:spanish)   # Spanish text
rw = RandomWords::Generator.new(:veggie)    # Vegetarian ipsum
rw = RandomWords::Generator.new(:walken)    # Christopher Walken

The randw Binary

Installing the gem also provides a powerful command-line tool called randw. Here’s what you can do with it:

Available Commands

$ randw -h

Usage: randw [options]

OPTIONS:
    -S, --source SOURCE              Specify the source language (default: latin)
    -l, --length LENGTH              Specify the length of the sentence [short|medium|long|very_long]
        --graf-length NUMBER         Specify the number of sentences in a paragraph
        --[no-]extended              Specify whether to use extended punctuation in generated text

GENERATORS:
    -s, --sentences [NUMBER]         Generate NUMBER of random sentences (default: 3)
    -p, --paragraphs [NUMBER]        Generate NUMBER of random paragraphs (default: 3)
    -w, --words [NUMBER]             Generate NUMBER of random words (default: 10)
    -c, --characters [NUMBER]        Generate random characters of length (default: 100)
    -m, --markdown [SETTINGS]        Generate random markdown text
    -H, --html [SETTINGS]            Generate random html text
        --password [LENGTH]          Generate a random password of LENGTH (default: 20)

DICTIONARIES:
        --list-dictionaries          List available dictionaries
        --create-dictionary [NAME]   Create a new dictionary

OTHER OPTIONS:
    -d, --debug                      Enable debug mode
    -h, --help                       Display help message
    -v, --version                    Display version
    -t, --test                       Run debug test

Command Examples

# Generate sentences with different sources
randw -s 5 -S corporate
randw -s 3 -S bacon

# Generate markdown with specific elements
randw -m "latin/1/short/ol"        # Latin, 1 paragraph, short length, ordered lists
randw -m "english,5,all"           # English, 5 paragraphs, all elements

# Generate HTML content
randw -H "corporate/medium/3/header/link"

# Generate a random password
randw --password 25

# List all available dictionaries
randw --list-dictionaries

# Create a new dictionary
randw --create-dictionary medical

Markdown Generation

The --markdown flag is particularly powerful, allowing you to specify exactly which elements to include:

trigger element
dec add em and strong
link add links
ul add unordered lists
ol add ordered lists
dl add definition lists
bq add block quotes
code add code spans and blocks
mark add ==highlights==
headers add headlines
image add images
table add tables
x add extended punctuation

Example:

$ randw -m "latin/1/short/ol"

Illa brevis muros potior arcesso, apud multae octo centum nonaginta octo nodum!

1. Hoc cognatus opus facile complor latus discendo
2. Aliqua apparens census quod nego
3. Nullus salvus dux apud habeo spectabilis

Creating Custom Dictionaries

One of the most exciting features of the random-words gem is the ability to create your own custom dictionaries. This allows you to generate content in specialized domains like medical terminology, legal jargon, or any other field-specific language.

Getting Started

To create a new dictionary, use the CLI command:

randw --create-dictionary [NAME]

This creates a new directory in ~/.config/random-words/words/[NAME] with all the necessary files populated with English defaults.

Required Files

Each dictionary needs these files:

  • adjectives.txt
  • adverbs.txt
  • articles-plural.txt
  • articles-singular.txt
  • clauses.txt
  • config.yml
  • conjunctions-coordinating.txt
  • conjunctions-subordinate.txt
  • names.txt
  • nouns-plural.txt
  • nouns-singular.txt
  • numbers.txt
  • phrases.txt
  • prepositions.txt
  • terminators.txt
  • verbs-passive.txt
  • verbs-plural.txt
  • verbs-singular.txt

Configuration

The config.yml file controls how your dictionary works:

name: medical
description: Medical terminology
triggers: [medical, medicine, health]
extended_punctuation: false
  • name: The name of the dictionary
  • description: Display description
  • triggers: Alternative names that can be used to access the dictionary
  • extended_punctuation: Whether to include extended punctuation

For detailed information about creating custom dictionaries, see the GitHub documentation.

Wrapping up

Markdown Lipsum API v4 represents a significant step forward in random text generation, offering expanded source options, new query parameters, and the flexibility of the random-words gem. Whether you’re using the API for quick placeholder content or the gem for programmatic text generation, you now have access to a much richer set of tools for creating random content.

The combination of the web API and the Ruby gem provides flexibility for both quick one-off uses and more complex applications requiring custom dictionaries and programmatic control.

Try the new API at https://brettterpstra.com/md-lipsum

Enjoy, and please let me know in the comments if you have any questions or suggestions, or just want to let me know how you’ve implemented it. I’d love to share any Shortcuts or Services (or command line scripts) you create, so don’t be shy.