use jade templates

[timaschew]

This is kind of a next step of #187

You see the generated website via github pages here: http://timaschew.github.io/website/en/index.html

So the main change was to use jade for the templates and provide a blog with the medium articles as markdown files and a index page for the blog which list all the articles with the date, which is encoded into the filename of each article, for instance: 2015-02-10_io-js-and-a-node-js-foundation.md

Write the templates in jade change the gulp template task from this:

      var pageTitle = thisFileJSON['browser-title'];
      thisFileJSON = _.omit(thisFileJSON,'browser-title');
      var finalJSON = {};
      _.forEach(thisFileJSON, function(value, key){
        finalJSON['[i18n-'+key+']'] = value;
      })
      finalJSON['[i18n-content]'] = html; // Attach md2html string to the interpolation object
      var htmlObj = HTMLtemplate(); // finally using that holder for the template stream
      i18nObj = htmlObj.template('i18n',{include:false}); // same
      var filepath = __dirname.split('gulp/tasks')[0] + 'source/templates/main.html'; 
      var fileStream = fs.createReadStream(filepath) // pulling this code from substack's example on html-template
        .pipe(replaceStream('<title i18n-title>io.js - JavaScript I/O</title>','<title i18n-title>'+pageTitle+'</title>'))
        .pipe(replaceStream('markdown-page=""', 'markdown-page="'+file.filename+'"')) // add css-triggerable attribute to body
        .pipe(replaceStream('[page-stylesheet]',file.filename)) // require in specific stylesheet
        .pipe(htmlObj)
        .pipe(source(file.filename + '.html')) // converting the readStream to a vinyl stream so gulp can write it back to the disk
        .pipe(gulp.dest('public/' + lang + '/')); // dump it in the appropriate language subfolder
      i18nObj.write(finalJSON); // write the interpolation JSON to the template
      i18nObj.end(); // saving? this is taken from substack too.

to this:

      templateJSON.page = file.filename; // extend locals for special styles on each page
      templateJSON['page-stylesheet'] = file.filename; // for special css files for the page
      templateJSON['i18n-content'] = html; // attach the rendered markdown into the body
      var filepath = __dirname.split('gulp/tasks')[0] + 'source/templates/main.jade'; 
      var destinationDirectory = path.dirname('public/' + file.filepathArray.join('/')); // consider 
      gulp.src(filepath) // read jade template
      .pipe(jade({ // render template while passing locals
        locals: _.cloneDeep(templateJSON)
      }))
      .pipe(rename(file.filename + '.html')) // rename output file, using md filename 
      .pipe(gulp.dest(destinationDirectory)); // dump it in the appropriate language subfolder

The template also looks more clear, instead of writing

  <footer class="content">
    <nav>
      <a href="https://github.com/iojs/io.js/issues" i18n-issues-link>GitHub Issues</a>
      <a href="https://github.com/iojs" i18n-org-link>GitHub Org</a>
      <a href="https://webchat.freenode.net/?channels=io.js" i18n-irc-link>IRC Chat</a>
      <a href="http://logs.libuv.org/io.js/latest" i18n-irc-logs-link>Logs</a>
      <a href="https://github.com/iojs/io.js/blob/v1.x/GOVERNANCE.md#readme" i18n-gov-link>Governance</a>
    </nav>
  </footer>

we can write this:

    footer.content
      nav
        a(href='https://github.com/iojs/io.js/issues')=locals['issues-link']
        a(href='https://github.com/iojs')=locals['org-link']
        a(href='https://webchat.freenode.net/?channels=io.js')=locals['irc-link']
        a(href='http://logs.libuv.org/io.js/latest')=locals['irc-logs-link']
        a(href='https://github.com/iojs/io.js/blob/v1.x/GOVERNANCE.md#readme')=locals['gov-link']

But the really cool feature is that we can use logic into the template like create markup on condition or loop over an array like for the blog articles:

  h1=locals['blog-link']
    ul.blog-posts
      each article in articles
        li
          a(href=article.url)
            span.h2=article.title
          div.post-date.
            #{locals['posted-on']} #{article.date}

Another change due to the template.json: there is now a fallback with a __translated meta object, so you can check if a (new) property is already translated or not, if not the fallback (english) value will be used.
With this trick the blog will be displayed in the menu only if the blog-link was translated in a given language:

if locals.__translated['blog-link']
  //- if 'blog-link' is not translated for the given lang, hide the blog menu item
  a(href='#{locals.urlPrefix}/#{locals.lang}/blog/')=locals['blog-link']

to summarize, this pull request include:

• use jade
  • easy binding between templates.json and master.jade
  • add logic like conditions and loops within the template
• add a blog (en only)
  • with articles from medium as markdown files
  • listing of all articles with the title and the date

fixes/support:

• set the correct language into the html lang attribute, for instance: <html lang="de">
• fix url paths for css and menu links (only occurs if you use a subfolder, like the blog)
• set optional urlprefix, if the website is not located at the root of a domain/host like for github pages
• fallback properties for template.json
  • new properties don't need to be copied from the english to all the locales
  • check if a property is translated via __transletd meta object, otherwise the fallback will be used
• make target to deploy the website to github pages for dev purposes, example

[therebelrobot]

@iojs/website can we all take a look at this? I know the template task needs lots of loving, and if this jade solution works for what we need, I'm willing to jump the html-template boat. I'm gonna add this to the agenda for tomorrow so we can discuss how it does.

@timaschew a couple things: we haven't yet decided on bringing in a blog, as its still an open issue #68, so I would prefer having that in a separate PR. generally we want to keep refactors and additions separate in PRs to ensure everything is being reviewed properly. Also, there is a merge conflict in this PR, will you take a look at that too?

I'm gonna pull down your changes and take a look at them today, see how it all performs.

[timaschew]

yeah I wanted to demonstrate how easy it is to include a (static) blog with jade ;)

Great, I will cut the blog out and fetch the new changes from the upstream

[timaschew]

done :)

[therebelrobot]

Thanks for that. I'll pull it down and take a look at it now.

[Fishrock123]

I'm willing to jump the html-template boat.

If everyone is comfortable with jade, sure I guess. I still think hbs is more well-known (despite the fact that I like jade). html-template is fine for doing content insertions, but it seems a little weak on doing insertions for attributes and such.

[alubbe]

I think jade is superior and helps spread the usage of "good" tools within the community

[timaschew]

any updates on this?

[snostorm]

@timaschew this is on the working group agenda for next meeting. To meet some interim needs I do have #243 up right now which quickly swaps out to using handlebars (for now) but I'm still open to discussion around bigger changes -- especially since the templates build script can continue to be iterated on to be made faster and more flexible.

[therebelrobot]

On the agenda for Mar 2nd Website WG meeting #240

[therebelrobot]

Unfortunately, as per our discussion in the last WG meeting, we aren't going to be pulling in jade for the time being. Maybe down the road after we get a new design in place it'll make more sense, but handlebars is handling what we need to for now.

[timaschew]

Why it does only sense with a new design?
And why is handlebars what you need now?