Gallery Workflow Style Guide

The Alfred Gallery strives for predictability between workflow READMEs so users have an easier time navigating and picking up new workflows. While exceptions are inevitable, this document covers how to remain consistent in common situations.

Note: Certain terms, such as Universal Action and Hotkey, become automatic links to Alfred's documentation when rendered in the Gallery.

Index

Introduction
Universal Actions
Screenshots
Modifiers
Alternative Invocations
Hotkeys
Workflow Configuration
Setup

Introduction

Start with ## Usage and one or two short sentences describing the main action on the workflow. Search is a great way to begin if the action involves any type of filtering through results.

End with via the `INPUT` keyword. Use keyword even if referring to a Script Filter, File Filter, or similar. Occasional use of with instead of via helps to mix it up.

Window Switcher Example

Markdown Source

    ## Usage
    
    Search app windows in the current Desktop Space via the `win` keyword.

Window Switcher intro example

Disk Usage Example

Markdown Source

    ## Usage
    
    See how much storage is being used by internal and external disks via the `storage` keyword.

Disk Usage intro example

Universal Actions

When describing a Universal Action, end with via the Universal Action. Use Universal Action even if referring to a File Action.

Share with AirDrop Example

Markdown Source

    ## Usage
    
    Send files, text, and URLs with AirDrop via the Universal Action.

Share with AirDrop Universal Action example

HEIC to JPEG Example

Markdown Source

    ## Usage
    
    Convert HEIC images to JPEG via the Universal Action.

HEIC to JPEG Universal Action example

Screenshots

Continue with an image directly illustrating the text. See Taking Good Screenshots.

Use standard markdown syntax for images: ![ALT TEXT](images/SOMETHING.png).

Mount Disks Example

Markdown Source

    ## Usage
    
    Mount disk partitions via the `mount` keyword.
    
    ![Showing disk partitions to mount](images/mount.png)

Mount Disks screenshot example

Send to Current Folder Example

Markdown Source

    ## Usage
    
    Move or copy files to the frontmost Finder window via the Universal Actions.
    
    ![Universal actions to move and copy](images/ua.png)

Send to Current Folder screenshot example

Modifiers

List modifiers below the image in a list of the format * KEYS ACTION. Use ↩︎⌘⌥⌃⇧ for the keys, surrounding each character in the <kbd> HTML tag.

For previewing with Quick Look, use * <kbd>⌘</kbd><kbd>Y</kbd> Quick Look SOMETHING.

Notes Example

Markdown Source

    ![Searching notes](images/search.png)
    
    * <kbd>↩</kbd> Open note in the Notes app.
    * <kbd>⌃</kbd><kbd>↩</kbd> Delete note.
    * <kbd>⌘</kbd><kbd>⌥</kbd><kbd>⌃</kbd><kbd>↩</kbd> Force cache flush.

Notes modifers example

Alfred Gallery Example

Markdown Source

    ![Searching for alfredapp workflows](images/gallery.png)
    
    * <kbd>↩</kbd> Open Gallery page in default browser.
    * <kbd>⌃</kbd> Show tags.
    * <kbd>⌘</kbd><kbd>↩</kbd> Install workflow.
    * <kbd>⌥</kbd><kbd>↩</kbd> Narrow search to creator’s name.
    * <kbd>⌘</kbd><kbd>Y</kbd> Quick Look workflow’s Gallery page.

Alfred gallery modifers example

Alternative Invocations

If there is both a keyword and Universal Action for the same task, use Alternatively, and another screenshot.

Ignore in Alfred Example

Markdown Source

    Alternatively, search for files and folders via the `ignore`, `unignore`, and `reignore` keywords.
    
    ![Alfred search for ignore](images/ignore.png)

Ignore in Alfred alternatively example

Thumbnail Navigation Example

Markdown Source

    Alternatively, begin navigation in a folder via the Universal Action.
    
    ![Navigate with Universal Action](images/navua.png)

Thumbnail Navigation alternatively example

Hotkeys

Mention Hotkeys with Configure the Hotkey SOMETHING.

Banner be Gone Example

Markdown Source

    Configure the Hotkey for faster triggering.

Banner be Gone Hotkey example

Unit Converter Example

Markdown Source

    Configure the Hotkey or use the Universal Action as shortcuts to convert results from Alfred’s Calculator, Clipboard History, or selected text.

Unit Converter Hotkey example

Workflow Configuration

Configuration should be explained in the workflow itself, but it is OK to mention the occasional relevant option users might otherwise miss. Describe it with Workflow’s Configuration.

Network Quality Example

Markdown Source

    Analysis takes a few seconds to complete. Results are copied to the clipboard and displayed in the viewer defined in the Workflow’s Configuration.

Network Quality workflow configuration example

Backup Preferences Example

Markdown Source

    Generate a backup of your local Alfred Preferences via the `start backup` keyword. A macOS launchd agent will be loaded to do it daily at the time set in the Workflow’s Configuration (using the [24-hour clock format](https://en.wikipedia.org/wiki/24-hour_clock)). The number of versions to keep is likewise configurable.

Backup Preferences workflow configuration example

Setup

Add ## Setup above the Usage section if extra manual steps are required before using the workflow. Leave out required Configuration items because Alfred itself warns of those. Leave out installing apps, Homebrew formulae, or setting API keys because the Gallery mentions those in a separate section.

Pause Tabs Example

Markdown Source

    ## Setup
    
    Turn on `Allow JavaScript from Apple Events` in the browsers you want to control. The exact location of the option depends on the browser.

Pause Tabs setup example

1Password Example

Markdown Source

    ## Setup
    
    [Install the 1Password CLI](https://1password.com/downloads/command-line/) and turn on the integration in 1Password Preferences → Developer → Connect with 1Password CLI.
    
    ![1Password preferences](images/1password_preferences.png)

1Password setup example