When working from home, my preferred writing environment is to use a huge fixed-width font on a large monitor with a matte finish, and nothing else on the screen. I write my text using either Markdown or LaTeX, depending on what the output format is going to be. And Yoda and Meditating Guy make me feel a little less crazy when I’m talking to myself. ;)
I recently started using AsciiDoc to write a new book. A great thing about it is that unlike Markdown, you can use AsciiDoc to write a book and get all of the features you want in a book, including linking between anything, captions for tables and figures, indexes, etc. Because this got me started using AsciiDoc I thought, “Wouldn’t it be nice if I could also use AsciiDoc to write blog posts like this one?”
Sadly, I quickly ran into a problem: I couldn’t find a good way to convert AsciiDoc into HTML, or even Markdown. There are tools to convert AsciiDoc to HTML, but for some reason they take the approach of including a ton of markup in the HTML (divs, spans, and attributes), and as far as I can tell there’s no way to turn off that markup.Back to top
A shell script solution
It turns out that converting AsciiDoc to HTML without including a bunch of undesired CSS is a problem, and converting AsciiDoc to Markdown is also a problem. The page I linked to shows the best way I’ve found to convert AsciiDoc to Markdown, which can then be converted to CSS-free HTML. In case that page ever disappears, the basic commands are:
Install pandoc and asciidoc:
sudo apt install pandoc asciidoc
Convert asciidoc to docbook:
asciidoc -b docbook foo.adoc
Convert docbook to markdown:
This past week I started working on the index for my book on Scala and functional programming. In retrospect I wish I had written the book using LaTeX (or some other technology) rather than Markdown; I would have started this process long ago.
In this post I share the contents of a custom TextMate command I just created that uses
sed to convert markdown content in the TextMate editor to a “pretty printer” version of HTML:
#!/bin/sh PATH=$PATH:/usr/local/bin # note: 'sed -E' gives you the advanced regex's # use pandoc to convert from markdown to html, # then use sed to clean up the resulting html pandoc -f markdown -t html |\ sed -Ee "/<p|<h2|<h3|<h4|<aside|<div|<ul|<ol/i\\ \\"
You can try to use a command like
tidy to clean the HTML, but the version of
tidy I have does not know about HTML5 tags. The TextMate Markdown plugin also doesn’t work the way I want it. Besides that, I’m trying to learn more about writing TextMate commands anyway.
As an important note, when you set this up as a TextMate command and then run it, it will convert the TextMate editor contents from markdown to HTML.
(In a related note, serenity.de is also a good resource for TextMate command and bundle documentation.)
In summary, this code shows:
* How to execute a Unix shell command from TextMate
* Specifically, how to execute a
sed command from TextMate
* How to use modern regular expressions with
* How to search for multiple regex search patterns with
Markdown FAQ: How do I create comments in Markdown? Especially comments that won’t appear in the generated output.
Part 1 of my answer is that technically there is no way — or at least no standard way — to create comments in Markdown documents, other than to use HTML comments like this:
I’m looking into producing my Scala/FP book as a PDF, and as part of that I have been looking into Pandoc. With the exception of converting HTML tables into other formats such as Markdown or LaTeX, Pandoc has been working well so far.
Here are a couple of Pandoc commands to show you how easy this is:
I just created a TextMate 2 bundle to underline the current line, and this image shows how I created that bundle. The dashed-line will be the same length as the line the cursor is currently on (the current line). I do this a lot when I use TextMate to write notes and even Markdown text, so I wanted a little script/bundle like this.
FWIW, the result of this bundle/command is that I can have the cursor be on a line like “Hello, world,” as shown below, press [Command][u], and end up with this:
Hello, world ------------
I don’t know much about it yet, but MkDocs is a static website generator that’s “geared towards building project documentation.” I’ll add more here as I learn it.
FWIW, this is the source code for a
sed script I use on my Mac OS X system to convert HTML output generated by MacDown into a format I need. MacDown generates some extra “cruft” that I don’t need, so I use these
sed commands to clean up that HTML output: