Welcome to the lab.

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).

styleStealer

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)

#### IMPROVED

- {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:

:freelance:jappleseed:script

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

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!

Quantify everything with Exist.io custom tracking

[Tweet : nvALT]

Ever since I wrote Slogger, I’ve been working toward a more “quantified self.” I’m really bad at correlating events in my life beyond a couple of days. Did the bad night’s sleep last week lead to eating things the next day I normally wouldn’t, which led to increased stress and decreased physical activity over following days, which resulted in the way I’m feeling today? Now that I’m actually healthy enough to notice these things, I really want to know.

I want all of that data, but I’m not great at recording it in the moment, and often forget things by my end-of-day check-in. That’s where apps like Exist.io have come in. Much like Slogger, they pull together all of the data sources that my Apple watch, iPhone, social media accounts, and even Last.fm and Spotify accounts create, automatically combining it to start drawing correlations. These are often humorous and obvious, but the more sources you add and the more data you record, the more interesting (and useful) things get.

A while ago they added Apple Health data, so my circles, my steps, and even my sleep are all recorded. You can also add Gmail and see how many messages you send and receive each day, and Calendar data to see how busy your day was (at least with planned activities). All great data.

What’s been missing, though, is the ability to record very fine-grained personal data. I’ve long planned an app that was essentially a database, with tiered levels where you could create nested checklists for common and uncommon things that happen in your life. Start a new medication? Check it off. Find yourself unusually uncoordinated? Check it off. Gathering that data easily and in a manner that’s simpler to statistically analyze is something I haven’t found a great solution for.

Well, Exist just added Custom Tracking, which allows you to create tags for any possible event, food/drink, medication, or even feeling. I can track what medications I take, what kind of exercise I got, whether I have a headache, and whether I felt productive or lackluster (or any other feeling I want to add). And all of those tags eventually build correlations with each other and all of the other automatically-collected data in Exist.

It’s not exactly what I planned for this app in my head, particularly because I can’t easily quantify each tag. I can add “coffee,” but if I want to mention more than one coffee, I have to add new tags for “2 coffees,” “3 coffees,” etc., but the implementation is simple enough that it’s going to be easier to keep up with than my plan.

I’m excited about this. I’ll finally be drawing statistical correlations that go beyond my steps and my music, how many times I tweeted, and how I rated my overall mood (although the correlations between those have been intriguing). If you haven’t checked it out, head over to Exist.io and create an account, then grab the iOS or Android app and start gathering that data.

As an aside, I also like aspects of Momento, and I love trying out apps. If you have a favorite I should check out, let me know in the comments.

Long-form writing with Marked 2, plus 2.5.11 teaser!

[Tweet : nvALT]

The next update to Marked 2 (2.5.11) is almost ready. It’s a free update, and should be ready in the next week (maybe two). If you’re not already a user, you can grab a free trial, and if you choose to buy now (and support development of this and BitWriter), these new features will be handed to you automatically when testing is finished.

As a tangential aside, things are a bit tight for me right now as I work on multiple unfinished (and thus far unpaid) projects. If you feel like offering a show of support for upcoming projects, feel free to donate or pledge continuing support with a subscription!

Because I’ve made a lot of low-level changes to improve efficiency in this release, I’d be glad to have some beta testers. If you’re interested, please contact me and I’ll hook you up.

In the meantime, here’s a quick teaser of a few new features.

Tease me

IA Writer includes
Marked has always done its best to normalize between various flavors of Markdown and special syntax. It has its own format for handling file transclusion, and supports mmd_merge, Leanpub, MultiMarkdown transclude syntax, and GitBook index files. The next version adds support for IA Writer file include syntax (/filename), and handles detecting and properly formatting for the type of file included, such as text, image, csv…
CSV tables!
Admittedly I cribbed this feature from IA Writer as I worked to support their syntax. I love it, though. If an included file is a CSV (or TSV), Marked will automatically turn it into a table in the output. Obviously this isn’t going to work with overly complex spreadsheets, but anything that should reasonably turn into a table does.

The new Tufte style!

Tufte!
A new style called Ink that’s replacing Antique. It’s based on Edward Tufte’s work (and Dave Liepmann’s CSS), and looks pretty great. The original Antique will remain available in the MarkedCustomStyles repository.

Fullscreen TOC
When switching to Full Screen mode with a preview window, the table of contents becomes a left sidebar, fixed in place unless explicitly hidden with ⌘T. Fullscreen and popup modes can be toggled in both Full Screen and windowed previews.

Teach me

The documentation in the 2.5.11 has received a lot of love. Because Marked’s feature set has grown to include a vast number of writing tools, I want to highlight a few existing features here.

Writing a book

You can use Marked to compile large documents from separate files in a few ways (full documentation).

  1. Marked’s include syntax

    You can add external documents in an index file or include them anywhere in the text. These can be nested, so included files can include more files. It can also be used to add code examples and raw HTML from external files.

  2. MultiMarkdown transclude syntax

    You can also use syntax based on the newer MultiMarkdown spec. Marked will recognize Transclude Base: path in MMD metadata and use it as the base for file transclusion.

  3. Leanpub index files

    Leanpub’s format is a simple Book.txt file that lists the chapter files in publication order. It’s handled the same way as mmd_merge files (which also work in Marked). You can use this even if you’re not publishing via Leanpub. Just enable Leanpub processing under Preferences->Apps.

  4. GitBook index files

    These use a more Markdown-style list/link format in a SUMMARY.md file.

  5. Scrivener and Ulysses

    Entire documents written in Scrivener can be previewed simply by dragging the .scriv file to Marked. Any documents in the Drafts folder will be rendered in order. Here’s the documentation for that. Ulysses sheets can be selected and previewed as a collated document using Ulysses’ quick preview (⌘6). Set the format to Text->Textbundle and choose Marked 2 as the target application. Then you can just hit ⌘6, Return to see the results. Note that files in “External Folders” can be viewed directly with automatic update on save.

Multi-file document features

When previewing files built from indexes or with includes in them, Marked 2 has features to make working with them easier.

  1. Edit included file

    Marked knows which file the section you’re currently viewing is associated with. While “Open in External Editor” will open the main index or parent file, pressing ⇧I will display the currently-visible included file. Pressing Return while the filename popup is displayed will open that file in your editor.

  2. Include chart

    Marked can show you a color-coded sidebar displaying where included files start and end, including nested includes. In the Gear menu at the bottom right you can choose “Show Boundaries of Included Files” to turn this on. You can also just hit ⌃⌘B to toggle it on and off. Hovering your mouse over the sidebar will show what file the current section comes from, and clicking it will open that file in your editor.

Both of these features mean you can preview your entire book, taking advantage of Marked’s extensive analysis and proofreading tools, and easily jump to editing a specific chapter or section when you find a change is needed.

I’ll try to post tips like these (and update the screencasts) a little more frequently, though between maintaining and improving Marked and trying to finish BitWriter, time for blogging is shorter…