Get Started with Static Site Generators

In the early days of the web, there was no such category as “static sites” - the web was made up of static resources. This was a maintainable solution when the web was simple. That didn’t last long. Static sites had enormous limitations that made them an impractical solution for most web sites - even the relatively simple ones. More recently, however, a combination of asynchronous content, third-party services and new tools, called static site generators, have made the old skool static site both feasible and cool again. Tools like Jekyll are used to run thousands of sites across the web (including this one…though it admittedly deserves more love). But what are static site genertors? Which one of the 400 or so of them should you consider using? What types of sites are they most suitable for? These are some of the questions I aim to answer in a free report on static site generators for O’Reilly Media. I know what you are thinking - “Awesome, just in time for the weekend!” You’re right! Did I mention it is free? Also, I should note that it is free. Hopefully this report will answer any questions you may have about static site generators and help you get started in choosing one. Static Site Generators - Modern Tools for Static Website Development

Posted by on 24 September 2015 | 11:00 pm

Which Free Code Editor Is Right For You?

We live in a day and age as web developers where our biggest complaint seems to be a overabundance of free tools. In the case of code editors, there are a few prominent free ones: Atom, Brackets and, most recently, Visual Studio Code. Each editor has its own set of strengths and weaknesses. Each is backed by a large corporation - GitHub for Atom, Adobe for Brackets and Microsoft for Visual Studio Code - so obviously they will be geared towards the target audience of each respective company. Nonetheless, they are all good editors. So which one should you choose? Well, it depends. You knew I was going to say that! In my latest article, Battle of the Free Code Editors, I go into the distinguishing features of each editor and what type of developer it is best suited for. Please, check out the article and feel free to share your thoughts. A Note on Sublime I was asked numerous times after writing this article, why did I not include Sublime? After all, Sublime is, for all intents and purposes, the market leader for lightweight code editors. The article compared free editors. However, Sublime is not free! Yes, you can try it for free and, as many responses noted, use it forever without paying if you are willing to live with dismissing the prompt to buy regularly. One person even noted to me that if the author didn’t want people to use it for free forever, they’d have a different license method. I’m sorry, that’s not how this works. The author clearly states: Sublime Text may be downloaded and evaluated for free, however a license must be purchased for continued use. As I said on Twitter… It surprises me how many people seem to advocate using Sublime for free. If you think the software is great, why not pay what they ask?— Brian Rinaldi (@remotesynth) September 17, 2015

Posted by on 22 September 2015 | 11:00 pm

Picking the Right Speakers for Conferences

I have been involved in events for some years, ever since running Flex Camp Boston back in 2007 and as recently as handling many aspects of the planning, in particular the speaker lineup, for this year’s TelerikNEXT event. I’ve also served on conference committees for events like QCon New York and Fluent. In my personal experience, the hardest part of running events are getting the word out and choosing the right speakers. Arguably, choosing the right speakers can heavily impact your ability to get the word out - after all, your content is the biggest selling point of your event. Yesterday, Lea Verou posted an opinion piece saying that blind reviews for technical conferences is a broken model. You should read the full post. In summary, she believes that while the goal is to reduce bias and allow unknown speakers an opportunity, it ends up leading towards choosing “safe” topics. This is because the fear is that the more advanced or atypical topics, in the hands of the wrong speaker, could totally bomb (I’m paraphrasing - these are my words not hers). I agree with her, and while I laud the goals of making the speaker selection more egalitarian, there is simply not enough information in a typical abstract to know how successful a presentation will be as the text doesn’t indicate the speaker’s ability to communicate effectively in the format of a session (and requiring a prior session recording already starts making the process less open to fresh faces). Here’s the response I added to her post: I totally agree with this. When I ran a conference for 5 years, I was of the mind that who gave the talk was generally more important than what they were talking about. There are people whose talks I want to see regardless of what the topic is - they are engaging, thought provoking and I always come away learning something. Other people could pick the best topic and even have the best slide deck and bomb. I chose to have invite-only speakers list. That being said, I always set aside a certain amount of slots for speakers I’d never seen or who were new. The trouble with invite only events is the tendency to invite from within the same group every time. To me the best option is to have a committee that you trust and who represent a diverse set of experiences, backgrounds and views. Have this committee be conscious of efforts to be inclusive and make sure there is room for some fresh faces (even acknowledging that some of these will inevitably bomb). As you say, each method has its flaws and potential for bias, but even the blind review (as you point out) has bias, just of a different kind.

Posted by on 14 August 2015 | 4:00 am

Is the Web Really in Trouble?

This morning I published a post on the Telerik Developer Network that asks the question “What’s Wrong with the Web?”? If you read about web development at all (and apparently you do, since you are reading this), you can’t possibly have missed the long list of posts declaring that the web, as we know it, is in serious jeopardy. The main issues are: The web is losing the battle to native The web is too slow, largely due to the weight of advertising The web is too slow, largely due to the cruft of too many libraries and frameworks The web is trying to be something it isn’t (i.e. native) and adding too many unecessary features There may be more, but these are the core debates. The thing about all these debates is they are very technical - they are about how we build web apps or the underlying technology of the web. None of these debates seems concerned with what we are building. As I argue in the conclusion of my post, perhaps we’re worried about the wrong thing. Perhaps if we focused on building awesome and creative things on the web again, the answer to these problems would work itself out. I worry that web developers have become like bureaucrats, too worried the procedure of building web apps, having lost sight of the point of building them in the first place. I’d love to hear your thoughts. Please comment on the post on the Telerik Developer Network.

Posted by on 2 August 2015 | 4:00 am

The Web is Boring

When I was growing up, flying was fun. This wasn’t the kind of fun that a kid finds in simply new experiences - it was a legitimately enjoyable experience. The airport was a much less stressful place than it is today, with far less security and fewer lines. The planes seemed more spacious (though perhaps that part was really just that I was a kid). They served you food on most flights - with a real, metal fork and knife. Perhaps it wasn’t the greatest food, but wouldn’t we just love to get something, anything, nowadays? They’d even let kids go into the cabin and meet the crew, often handing them a junior crew member pin to wear. I fly more nowadays than I did back then, but flying is generally painful. The airport is stressful. The airline customer service is generally awful. There are few, if any, meals or snacks served. Flying has become something I need - for work, to visit family, to get to somewhere for vacation - not something I enjoy. Even on vacation, flying is something we power through to get where we want to be rather than being part of the vacation experience. The Web, Too, Has Lost Its Luster Much like the joy of flying, I am finally ready to openly admit that the web is no longer fun. Just like flying, I use it more today than I ever did back when it was fun, but it is purely out of necessity rather than desire. On a personal level, I use web sites to get news and to keep up with friends and family. The web is, obviously, an integral part of my work too, for news and information as well as the focus of my actual job. All of these things I need, but none of them bring the joy and exitement that the web used to bring. Perhaps you are not old enough to remember when the web was fun. If so, you may even think that it is fun. But back in the mid-to-late-90s, the web had the power to amaze us. New sites and new businesses would launch regularly and everyone had to try them out because each one seemed to bring something new and creative to the table. Sure, many didn’t survive long (and we had tons of useless accounts), but they all seemed to be part of an inexorable path towards something special - a future where the web would make our lives more enjoyable, easier and, yes, more fun. Many of us firmly believed that the web was the future of computing - who’d need a desktop or operating system when the web was eventually going to replace the need for either. That Didn’t Happen Let’s be honest. None of that ever happened. You may be thinking, “But what about my streaming movies or my streaming music or my multiplayer games? Aren’t those fun?” To which I’d say, “Don’t confuse the internet with the web.” The internet enables each of these, but they are rarely done via the web (yes, they all have web interfaces, but I’d bet the majority of people do not access them this way). There’s been a lot of talk about how the web is losing some unofficial battle for survival. Much of that has focused on the overwhelming amount of tools for web development and the way these tools are impacting the performance of the web. I am not disagreeing with those, per se, but I can say that the web was actually much more fun back when it was also horribly slow (most of us were on dial-up after all). I feel that the thing holding the web back is a lack of real, creative innovation. I read every day about new little features of the web platform, but I can’t remember the last time I read about something built on the web that really excited me. Until then, I’ll keep passionlessly reading my news and blog posts or getting my gmail and hating myself for checking Facebook for lack of something more interesting to do. Sorry, web, but you bore me.

Posted by on 24 June 2015 | 4:00 am

Tips for Writing for a Tech Audience

I’ve been writing articles and blog posts about web development and technology for a long time. The original version of this blog started in 2004, but by that time I’d already written a couple articles for the ultra-prestigious ColdFusion Developer’s Journal (it’s ok to feel jealous). However, I’ve also been editing articles and blog posts about web development and technology for a while too. It started when I was at Adobe helping to run the Adobe Developer Connection a few years ago and continued when I launched my own site (Flippin’ Awesome which is now Modern Web and not run by me anymore). I still do this on an almost daily basis running the Telerik Developer Network. All of this experience has taught me some things that I think help to make a really good (and potentially really popular) article or blog post for a developer or technology audience. In this post I’ll share my recommendations, though I should note that I’m not an expert at always following my own guidelines all the time. Have a Style It’s important to keep in mind that you aren’t writing API docs. API docs are generally dry, boring and simply stick to the facts. That’s their goal. However, an article or blog post should allow some of your personality to shine through. This helps to make the content both more relatable and more enjoyable to read. Keep in mind that your goal is both to educate and to entertain, to some degree. Some developers revert to a litany of code and explanation. It’s better to have a voice and have a story. Some things that can help: Explain why you are trying to do something, not just what you are trying to do and how you are doing it. What made you get interested in doing this? Did you have a struggles along the way? There’s no shame in admitting that you found something difficult - your readers will likely relate to the experience. Have fun with the demo! Perhaps pick something you are interested in that isn’t technical. For example. I often choose to use some cartoons I enjoy as subject matter for my demos. Know Your Audience While you should have a voice and a style, it’s important to know when it’s ok to be more or less casual in your voice. If I am writing something for my blog, I am often much more casual than if I am writing for the Telerik Developer Network or Sitepoint. If I am writing for my blog, proper grammar, punctuation and spelling are less important. If I am writing for a professional site, these become the difference between seeming like an amateur and not. You’d be surprised how people are affected by these things, even if they do not recognize it themselves. Some sites have editors who help with this, but others don’t - so don’t rely on them to correct your mistakes. Try to always have a friend you trust read through the article first - this isn’t critical for a personal blog post but even those can benefit. Even the best writers need a second opinion and there is nothing than can make your content better than a good, critical opinion. Stay on Track So many developers tend to think that every little detail is pertinent. So, they get sidetracked. Instead of traveling straight down a path, they don’t just point out the detours, but take you down them. As a rule, if the information doesn’t apply to most situations, don’t spend time on it. These are the kind of scenarios like, if you are running an old version of X operating system and want to perform special action Y, you’ll need to do this a different way - let’s walk through it. Another example is getting lost in caveats, detailing every minor exception that in all likelihood doesn’t apply to the reader. The best strategy in these cases is to simply point to the “detour” as an aside and link to the best resource to follow. Or note that there are exceptions but don’t go detailed into the full list of caveats. You may feel as though you are being somehow incomplete in your coverage, but you are less likely to lose the 90% of the readers to whom the straightforward path applies by not catering your post to the 10%. Avoid the Wall of Text There is nothing harder to read than a post that has no headers and is filled with overly long paragraphs. Adding section headers and even subheaders for long sections not only makes your article easier to read, but also makes it easier to scan - which can help the reader determine it’s value to them. Shorter paragraphs also make your content more readable and scannable. Plus, a wall of unbroken text can seem intimidating to a reader. Break up large paragraphs and, whenever possible, place key ideas into lists, which I’ve found can help drive home key points and improve retention. What Are Your Ideas? Hopefully you’ve found these ideas helpful. Do you have any strategies you use to improve your writing? Please share.

Posted by on 18 May 2015 | 4:00 am

Why are Web Developers Hostile to Audio?

I like to talk and write about Web Audio. It can be a fun topic. However, most talks and demos fail to touch on anything useful. Sure, we can build drum machines and sequencers to our heart’s content, but how does this apply to 90% of the web? It doesn’t. Thus, when I speak or write about web audio it seems to draw a niche audience. However, recently I have been on a mission to talk and write about how web developers can use web audio to enhance their applications in practical and useful ways. The frequent response I get is like the one below: You gotta love social media because not only did this person make it clear he never bothered to read the article, but 5 people (which on Google Plus is like everyone) gave it a plus one. However, leaving aside those issues, why are web developers so outright hostile and dismissive to even the suggestion of using audio on the web that they aren’t even willing to discuss it or hear arguments as to how it could be useful? Let’s recap: Audio in game UI equals totally expected; Audio in mobile app UI equals acceptable; Audio in desktop app UI equals legitimate, within reason; Audio in web apps equals ARE YOU INSANE?!?! I have a theory as to why. The Legacy of Years of Misuse I expressed this In the early days of the web, we didn’t have the web audio API. What we had was site’s that got clever and used MIDI or, even worse, had some obnoxious “Hamster Dance” like audio. Then came years of Flash Intros and more useless audio. It became ingrained in web developers’ heads that audio on the web was purely a gimmick. It is such a widely accepted “faux pas” to include audio, that even the mention of carefully considering audio brings strong reactions. It’s Time to Let It Go But do we have to be held back today by the misdeeds of years ago? Sure, the web audio API can be misused. Sure, so far, we’ve mostly shown how it can be used for things like 8 bit video game music (guilty as charged) and web-based drum machines. (Not that those things are useful, even purely as excercises in having some fun with your programming skills, they are beneficial.) The point is, though, this doesn’t negate there being useful and practical ways to integrate audio into your web application. If it’s ok for every other type of application, why not the web? Unlike the commenter above, perhaps you’ll give my full article a read. I’d love to hear your thoughts on the topic.

Posted by on 14 May 2015 | 6:15 am

Jekyll Versus the Competition

On Saturday, May 2, the first ever JekyllConf was held online and featured some really prominent speakers including Tom Preston-Werner and Brandon Mathis. I had the honor of opening the event with my session comparing Jekyll to other popular static site engine options including Harp, Hexo, Wintersmith, Hugo and Middleman. In summary (and in my personal opinion of course), Jekyll is still in the strongest position of all the engines. It has the strongest community (partly evidenced by JekyllConf itself), the best documentation (not saying it couldn’t be better, but it’s better than the alternatives) and has the largest selection of pre-built templates and plugins. However, it has failed to reach much beyond hardcore developers. This is partly because of the nature of the tool - for instance, few people outside of the developer community enjoy working on the command line…in fact, most find it intimidating. Tooling for authors is weak too - Markdown is a terrible option for authors (who aren’t developers). We think of it as being so simple and easy, but that’s actually what makes it so complex. In terms of authoring, it covers a majority of use cases, but it is still very common to encounter requirements that it doesn’t meet (intentionally, since it’s goal was simplicity). Thus, when you teach an author Markdown, you need to teach them the syntax, what it doesn’t cover and HTML to handle those scenarios it doesn’t cover. This is actually more complicated than simply teaching them HTML. In my opinion, until the tooling is available to allow authors and contributors to write using the tooling they love, static site engines will remain a niche solution. This is a shame as they actually seem like the optimal solution for content focused sites and, perhaps more so, documentation sites. The good news is that there are people working on the tools needed to bridge this gap…we’ll see how this goes! You can see the full session recording below or view the full recording of the day here.

Posted by on 7 May 2015 | 6:15 am

Tools for Writing and Converting Markdown

By now, most developers are familiar on some level with Markdown. It’s become a somewhat ubiquitous part of developer tooling, probably in no small part due to it’s usage for documentation in GitHub. It also plays a big part in nearly all the major static site engines. The power of Markdown and probably a significant reason for its success is in its simplicity. But this is also its biggest weakness. Developers love Markdown because it offers a shorthand for probably 80% of their writing use cases - things like blog posts and basic documentation. For the other 20%, developers have no problem switching to straight HTML, which, of course, you can include in a Markdown file without issue. For writers and the general public however, this presents a huge obstacle. They cannot use the tools they are comfortable in writing with and they not only are forced to learn Markdown syntax, but they must learn those cases that Markdown doesn’t cover and the HTML to use in these cases. It’s multiple layers of complexity for the sake of simplicity. That being said, as Markdown becomes more widespread in its use, the tooling around it is slowly improving. I use Markdown daily and below are some of the tools that I’ve found useful in my own experience. Desktop Editors Most code editors such as Brackets or Atom already include some level of Markdown support. However, if you’re looking for an editor with richer functionality geared specifically towards Markdown, then there are a number of options. Mou is my current go to option for writing Markdown. As with pretty much every Markdown editor out there, you write in Markdown and have a live preview available. There is currently no option that I am aware of where you write in rich text and have it converted to Markdown. Mou offers syntax hinting and highlights as well as keyboard shortcuts, but my favorite feature (and why I prefer it) is the export. I rely heavily on the export to HTML feature and, in my experience, it has the most reliable of the editors I have tried. The only quirk I find is that it often stumbles when using backticks for code blocks (and doesn’t recognize the GitHub-flavored Markdown syntax for indicating the type of code within a code block). Currently Mou is still free, though a 1.0 looks to be forthcoming that will be paid. Another free option is Macdown, which was created when Mou appeared to be ceasing development. I found it to be quite buggy, personally, but have not tried it much since its initial release. If you are on Windows, some options I’ve heard recommended include Texts and MarkdownPad, though I have limited experience with either. Lastly, while not technically an editor, Markdown Live is a useful tool for live-previewing Markdown as you write it. Once installed, you simply change directory into the folder you want to serve up and enter mdlive and it will open a preview in the browser that will update as you type - without the need to save the file. This can be useful if you prefer to use a plain text editor for writing Markdown. Web-based Editors If you are looking for a free web-based option, Dillinger is a free (and open source) Markdown editor for the browser. It includes a live preview as well as the ability to import documents from numerous sources and export them to various formats. However, one of the things lacking in both desktop and web-based editors is collaboration. If you are working on a team, the ability to share, comment and collaborate on a document is not just useful, but necessary. Beegit is a commercial offering that includes a number of collaboration features. My team uses it mostly for the ability to share and comment on documents as they are being developed, much as you would within Google Drive. Converters When you are working with a number of contributors, it’s not always possible to force everyone to use Markdown. While Markdown’s simplicity makes it simple to manually convert short documents, converting long documents or groups of documents could get tedious and time consuming. While they aren’t perfect, in these cases, a converter can be enormously helpful. One converter that I rely on frequently is the Word to Markdown web app. Simply choose your local file and hit convert. The site will post you the Markdown it generates from the file as well as a live preview. For good or for bad, it even embeds images in the document using Base64 encoding. Personally, I find this can be difficult to clean up and replace with external images, so I often remove them from the source document first and put placeholders. Word to Markdown is also available as an open source project and command line tool. In my experience, I couldn’t get the command line tool to work properly for some reason, while the web app worked perfectly. In other cases, you may encounter rich text that you need converted to Markdown, such as text copy/pasted from the web or some other editor. In these situations, I’ve found Mark It Down to be both reliable and helpful (it is also open source). Simply paste in the rich text and hit the convert button to get back nice, clean Markdown. Other Tools? This is by no means a comprehensive list of Markdown tools - just the ones that I’ve personally come to rely on at some level or another. Are there any others that you recommend? Be sure to share in the comments as I’m always looking for new ones.

Posted by on 29 April 2015 | 6:15 am

Building Static Sites with Node.js and Wintersmith

When I’ve spoken on the topic or even when I posted my recent guide to getting started with Jekyll, the question I always get is if there is a comparable static site generator to Jekyll that is built with JavaScript and available on npm. The reason people cite is that they aren’t comfortable with Ruby and thus have trouble when they encounter problems with Jekyll or are unable to customize it completely to their needs. Well, there’s good and bad news. First, the bad news… I have found nothing comparable to Jekyll in terms of overall features, documentation and community. Now I don’t know every engine out there, but, so far, there’s nothing that even comes close to fully matching Jekyll. The good news, however, is that I found Wintersmith to be a viable Jekyll replacement. It has a lot of the key features and is extensible. Plus, there are a reasonable amount of extensions out there for it already. On the other hand, the documentation is awful (let’s be honest) and the community is small. So, if you run into a problem, you’re stuck reviewing the source code. On the upside, I found the source code is pretty self-explanatory when I needed to rely on it. Given the lack of a good getting started guide in the Wintersmith documentation, I wrote a two-part series for Sitepoint that walks you through the entire process of building a site. It follows the same exact format of my Jekyll guide covering everything from installation to templating, creating posts, custom metadata and custom data. Getting Started with Wintersmith: A Node.js-based Static Site Generator - Part 1 Creating Posts, Custom Metadata, and Data in Wintersmith - Part 2 The source code for the example is part of my Static Site Samples GitHub project which also includes the aforementioned Jekyll sample as well as examples for Harp and Middleman.

Posted by on 8 April 2015 | 4:00 am