MultiMarkdown Composer v4 Expansions

Background

MultiMarkdown Composer v4 (Pro) supports user-customizable text expansion of defined keywords. This is similar to TextExpander, but nowhere near as powerful. The goal is not to replace Text Expander for those who use it, but to provide a lightweight alternative for those who don't. It will also be easier to provide a consistent writing environment across devices by using a built-in approach. The text expansions are controlled using JSON configuration files:

{
    "expansions" : [
        {
            "key" : "ftp",
            "expansion" : "Fletcher T. Penney"
        }
    ]
}

If you update your expansions file while Composer is running, you will have to reopen your document for the changes to take effect.

Date/Time

MultiMarkdown Composer supports standard strftime() format specifiers. A full list is available here.

For example, the following would insert August 20, 2017

{
    "expansions" : [
        {
            "key" : ".date",
            "expansion" : "%B %e, %Y"
        }
    ]
}

Jump Points

There are often certain points in an expansion where you know that you will need to type something. For example, if you wanted to insert a link, you anticipate wanting to type in the brackets and in the parentheses. The %| token allows you to do that. Whether in text expansion or not, when hitting the Tab key in Composer and there is a %| somewhere in the text, the cursor will jump to that point. The following expansion would start the cursor inside the brackets, and once you're done typing the text of the link, hitting Tab again will take you to the parentheses:

{
    "expansions" : [
        {
            "key" : ".l",
            "expansion" : "[%|](%|)"
        }
    ]
}

Clipboard Insertion

It is sometimes useful to be able to use copied text in your expansion. The %clipboard token allows you to do that (and is compatible with the same functionality in TextExpander).

{
    "expansions" : [
        {
            "key" : ".l",
            "expansion" : "[%|](%clipboard)"
        }
    ]
}

Replaced Selection

If desired, you can set up text expansion to work on selected text. For example, you select text and then type .lr to trigger a link:

{
    "key" : ".lr",
    "expansion" : "[%replaced](%clipboard)%|"
},

This would wrap the selected text in brackets as the link text, and then use the clipboard to paste the URL inside parentheses.

This can allow you to create some fairly complex shortcuts.

Recursive Expansion

Additionally, the expansions can reference other expansions that you have configured. This allows you to define something once, and use it in several different ways without repeating yourself. For example, you can define an email address, and then include it in multiple different templates. Then, when your email address changes in the future, you only have to change it once.

In order to make it easier to convert expansions you may have defined already in TextExpander, the syntax is the same as the one used there:

{
    "expansions" : [
        {
            "key" : ".email",
            "expansion" : "foo@example.com"
        },
        {
            "key" : ".contact",
            "expansion" : "Feel free to email me at <%snippet:.email%>"
        }
    ]
}

Where Do I Install My Files?

Expansion files belong in ~/Users//Library/Containers/com.multimarkdown.composer4.mac/Data/Library/Application Support/MultiMarkdown Composer 4/Expansions.

That's rather long to remember, so instead there is a button to open the folder for you in the Preferences under the Pro tab.

Troubleshooting

If you create an invalid expansions definition file, Composer will silently fail to load it rather than crash. Once you edit the file, be sure to close your document window and then open it again to load the new expansions. If it isn't working, then one step is to ensure that your JSON is valid. This website will ensure that the JSON is valid -- however it does not ensure that it properly defines a Composer expansion file.

Note

Again, this feature can be useful, and will be more useful when expansions can be shared between macOS and iOS (no timeline on that though). If you really want more powerful text expansion, then TextExpander is a great utility from a great group of people. It has more complex and powerful features, and many satisfied users. Choose whichever tool you want, or use a combination of both.