Occasionally, working on some projects hosted on github, we put much time into creating useful & comprehensive README.md file for our project and I think you can benefit from using it to create html pages hosted on github that will be always in sync with the content.

Issue

When you might benefit from thing I’m talking about? For example, your README.md is magnificent & useful, you have some static examples hosted on github page but there’s no landing page and no connection between two. Whenever someone lands on your examples, if he knows how github pages work, he might edit the URL in his address bar & land on your repo (not everyone does & that’s quite normal). And on top of that, you don’t have time/skillset to do a cool static page and will be happy with something minimal for lack of better alternative. I turned to do this after I’ve seen I have different content in README.md & static page used for the folder (hosted on github pages) for statically hosted slides project of mine.

How to solve it?

Turn your README.md into static page! Your repo is already on github, and whenever you push something to branch name gh-pages it’s being build & published to %username%.github.io/%reponame% (given it’s enabled in the repo’s settings). Only exception is your very own github space that resides in repo called %username%.github.io and will be using master branch to build stuff out. Github pages use Jekyll - static site generator written in Ruby. There’re some catches to it - you cannot run plugins on Github pages, Github is using some custom markdown parser, - maybe, something else, but those are minor considering how useful this feature is, providing static site hosting & ability to use markdown to create content (you can run your very own blog using Jekyll or Octopress built on top of it and pay noone for that).

‘Code’ to do that

To signal Jekyll that some markdown needs processing, you add YAML syntax FrontMatter in the very beginning, which can be as brief as two sets of triple dashes, separated by newline.

---
---

Learned this some time ago when was battling with Jekyll for kottans.org site, which now seems to be a common knowledge, marked as ProTip in the corresponding section of documentation. But after README.md will be processed it will be output as ‘README.html’, which poses a minor issue. We don’t want to change the name of the file (README.md will rendered by default when looking at repo page using github), but we want to be able to navigate to root path of our project and still be able to see something instead of four-oh-four page, which means we want to have index.html page probably. I used something simple as static page that would be redirecting to README.html. There’re at least 2 different ways to redirect using <meta> tag and couple of ways to navigate to another page using JS, so it shouldn’t be of too much of a trouble. I ended with following code:

<!DOCTYPE html>
<html>
<head>
  <title>Redirecting to main site</title>
  <meta charset="UTF-8">
  <meta http-equiv="refresh" content="0;url=README.html">
</head>
<body>
  Redirecting<i>↻</i>
</body>
</html>

And that would be pretty much everything that needed to be made in order for your README.md get 2 horizontal rulers on top (those tripple dashes added for jekyll’s sake) & it’s very own html representation on your github pages.

Caveats

Broken Charset on Localhost & _layouts

If you use github-pages gem to bootstrap jekyll locally and directly going to ‘localhost:4000’ URL, you might see some issues with encoding because of lack of specification of proper character encoding. This won’t be a problem when pages are on Github, because Github sets charset=utf-8 encoding using Content-Type header. In any case, if that might be a problem for you, you might want to add layout with proper charset. For this, you will need to create _layouts folder and put default.html with following markup:

<!DOCTYPE html>
<html>
<head>
  <title>These are my precious slides!</title>
  <meta charset="UTF-8">
</head>
<body>
  <header><a href="/">Home</a></header>
<article class="post h-entry" itemscope itemtype="http://schema.org/BlogPosting">

  <header class="post-header">
    <h1 class="post-title p-name" itemprop="name headline">Concurrency in JS</h1>
    <p class="post-meta">
      <time class="dt-published" datetime="2015-05-04T00:00:00+00:00" itemprop="datePublished">
        May 4, 2015
      </time>
      </p>
  </header>

  <div class="post-content e-content" itemprop="articleBody">
    <p>Recently I’ve been to <a href="http://bostonjs.com/">BostonJS</a> at Bocoup, where <a href="https://twitter.com/naveedi">Naveed Ihsanullah</a> from Mozilla shared some of the upcoming concurrency features that will come to live supposedly in about a year (and this talk took place on 30th of April 2015).</p>

<p>Previously, closest we had to concurrency was usage of <a href="https://developer.mozilla.org/en-US/docs/Web/API/Worker">Web Workers</a>, which solved some of the problems. It provided us with ability to offload heavy computations from our single threaded javascript. It was safe in terms of playing well with single threaded execution model, but involved some overhead for communication between main thread and workers, as well as imposing restrictions to what kind of code could run in those.</p>

<p>Looks like things are going to change. There’s a <a href="https://docs.google.com/document/d/1NDGA_gZJ7M7w1Bh8S0AoDyEqwDdRh4uSoTPSNn77PFk/edit#heading=h.a6o4dubw5qla">draft spec</a> “Spec: JavaScript Shared Memory, Atomics, and Locks”, and <a href="https://gist.github.com/dherman/5463054">this gist</a> that talks about <code class="language-plaintext highlighter-rouge">SharedArrayBuffer</code> primitive that would be concurrently accessible. You could read about motivation and roadmap in February <a href="https://blog.mozilla.org/javascript/2015/02/26/the-path-to-parallel-javascript/">entry in Mozilla blog</a>.</p>

<p>Naveed joked about bringing <a href="http://en.wikipedia.org/wiki/Deadlock">deadlocks</a> &amp; <a href="http://en.wikipedia.org/wiki/Race_condition">race conditions</a> to previously safe js (which is great pun and will help make future interviews ‘funnier’: ‘- do you want to create static pages for us &amp; validate some forms? - Yeah! - Great, tell us about concurrency &amp; deadlocks in javascript’).
I might have got previous paragraph distorted, so here’s an actual comment by Naveed:</p>
<blockquote>
  <p>Deadlocks are actually possible now in JavaScript. Shared memory and the associated locks, however, would potentially allow data races and new deadlocks because of synchronization. A bit different. What I meant is shared memory can be complex and JavaScript was spared that complexity in the past. Depending on how we finally choose to surface this functionality that may not be the case in the future.</p>
</blockquote>

<p>It seems that API will be going through some dramatic changes over the course of next months. Naveed mentioned that on the day of the talk there was an interesting idea of looking into the way C++ handles threads &amp; modifying the API slightly. For more details, you might want to take a look at <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4195.pdf">this draft</a>.</p>

<p>Closing up was the demo of visualizing <a href="http://en.wikipedia.org/wiki/Mandelbrot_set">Mandelbrot fractal</a>, which used all 8 cores. Notably, it was also using <a href="http://en.wikipedia.org/wiki/SIMD">SIMD</a>, which made code run several times faster. The fractal demo itself was about 6x faster (using 8 cores instead of 1), than normal JS because of shared memory &amp; threading. SIMD brought another 2.5-3.5x pefromance boost.</p>

<p>Such an API might be used to enable some great things in the web, as well as bring us another way to shoot ourselves in the foot.</p>

<p>Naveed did mention necessity of future involvement of library authors to wrap this powerful low-level primitives to bring end-users handy tools that would enable easier work, especially when it will involve VR, image processing and other heavy-computational activities that will get only more widespread as we go forward.
Oh, Naveed did mention that there was a <a href="https://groups.google.com/a/chromium.org/forum/#!topic/blink-dev/d-0ibJwCS24">public indication</a> that V8 team had intention of implementing this, so let’s just hope we will have this generally available in around a year.</p>

<p>All in all, this looks like interesting space to follow &amp; I would definetely be looking forward to Naveed’s talk on <a href="http://2015.jsconf.us/speakers.html#ihsanullah">JSCONF US 2015</a>.</p>

<p>I want to thank Naveed for taking time to review this post &amp; provide additional details I didn’t get right the first time 😼</p>

  </div>

  
    <div id="disqus_thread"></div>
    <script>
      var disqus_config = function () {
        this.page.url = 'http://sudodoki.name/concurrency-in-js/';
        this.page.identifier = 'http://sudodoki.name/concurrency-in-js/';
      };
      (function() {
        var d = document, s = d.createElement('script');
        s.src = 'https://sudodokiname.disqus.com/embed.js';
        s.setAttribute('data-timestamp', +new Date());
        (d.head || d.body).appendChild(s);
      })();
    </script>
    <noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript" rel="nofollow">comments powered by Disqus.</a></noscript>
  
  <a class="u-url" href="/concurrency-in-js/" hidden></a>
</article>
</body>
</html>

and in your README.md you will have to put

---
layout: default
---

which will render not that pretty when looking at your github project page, but as soon as you do that step you can add all sorts of customization and styling to the page.

Default markdown parser might work differently from Github’s

In process of creating html version page for one of my slides it turned out that markup of

Strike through heading

isn’t working in markup used in jekyll by default. Thanks to issue#1752 in jekyll repo I was able to go over bunch of different possible engines to render markdown to find the one that worked correctly for page that used github flavored markdown (spoiler: it was rdiscount). To set an engine used on your gh-pages, you will need to create _config.yml file in root of your project and put

markdown: rdiscount

into it. That did solve the issue of. 😼

Nested folders & README.md

Every folder, especially when it’s a separate entity/project, should have its own README.md to explain how/what/why of the contents. That will mean, that you will have to apply the same changes to the README’s content as to the one in you project root (and add redirecting page).

Write READMEs

Be a good person and don’t just throw your stuff over the fence in the world of open source. Share your work, show you care about it & people using it, and you will get tenfold in return. Hope this small note will help you have this while spending less time. Hope it was somewhat useful. 😇