Solving From A Different Direction

As of late I have been a bit remiss in getting these blog posts out the door.

Part of the issue has been I didn’t have a good blog creation solution. I have tried standalone apps, the provided editor from my blog provider and I even tried using different plugins to get the results I wanted.

This week I was documenting the REST API for my new web project and I realized that what I was doing there might solve the problem I was having here.

The problem has been how to show code snippets. So far all the standalone blogging apps I have tried have failed in one way or the other when I tried to attach code. In fact it was so bad that in my last post I had to post screen shots of the code.

That’s not right, so I have been hampered by this problem for a while.

As I said, I was documenting the REST API for my new web project and I have been doing it in Markdown so that I could view it, nicely formatted, from the git repository. In it, I had to show an example of the REST call in CoffeeScript as well as show the resulting JSON that was returned.

Markdown has a very simple way of showing code snippets, but for me it wasn’t working exactly right. It was delineating the code, like I wanted, but it was showing it all on one line.

What I learned, after some investigation, is Markdown has different flavors. Oh the joy of the open source world we live in ;-/

Anyway once I figured out the syntax for the particular flavor of Markdown my git repository supported I was able to get the code snippet formatted properly. So my CoffeeScript code looked like this.

     $.ajax({
        url: "/goals",
        dataType: 'json',
        type: 'POST',
        data: {
          goal: ...
        },
        success: function(data) {
          ...
        },
        error: function(xhr, status, err) {
          ...
        }

With this working it got me to thinking. What if I just wrote Markdown documents, and then exported them to HTML and pasted them into my blog? Would it work?

So today’s post is mostly a proof of concept of that. I can already see one downside and that is I’ll need to keep the Markdown versions locally, if I want to make any edits. It pretty much makes the editor on the blogging site useless.

I found several online editors that can take Markdown and export the HTML. Another requirement was that this HTML file had to be a single file, otherwise it would be hard to cut and paste it into the blog application.

After trying JavaScript, Swift and Ruby code I was pretty confident this could work. However, I also needed to show ReactJS code as well.

This has been the code that has presented the most challenge to the various solutions I have tried. The reason I think (I use JSX syntax) is the code starts out as JavaScript but then in the “render:” method turns into XML/HTML.

All this works because of the “JSX” compiler.

However, I have not found a standalone app that has handled this well. Admittedly I do need to go back and see what support the standalone apps have for Markdown, since I now think that is right format to use. At any rate, here is a simple JSX file:

var Page = React.createClass({
  getInitialState: function() {
    return {goals: []};
  },

  componentDidMount: function() {
  },

  render: function() {
    return (
        <div className="col-md-10 main defaultheight">Page
        </div>
    );
  }
});

I was pleasantly surprised how well this worked.

There is another advantage in using this scheme and that is any documentation I write for my iOS projects can also be done in Markdown (well a flavor of it).

So in the end the fix to a problem I was having for a different issue (that of documenting the REST API) may also solve the problem I have with including code snippets in blog posts. Anytime I can have one solution that solves two issues, I call that a win!

Till next time.