Exploring GitHub Flavored Markdown local preview

I’ve been writing various lengthy documents for GitHub repositories recently, and as I push them to GitHub, and then view them in the browser, there’s almost always something wrong with the layout resulting in additional commits or amends/forced updates which I would rather avoid. I was initially using MacDown to edit/preview Markdown, but its rendering of GitHub Flavored Markdown (GFM) was way off. There had a to be a better way, and there is! I found two solutions that work reasonably well: the first one is Node-based vmd for general use (it watches the given file, and thus works with any editor), and the second is a set of plugins for Sublime Text 3. The former is now my choice for offline GFM previewing (such as on a plane), while the latter is my preferred choice because 1) Sublime Text 3 is already my go-to editor, 2) the Sublime Text plugins provide incredibly handy macros for, and context-highlighting of the Markdown being edited and, most importantly 3) the GFM is rendered through the GitHub API, ensuring that the rendered output matches the way GitHub renders it 100%. Both `vmd` and the Sublime Text solution work on macOS, Windows, and Linux Desktop.

Some other options that I looked at included Grip (a cool idea, but it kept crashing on me), or Atom‘s GFM preview (which, even with the right extensions installed, wasn’t accurately GFM, which is strange considering that Atom is made by GitHub; if you know how to make Atom render GFM through the GitHub API, please comment this article).

First, `vmd`. It’s easy to set up, simply first install Node.js on your platform, then add `vmd` with `npm` as a global:

npm install -g vmd

Now simply point `vmd` to the file you’re editing, and it gets re-rendered every time the file is saved as long as `vmd` is running.

vmd SomeFileName

That’s all. You can use any editor to edit the file.

However, if you’re using Sublime Text 3, give the following a try; it makes Markdown editing outright fun. The following instructions are for ST3.

  1. Install Sublime package manager if it’s not yet installed. Then restart Sublime.
  2. Install the following packages with the Package Manager:
    `Ctrl-Shift-p [Win] / Cmd-Shift-p [macOS] > Package Control: Install Package`

    Restart Sublime.

  3. Install monokaiC theme (read the installation instructions on its GitHub page).The target location depends on the platform, see this StackOverflow answer for details, but use the User subdir under the directory listed for your platform.
  4. SETTINGS

    1. In Markdown Preview User Settings:
      `Preferences > Package Settings > Markdown Preview > Settings — User`

      Add:

      {
         "git_oauth_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
         "github_mode": "gfm",
         "enable_autoreload": true
      }

      ** Get the `git_oauth_token` from GitHub. Log in to your GitHub account, then:
      `Settings > Developer Settings > Personal Access Tokens`, or use generatetoken.sh script. No scope permissions are required for a token for it to be valid for Markdown rendering. Note that without a token set you’re limited to about 60 renders per hour, while with the token set you can make 5000 requests per hour (which you’ll never hit, since the re-render only occurs on file save).

      ** Make sure you have a comma at the end of each line, except the last parameter line in the settings

    2. In Markdown Editing User Settings for GFM:
      `Preferences > Package Settings > Markdown Editing > Markdown GFM Settings — User`

      Add:

      {
        "color_scheme": "Packages/User/ME-MonokaiC.tmTheme",
        "extensions":
        [
          "md"
        ]
      }
    3. In Key bindings
      `Preferences > Key Bindings — User`

      Add:

      { "keys": ["alt+l"], "command": "markdown_preview", "args": {"target": "browser", "parser":"markdown"} },
      { "keys": ["alt+m"], "command": "markdown_preview", "args": {"target": "browser", "parser":"github"} }
      

    Restart Sublime.

  5. Enable Simple Reload:
    `Ctrl-Shift-p [Win] / Cmd-Shift-p [macOS] > Live Reload: Enable/Disable Plugins > Enable Simple Reload` You need to reactivate Simple Reload like this whenever you restart Sublime, and want to use the auto-reload.

All set! Open an existing markdown (.md) file, or start a new file and save it with `.md` extension. Then hit `alt-m` for GitHub-rendered preview, or `alt-l` for locally rendered (but less accurate for GFM) Markdown preview. When you make changes and save the file, the preview gets automatically refreshed in your browser using the originally selected method (i.e. GitHub API or local).

Be sure to read the MarkdownEditing documentation for awesomely useful keyboard macros and other support for Markdown! This will also give you syntax highlighting in fenced code blocks when you postfix the first triple-backtick with supported language identifier, like so:

```sql

Happy GitHub Markdown editing! Octocat

Update 2018-03-02: The `git_oauth_token` must be set in Markdown Editing package settings, not in global Sublime settings. This correction has been reflected in the above instructions.

Workflow magic (or so it seems :-)

A few days ago I came across the solution to a workflow issue I had been for long wishing could be done. Today I solved another one, and since they’re connected, I outline them below. Maybe they’ll make someone’s day! 🙂

I often work with remote servers that are almost always some flavor of Linux, most frequently Ubuntu/Debian, but also CentOS/Redhat. Despite of being a lifelong geek, I really dislike `vi`, finding it massively unintuitive. Maybe I haven’t figured out its intricacies, but I doubt it – it just doesn’t jive with me. In the 90’s I remembered most of Emacs’ chords by heart (or more likely by muscle memory), and really enjoyed using it, but for some reason I eventually stopped using it and only now am picking it up again. For now, however, my go-to editor in Linux is `joe`, which is handy enough (more so than `pico` or `nano`), but none of them still are as comfortable and flexible to use than a good GUI editor. In Windows & macOS my editor of choice is Sublime Text 3, and a few days ago I came across this answer in StackOverflow. Enter rmate/rsub! To make the magic happen, first install a small `rmate` script on your server (but call it `rsub` since you’re using Sublime Text rather than TextMate):

sudo curl -L --output /usr/local/bin/rsub https://raw.github.com/aurora/rmate/master/rmate
sudo chmod +x /usr/local/bin/rsub

Or perhaps like this (requires `git`, but makes it easier to keep rmate/rsub up-to-date by executing `git pull` in the cloned directory):

cd /opt
git clone https://github.com/aurora/rmate.git
ln -s /opt/rmate/rmate /usr/local/bin/rsub

Then add a few lines in `~/.ssh/config` on your Mac (Windows users, keep reading, you haven’t been forgotten):

Host *
  RemoteForward 52698 127.0.0.1:52698
  UseKeyChain no

To exclude some domains where you’ll never use `rsub`, like GitHub:

Host github.com
  Hostname github.com
  User myUserName
  ForwardAgent no
  ClearAllForwardings yes
  IdentityFile ~/.ssh/myGitHubKey

(the significant line above is `ClearAllForwardings yes`)

Then install `rsub` package in Sublime (easiest done with Package Control), and now `rsub someFileName` command on the remote opens `someFileName` in Sublime on Mac! Like magic!! No need to mess with FTPS. Just one word of caution.. if you put the Mac to sleep, the “rsubbed” file may become disconnected from the remote, so when you make the first save after resuming work, verify that the changes are indeed saved, or close the file and reopen it from the remote.

`rsub` also works with Sublime Text in Windows. The only part of the above setup that differs on Windows is the SSH config since Microsoft’s effort to create a native OpenSSH port for Windows is slow going (“non-production ready pre-release v0.0.17.0” with 161 open issues as of writing of this post). I usually use the excellent commercial SSH client VanDyke’s SecureCRT as the SSH terminal in Windows. I initially thought reverse port forwarding would not be possible in it, but alas, I stand corrected! Van Dyke’s always helpful and knowledgeable technical support pointed out how to achieve the desired port forwarding in it (the config section in question was titled: “Port Forwarding – Remote/X11”, and that indeed meant “remote OR X11”, not “remote X11”, as I had read it. So regardless of whether you use PuTTY (or its derivatives like KiTTY) or SecureCRT, you setting up the port forwarding is a snap. I’ll outline below PuTTY’s setup first, then SecureCRT’s equivalent configuration.

Install and fire up PuTTY. Just to make sure you start from a clean slate, click on “Default Settings” and then “Load”:

putty-1-load-defaults

Set the name (or IP) of the server you’ll be running `rsub` from:

putty-2-set-server-name

If you’re not using PuTTY’s key agent Pageant to authenticate, enter the path for your private RSA key. Note that it must be in `PPK` format (if you have PEM format key, you need to convert it with PuTTYgen, another PuTTY utility program):

putty-3-set-key

Add the remote listener port:

putty-4-add-remote-listener-port

[OPTIONAL] If you’re NOT using this PuTTY session for the shell (i.e. if you’re using for that purpose some another program that lacks the reverse forwarding capability), disable the shell for this connection:

putty-5-do-not-start-shell

[OPTIONAL] Similarly, if you’re not using this PuTTY session for the shell, set the window size to a small value:

putty-6-set-window-size

Finally, back in the Session tab, save the session: give it a name, then click on “Save”. If this is a shell-less RSUB session only, give a descriptive name:

putty-7-save-session

Now you have configured a RSUB session in PuTTY. For convenience, you may want to create a desktop link to activate the [RSUB] session. If so, right click on the desktop and select “New > Shortcut”, then enter the path to `putty.exe`, followed by `-load`, and the name you gave the session in PuTTY:

putty-8-create-shortcut

Finally, give a descriptive name for the desktop link:

putty-9-name-shortcut

And now you have a link that opens the RSUB channel to your remote server:

putty-10-link-image

Click on it, and it opens a small session window. As long as you keep it open, you can use the `rsub` command on the remote to open and edit remote files on your local Sublime Text!

And now, the same for SecureCRT:

Once you have configured a profile otherwise (set the hostname, username, and authentication information – [preferably] either a PEM format key, or a password [if allowed by your server]), head to Connection > Port Forwarding > Remote/X11, like so:

rsub-scrt-1-add-remote-port-forwarding

Click on “Add”, and enter a name for this tunnel, such as “RSUB” here, and the port 52698. When you enter it in the “Remote > Port” field, the “Local > Port” is automatically filled out for you:

rsub-scrt-2-add-remote-port-forwarding

And now you have the `rsub` port forwarding in place in SecureCRT!

rsub-scrt-3-remote-port-forwarding-added

Now when you open the session, you automatically have a `rsub` port open as well, and once you open Sublime Text on Windows, you can proceed to type `rsub someFileName` on the server, and it opens in Sublime.

So far so good (remote editing is working great!). Today I needed to diff an old configuration file against the new one, and the CLI `diff` output was too tedious to decipher. Then it occurred to me that maybe it would be possible to somehow use my favorite GUI diff utility, Beyond Compare with Sublime — and it is! The only thing to note is that when you open Beyond Compare from the files open in Sublime, you’ll need to save the completed diff first in Beyond Compare, and then in Sublime. Note that the file change indicator doesn’t light up in Sublime even when it has received the changes resulting from the diff reconciliation in Beyond Compare. The changes are received in Sublime when you save them in Beyond Compare, but not saved from Sublime [to the server over `rsub`] until you explicitly hit save in Sublime.

Now.. the files opened in Sublime from a remote using `rsub` can be diffed by this method with Beyond Compare! Working with remote files just became a lot more fun! 🙂

Update 2017-11-07: The article was updated with the latest `rsub` installation details, and PuTTY configuration instructions were added.

Update 2017-11-09: Van Dyke’s technical support pointed out to me that the reverse port forwarding can be accomplished in SecureCRT as well, so I corrected the article, and added the configuration details for SecureCRT.

Update 2017-11-24: I just noticed you can open two files from two different servers (using `rsub`), or one file from a server, and one file locally, and then compare them with Beyond Compare as described above. So cool!

Update 2018-01-17: Note that if you have a connection open from multiple machines, the first one that reverse-forwards the port `52698` receives the file when you run `rsub someFileName` on the remote. This can be confusing if you work on same remotes from multiple systems, so if you so choose, you can map a different port from different laptops/desktops, like so:

laptop – `RemoteForward 52698 127.0.0.1:52698`
desktop – `RemoteForward 52699 127.0.0.1:52698`

(NOTE: The first port value is the forwarded remote port; the second value is the local port which always remains at `52698` as it corresponds to the Sublime’s rsub extension port set in Sublime > Preferences > Package Settings > rsub > port)

Then on the remote system set up couple of aliases, respectively (here we assume the `rmate` repo was cloned in `/opt/rmate` rather than downloaded with `curl`):

alias rsubl='/opt/rmate/rmate --port 52698'
alias rsubd='/opt/rmate/rmate --port 52699'

If you set up multiple `rsub` alternatives like this, you may not want to copy/symlink the `rmate` executable to `/usr/local/bin/rsub` as that way you have to use the the port-specific aliased commands instead.

Visio 2013 Connector Text Block Background Color

I recently switched from Visio 2010 to Visio 2013, and while I quite enjoy the fluidity of 2013’s UI, some of the changes have had me run in circles before finding the 2013 equivalent for 2010 features I already knew. Here’s one of them:

Working on a diagram of our DNS server setup I wanted to adjust the background color of the connector text block. There are many good tutorials on the web on how to accomplish the same in Visio 2010… but in Visio 2013 the “Format” context menu option is gone, and there’s “Format Shape” which opens the Format Shape sidebar which has no options to adjust the text block’s background color.

A text block with the default white background.
A text block with the default white background.

Finally after clicking around for some time I found the new hiding place of the Text Block options. Here’s how:

First left click on the connector to select it; the green and yellow selector indicators show up:

visio_connector_selected

Then click on the little symbol in the lower right corner of Home > Font, or Home > Paragraph area in the ribbon bar. This opens up the text dialog (with ‘Font’ or ‘Paragraph’ tab selected, depending on which area you clicked). Select the “Text Block” tab, and you’ll see “Text background” options:

visio_text_dialog

Now the earlier tutorials I mentioned apply. If you select “None” for the background, or set its Transparency to 100%, you’ll get an undesirable effect:

visio_transparent_textblock

The better option is to use some color picker tool like Nattyware’s free pixie (or one of many other alternatives) to sample the color surrounding the text block and then set the Solid color value to match (with Transparency set to 0%). Or, if you use standard colors in your diagram, select the same standard color for the text block background. Now it looks a lot better:

The little arrow symbols in the lower right corners of various Ribbon areas are good to get to know — lots of options hide behind them! For example, the arrow symbols in Design > Page Setup, or View > Visual Aids open dialogs to many everyday workflow options that are frequently needed.

Finally, couple of other Visio tips. A blog post Work Faster With Our Visio Keyboard Shortcuts by “Visio Guy” outlines the navigation shortcuts that also work with Visio 2013. Mastering and memorizing them makes Visio use a pleasure!

Another task that I frequently run into while using Visio is the need to replace an object, say, a square with another such as a diamond, for example. Visio does not allow you to do this natively. You’ll have to delete the object, reconnect all the connectors, etc. If you have many objects to replace, it translates to a lot of work. Then I found Paul Herber’s Super Utilities and Tools for Visio. Among its many features, there is “Shape substitute” command that does exactly that — very handy!

LaserJet P2015dn duplexing on Windows 7

HP LaserJet P2015 models use “Universal” driver under Windows 7. When first installed, duplexing doesn’t work by default. This is a surprise for many who come from Windows XP environment where the dedicated drivers had P2015’s built-in duplexing availability turned on, of course, by default. In Windows 7, however, the duplexing selector for P2015 says by default: “Print on both sides (manually)”.

To enable P2012’s automatic duplexing on Windows 7 go to Devices and Printers, highlight the P2015, right click, and select Printer Properties from the context popup menu. Go to Device Settings tab and look for “Duplex Unit (for 2-Sided Printing)” option. It’s set to “Not Installed” by default. Change it to “Installed” and click on “OK”. Now when you go to Preferences when getting ready to print, the automatic (not “manually”) option is available on the Finishing tab, and automatic duplexing works.

Also if you use the excellent priPrinter utility, P2015 honors the “Double Sided” toggle on the Page Layout tab. Same goes for the “Double-sided” checkbox on FinePrint utility, and other applications that provide the option to turn automatic duplexing on or off.