Welcome to the lab.

Web Excursions for August 21, 2017

[Tweet : nvALT]

Web excursions brought to you by CleanMyMac 3, all the tools to speed up your Mac, in one app.

Sketch for Designrs
Not a huge repository, yet, but another resource site to add to your Sketch bookmarks collection.
I love Sketch plugins to the extent that a plugin manager is a necessity. Sketch Toolbox hasn’t been updated for a while, and this new one is pretty sweet.
Ok, so there’s not been any shortage of email clients in recent years, nor am I interested in replacing MailMate or Spark. I do try everything out, though, and this one looks great. Currently just in advance signup mode, but if you’re curious, get your name on the list.
I’m not switching away from Pinboard, but I am impressed with this as a bookmarking/read later tool. Imports from Pocket, Readability, and Instapaper so you can try it out easily.
I really like the way Spotify analyzes my playlist data. Just the facts, but with some interesting notes. I am apparently high energy, with 79% of my played tracks categorizing as “energetic,” and zero “chill” tracks in my playlists. And I’m only drinking one cup of coffee in the morning these days…

CleanMyMac 2

seconds: CLI for quick time interval calculation

[Tweet : nvALT]

Here’s a quick script I swear I’ve written before but couldn’t find. If given a string as an argument, it converts it to seconds, and if given just a series of numbers, it converts the number to a human-readable string.

I needed this today when setting update intervals for Sparkle, and it’s something I’ve run into in the past. I usually pull up a calculator, which is annoying. There’s probably a simple Unix way to do it that I’ll hear about in the comments, which is ok, I still had fun writing it.

Since this is mostly likely to be of use to programmers, I won’t bother detailing how to turn it into an executable script. You got this.

Convert strings to seconds

Arguments are numbers followed by a timespan. It works on shorthand (w = week, day = d, hours = h, minutes = m, seconds = s), but will convert most strings to this format automatically, e.g. “2 days, 3 hours, and 30 min” is the same as “2d3h”. As long as the format is a number followed by strings that start with w, d, h, m, or s, it’ll figure it out.

$ seconds 3d2h
=> 266400
$ seconds 2 days, and 3 hours
=> 183600

Convert seconds to a human-readable string

$ seconds 266400
=> 3 days, 2 hours

Here’s the script. Do with it what you will.

styleStealer: add your web design to Marked with a click

[Tweet : nvALT]

Creating custom styles for Marked 2 is pretty easy… if you know CSS. I’ve started work on building an actual templating system, but it hasn’t come to fruition yet. In the meantime, I present styleStealer, a bookmarklet to make grabbing a site’s design and applying it to your Markdown preview in Marked a simple process.

To use it, just drag the bookmarklet below to your bookmarks/favorites bar (tested in Safari and Chrome).


When you’re on a page that contains a section of content you want to match the style of (usually a blog post or article):

  1. Click the bookmark.
  2. When a blue bar appears across the top of the page, you’ll be in inspection mode. Hovering over elements will outline the closest container elements, and show their selector at the top of the screen.
  3. Click a container that holds the entire article but not any sidebars or excess cruft.
  4. Watch a stylesheet magically appear.
  5. Click the text once to select all, then copy and paste into a text file. Save as “[site name].css”.
  6. In Marked > Preferences > Style, click the plus sign under the custom style list and locate your new css file.
  7. Make sure you’ve selected the new style in the style picker on a preview window to check it out!

It’s not 100% perfect on all sites as there are a lot of variables to deal with when trying to detect and replicate styling using JavaScript alone. But in my testing it’s been pretty awesome.

YouTube Video

A few notes, mostly for my own documentation:

  • Recent security changes in WebKit make it difficult to parse styles via JavaScript on most pages. styleStealer uses XHR requests to reload cross-domain stylesheets.
  • The script uses computed rules for most styles, parsing stylesheets mostly for imports/webfonts.
  • When a container is chosen, it injects standard elements into the selected container and then reads their applied styles.
  • It reads only style rules relevant to display in Marked, creating a relatively simple stylesheet.
  • Output is specifically formatted to be a stylesheet in Marked, meaning:
    • Selectors are previxed with Marked’s #wrapper container ID for specificity
    • Standard comment header is added to the top

    The #wrapper prefix is added when the styleStealer.steal() function is called, and is easily removed. All extra text is contained in heredocs in the script and is easily editable.

Come up with a great one that would be useful to others? Feel free to add it here or contact me with it.

Automatic release notes from Git commit messages

[Tweet : nvALT]

I thought I’d share the script I’m using to generate changelogs for Marked releases using git commit messages. A lot of it is tailored to my own setup, and would require some customization to make it work with a different workflow. Also, it’s messy code, for which I apologize. Ultimately it should have just been a procedural script, but I started to go somewhere else with it before I realized that wasn’t what I was getting paid for.

Anyway, when I’m working on Marked, I use keywords in my git commits to specify things I want to appear in the release notes later. For a long time I would just output a pretty-formatted log and then use one-off scripts and Sublime Text to generate my release notes. This script is my current method of automating it.

Workflow specifics

ChangeLogger uses git rev-list --tags --max-count=1 to find the commit hash for the last tag, which in my workflow (git-flow) are only created for releases. Thus the commit hash of the last tag is where the next changelog begins.

Lines in commit messages can have one of three keywords at the beginning, anything without a keyword is not included in the changelog. The keywords are “NEW”, “FIXED”, and “IMPROVED”. The script also accepts “FIX” and “IMPROVEMENT”, and these can have hyphens before (as Markdown lists) and colons after, but that’s all stripped either way.

The header for the changes gets the app name and version information. These are pulled from Xcode Info.plist files and agvtool.

It outputs formatted in the way my documentation generator needs for creating the release notes pages. That’s currently hardcoded, but probably easy to modify as needed.

Example commits

Here are a few commits from the next version of Marked

Thu Jul 6 10:53:41 2017 -0500 4a4db1bb Allow disabling code wrap, fix empty lang class  [Brett Terpstra]
   - NEW: Option to disable wrapping inside of code blocks, forcing scroll (Preferences->Style->"Allow themes to wrap text inside code blocks")
- FIXED: If a language on a code block isn't specified, Marked inserts "class=(null)"

Wed Jul 5 15:09:12 2017 -0500 68a90c57 Leanpub aside styling, fullscreen toc  [Brett Terpstra]
   - IMPROVED: {icon=[fontawesome name]} before a leanpub aside works now
- NEW: Full screen mode for table of contents, fixed to left (automatic when switching to full screen, can be manually enabled from button on TOC popup)

Tue Jul 4 15:25:06 2017 -0500 fe20f115 Fix CriticMarkup export  [Brett Terpstra]
   - FIXED: Setting criticmarkup type (markup, original, edited) in non-PDF export has no effect
- IMPROVED: {icon=[fontawesome name]} before a leanpub aside works now

When the script runs on this repository, it outputs:

Marked 2.5.11 (933)

#### NEW

- Option to disable wrapping inside of code blocks, forcing scroll (Preferences->Style->"Allow themes to wrap text inside code blocks")
- Full screen mode for table of contents, fixed to left (automatic when switching to full screen, can be manually enabled from button on TOC popup)


- {icon=[fontawesome name]} before a leanpub aside works now

#### FIXED

- If a language on a code block isn't specified, Marked inserts "class=(null)"
- Setting criticmarkup type (markup, original, edited) in non-PDF export has no effect

The script has no library dependencies, so it should be self-contained. The few config options it has are commented at the top.

If this sounds intriguing, and you’re feeling forgiving about a mess of pointless class structures, feel free to grab it.

Regarding punctuated tags

[Tweet : nvALT]

I’m at the CMD-D conference in Santa Clara this morning. I’m actually a couple hours early because my body is still on Central time. So I figured I’d take a minute and answer the most common question that I got after my last appearance on Mac Power Users.

I mentioned (kind of in passing) that you can nest tags using punctuation, in my case a colon. Here’s an example:


So in my system, there’s also a #Context tag, in this case it would be #Work. (Context tags are the only tags I capitalize, and I don’t know why, but I’m consistent.) My auto-filer would take the file with the above tag, find the freelance folder inside of my base Work folder, and then file it under jappleseed/scripting. The way my system works, if there was a folder tagged @script even deeper within the @jappleseed folder, it would file it there instead of creating the folder at the base. So that’s why I started using these punctuation-split tags. There are some additional benefits, though.

Spotlight breaks the tag up on the punctuation when searching. This means that I can still search for tag:script and find all of my script files, regardless of the preceding portion of the tag. But I can also search tag:jappleseed:script and create an automatic boolean AND search, as if I’d searched tag:jappleseed AND tag:script. The file will also show up for the search tag:freelance and tag:freelance:jappleseed.

It also makes autocomplete work more efficiently for you. Once you’ve tagged a file with any freelance:jappleseed subtag, it will show up in autocomplete for you after just typing “free,” letting you tag the file with all three tags at once.

When I’m using these grouped tags, I start the tag with a colon as well: :freelance:jappleseed:script. It doesn’t affect Spotlight’s ability to search in any way, but helps keep my nested tags together in the list. This system doesn’t help with tag pollution (having too many tags), but that helps keep the lists neater. You can also do searches like “NOT tag::*” to exclude any tags starting with a colon. That also works with other punctuation, so in my system I can get a list of all project folders in a given context with tag:#Work AND tag:@*.

So basically you’re creating nested groups that are children of a particular tag. You can then have a smart folder for all of the “jappleseed” client files, and use Spotlight within that folder to find various tags. You can even set Finder to group by tags in the list, so it creates an automatic visual “folder” hierarchy for each smart folder.

It’s not a necessary tool. You could always just use all of those tags separately and run “AND” searches to combine them. I like the shortcut, though, and in combination with tag autocompletion, it makes filing quite easy.

Marked 2 tips: Document navigation

[Tweet : nvALT]

Another in my irregularly-update series of Marked 2 tips and tricks. There are a lot of document navigation features in Marked, and many that have evolved since the last time I wrote about this. This particular tip is about Marked’s special tools for navigating long documents.

The table of contents

You may already know that while previewing a Markdown document, you can click the “hamburger” icon in the lower right of the preview window status bar to open up a table of contents. More my speed, you can also just hit ⌘T to toggle it. There are some tricks hidden in there…

The table of contents is generated automatically from headlines in the document. It won’t show up if there aren’t any headlines. But any number of ATX (#) or Setext (===/---) headlines will create a hierarchical navigation. It’s always best to nest these in order, with only one top level headline (H1), H2 as sections, and then H3 as chapters or subsections, etc.. That’s just good form in general, but it definitely makes navigation easier.

Keyboard nav

Much like the rest of Marked, when the TOC is open, you can use keyboard shortcuts to navigate it. j and k will navigate up and down, and return (or o) will open the highlighted header.

Pressing the Space bar will open up a filter field at the top of the TOC. It’s immediately focused, so you can just type Space and then start typing a search query. This is a fuzzy matching filter, so you can type any part of the headline, even with missing letters, and filter the list to show only matches. Once you see the one you’re looking for, hitting Tab or ctrl-n will jump back to the list so you can select the one you want.

By the way, you can type “?” in any preview window to show available keyboard commands.

You can also access the filter directly by hitting f when the TOC isn’t showing. This will pop up the TOC with the filter field focused, and it will hide again as soon as you open a selection.

Follow scroll

In Preferences under the Preview tab, you can enable “Table of contents tracks scroll position.” With this on, the current viewing area is highllighted in the table of contents, moving as you scroll. This also means that if your TOC is long enough to scroll, it will always be scrolled to the same area as your current position in the document.

Inserting a table of contents in the document

You can also manually include a copy of the table of contents in your document using the special syntax <!--TOC-->. You can also define a maximum level like this: <!--TOC max2-->. That would show only the first two levels of headlines in the inserted table of contents. The inserted TOC will also only pick up headlines after the point in the document where it’s placed, so if it comes after, say, a title page, headlines on that page won’t be included in the navigation.

Sadly, Marked is still suffering from the WebKit issue where intra-document links in exported PDFs don’t work, so the clickable TOC isn’t clickable in PDF format. Still working to remedy that one.

Collapsible sections

This isn’t really a Table of Contents feature, but it does relate: if you enable “Headlines collapse sections” in Preferences > Preview, headlines become clickable, collapsing all sections between them and the next headline at the same level (so clicking an H2 would collapse any H3s before the next H2). You can also check the box below the option to require the ⌘ (command) key, which is handy if you find yourself accidentally collapsing headlines. With that enabled, you have to hold down ⌘ when clicking in order to trigger the collapse.

A collapsed section is indicated by a yellow marker on the right of the headline.

You can use the keyboard shortcut ⌘⌥← to collapse all sections, and ⌘⌥→ to expand all. When they’re all collapsed, clicking a headline will uncollapse only that level, so sub-levels within it remain collapsed. Holding down ⌥ (option) when clicking will expand all sub-sections as well. (And same for the reverse, collapsing all subsections.)

In the Table of Contents, collapsed sections are shown as dimmed, but still searchable and selectable. Choosing one in the list will open just that section, allowing you to collapse all, then navigate to just the section you want to work with, even if it’s deeply nested.

Coming soon

The next update to Marked includes the ability to fix the table of contents to the left side. This happens automatically when you switch to full screen mode, but it can be toggled on and off manually at any time. More details to come!


Bookmarks are used when reviewing and working with long documents. They only last for the life of the session, and aren’t saved along with the document itself. You can set up to 9 of them in the document, and then quickly navigate just by typing the associated numbers.

Typing ⌥1 (Option-1) in your document will place the first bookmark at an offset based on the nearest headline. This means that the bookmark will still work even if the length or ordering of elements changes. You can also type ⇧1 to set a more literal, position-based bookmark, but I’d recommend always using the newer headline proximity system you get with the bookmarks.

Now you can just type the number 1 to jump to that bookmark. You can also navigate through bookmarks using n and p. n will go to the next bookmark in positioning order, p to the previous. Using Shift with them (N and P) will navigate them in numerical order.

Add additional bookmarks using ⌥2--9. Using and existing number elsewhere in the document will replace that bookmark position with the new one. Use xx (type “x” twice) to clear all bookmarks.

You can also navigate bookmarks with the mouse. Bookmarks will show on the right side of the preview. They’re positioned within the viewing area spaced relative to their position in the document. Hovering over them will reveal more information, and clicking the markers will jump to that spot.

The mini map

Typing 0 (the number zero) will expand the bookmarks. If you’ve enabled “Mini Map navigation” in Preferences > Preview, it will also open the minimap. Note that the map is only created on documents that are at least 3 pages long at the current viewing width. The map is an image of the entire document, at the proportions created by the current preview window size. It slides out from the right, offering an overview of your document on one screen. Click anywhere on the mini map to jump to that point in the document. If you hold down ⌘ while hovering, it will magnify the area under the cursor, and holding down will “scrub” the document, moving the scroll position relative to the mouse as you move over the map.

The mini map can have trouble on very large documents, which is a bummer because that’s when it’s the handiest. I’m working out a few issues on that.

Other tools

I should also mention Autoscroll, and handy feature for those who are reviewing and performing editorial tasks on documents, or using Marked for reading long-form texts. You can find more information on Autoscroll in the documentation, but the short version is: just type s to start scrolling, and use ⇧←/→ to speed up and slow down. Escape will end autoscrolling.

If all of this sounds titillating and you’re not a Marked user, go grab a copy. The next big update is right around the corner!

Talking tags with David and Katie

[Tweet : nvALT]

I had the pleasure once again of joining David Sparks and Katie Floyd on Mac Power Users episode 390. While we’ve discussed tagging (probably every time I’ve ever been on the show), it’s been years since we dove deeper into the subject.

Things have changed since we all talked back on episode 45. The Files app in iOS 11 has started syncing tags, and that alone is a huge burst of hope for those of us whose primary sticking point was the uselessness of all our tagging efforts once we started doing more on our iPads.

We discussed more about the the state of tagging on Mac and iOS, past, present, and future. We also dug into the “why,” the “how,” and a bit of the “how not” (i.e. mistakes to avoid when developing a tag taxonomy for yourself).

Check out the episode on Relay.fm!