Skip to content

Home

Jump to bottom
Nicholas Jitkoff edited this page Nov 12, 2022 · 15 revisions

This document covers advanced use for itty.bitty

Creating Content

Handcrafted HTML files

Drag one into the editor to convert it.

Using Codepen.io (Pro Accounts)

Paste a codepen URL into the editor. Get started with a template or look at some samples. This must be a Pro account to work.

Hosting Content

Domain Forwarding

One simple way to host is to forward a domain. Just paste the itty.bitty url in the redirect.

Shortlinks and Twitter

Most shortlink providers (and Twitter shortlinks) can serve as a host, but note that they may have a size limit.

Size Limits

While most sites support 2000 bytes, some can handle more. Maximum sizes for links in various apps & Browsers (approximate, size in bytes)

App Max bytes Notes
Twitter 4,088
Slack 4,000
Discord 4,000
iMessage 4,000 URLs with more than 300 nonbreaking characters in a row will be split.
LZMA compression usually fixes this, but raw data urls may fail.
QR Code 2,953
Bitly 2,048
Tinyurl 15,996 16,000 bytes and more get an error msg
Browser
Google Chrome (win) 32,779
(mac) Lots Only 32,775 in url bar
Firefox >64,000
Microsoft IE 11 4,043 Only shows 2,083
Microsoft Edge 2,083 Anything over 2083 will fail
Android 8,192
Safari Lots Only shows 5211

Generating links programmatically

Because they use standard formats, you can generate and decode itty.bitty links from the command line

Encoding (Mac)

echo -n 'hello world' | lzma -9 | base64 | xargs -0 printf "https://itty.bitty.site/#/%s\n"

Encoding (Linux)

echo -n 'hello world' | lzma -9 | base64 -w0 | xargs -0 printf "https://itty.bitty.site/#/%s\n"

Encoding (Win Git/WSL)

echo -n 'hello world' | xz --format=lzma -9 | base64 -w0 | printf "https://itty.bitty.site/#/%s\n" "$(cat -)"

Encoding (Python)

'https://itty.bitty.site/#/'+base64.b64encode(lzma.compress(bytes("hello world",encoding="utf-8"), format=lzma.FORMAT_ALONE, preset=9)).decode("utf-8")

Encoding (Node.js)

'https://itty.bitty.site/#/'+Buffer.from(lzma.compress("Hello World", 9)).toString('base64')

Decoding (Mac)

echo -n "[URL]" | sed -E 's/^.*#[^\/]*\/\??//g' | base64 -D | lzma -d

Decoding (Linux)

echo -n "[URL]" | sed -E 's/^.*#[^\/]*\/\??//g' | base64 -d | lzma -d

Decoding (Win Git/WSL)

echo -n "[URL]" | sed 's/^.*#[^\/]*\///g' | base64 -d | xz --format=lzma -d

URL Structure

IB1 structure

https:// HOST/ # [TITLE] / PAYLOAD

Examples:

IB2 structure

https:// HOST/ [HOST_METADATA/] # [CLIENT_METADATA] / PAYLOAD

Examples:

Attributes

  • HOST - usually itty.bitty.app

  • HOST METADATA - TITLE/d/DESCRIPTION/i/IMAGE/f/FAVICON

    • Host Metadata is sent to server edge nodes to generate opengraph data for previews.
    • Also used to set title and favicon of rendered page
    • Only title is inlined without a preceding letter, to aid legibility
    • Dashes are replaced with spaces.

  • CLIENT METADATA - favicon[/]secrettitle

    • Client Metadata is secret, but doesn’t yield previews.
    • Used to set title and favicon of rendered page, overriding the above if present.
    • Used to set name for downloaded documents

  • PAYLOAD - A valid URI or a data blob with a shorthand type identifier

    • PAYLOAD format:

      • Valid data URL (data://…;,WXA…)
      • Shorthand prefix (representing standard data url types)
      • Other URL scheme (iframed/forwarded)

    • Data URLs: data:MIME_TYPE[;ATTR=VALUE…];base64,content

      • MIME_TYPE (like "text/plain")
      • ATTRS - key value pairs about content format
        • format=br; (Compression format - gz: gzip, br: brotli, xz: lzma),
        • render=download; (Renderer, either known renderer, or url for js file)
        • cipher=aes; (Encryption cipher type)
        • charset=UTF-8; (Standard attribute for text)
      • base64, - standard base64, or bxz64 (legacy designation for XZ compression. use the format ATTR instead)

IB V.1 endpoint

The legacy V.1 version of itty bitty (which supports IE11) will remain available at https://itty.bitty.site/v1/

IB V.2 features

Itty bitty V.2 uses features of newer browsers, and should work on the latest versions of each. These features are works in progress, and may be unstable or change.

Compression formats

IB2 supports Gzip and Brotli compression. Gzip will be used in lieu of lzma if it yields a smaller result. Client side brotli compression is not implemented. Compression type will be inferred from the first few bytes of data if not specified

brotli

echo -n 'hello world' | brotli | base64 | xargs -0 printf "https://itty.bitty.app/#data:text/plain;format=br;base64,/%s\n"

gzip

echo -n 'hello world' | gzip -9 | base64 | xargs -0 printf "https://itty.bitty.app/#/%s\n"

Encryption

Encrypted content will prompt for a password before decoding. Encryption type should be specified with cipher=\[aes|des|...];.

echo -n 'hello world' | gzip -9 | openssl enc -aes-256-cbc -salt | base64 | xargs -0 printf "https://itty.bitty.app/#/data:text/plain;format=gz;cipher=aes;base64,%s\n"

Chat + Social media metadata (Open Graph)

Title, description, and image can be included as path components before the # fragment. If present, these will be rendered as the preview data. Note: Including this metadata requires serverside rendering - the body of the content will still be rendered clientside.

  • Title is the first path component.

    • /TITLE-TEXT/

  • - are converted to spaces. -- to -, and _-_ to  - 

  • Each subsequent field is prefixed by a single letter path component followed by slash. These can be used in arbitrary order.

    • /d/DESCRIPTION-TEXT/
    • /i/BASE64_IMAGE_URL/
    • /f/BASE64_FAVICON_URL_OR_EMOJI/

  • This set must terminate with a slash

Custom data renderers

Itty bitty app supports custom renderers for structured data. Recipes and bookmarklets are special cased currently, but any renderer can be implemented by specifying a render attribute (render=https://script_url.js;) within the data URL.

Recipes

Recipes use a ld+json format, which is commonly found on many recipe sites - these can be extracted using the bookmarklet at https://bookmarklet.bitty.site

#/data:application/ld+json;base64,RECIPE_JSON

Bookmarklets

Javascript bookmarklets are displayed with basic instructions for how to add them to your browser : https://itty.bitty.app/#Show_Alert/javascript:alert('hello')

Clone this wiki locally