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:

varpageTitle=thisFileJSON['browser-title'];thisFileJSON=_.omit(thisFileJSON,'browser-title');varfinalJSON={};_.forEach(thisFileJSON,function(value,key){finalJSON['[i18n-'+key+']']=value;})finalJSON['[i18n-content]']=html;// Attach md2html string to the interpolation objectvarhtmlObj=HTMLtemplate();// finally using that holder for the template streami18nObj=htmlObj.template('i18n',{include:false});// samevarfilepath=__dirname.split('gulp/tasks')[0]+'source/templates/main.html';varfileStream=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 subfolderi18nObj.write(finalJSON);// write the interpolation JSON to the templatei18nObj.end();// saving? this is taken from substack too.

to this:

templateJSON.page=file.filename;// extend locals for special styles on each pagetemplateJSON['page-stylesheet']=file.filename;// for special css files for the pagetemplateJSON['i18n-content']=html;// attach the rendered markdown into the bodyvarfilepath=__dirname.split('gulp/tasks')[0]+'source/templates/main.jade';vardestinationDirectory=path.dirname('public/'+file.filepathArray.join('/'));// consider gulp.src(filepath)// read jade template.pipe(jade({// render template while passing localslocals: _.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

<footerclass="content"><nav><ahref="https://github.com/iojs/io.js/issues" i18n-issues-link>GitHub Issues</a><ahref="https://github.com/iojs" i18n-org-link>GitHub Org</a><ahref="https://webchat.freenode.net/?channels=io.js" i18n-irc-link>IRC Chat</a><ahref="http://logs.libuv.org/io.js/latest" i18n-irc-logs-link>Logs</a><ahref="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-postseach 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:

iflocals.__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?