Clean-up site setup

[addyosmani]

At the moment, going to http://tooling.github.io/book-of-modern-frontend-tooling/introduction.html gives you the current version of the book based on the gh-pages branch. Links to most of the chapters result in a 404, even if the content exists. I believe this is because of the way the TOC is currently generated.

I wonder if it's worth taking another look at how the TOC is handled and only list the sections that have content written up for them. Perhaps graying out the items that don't have any content yet. Does that sound like a feasible/sensible way of displaying the navigation?

cc @rowoot @sindresorhus

[sindresorhus]

Instead of graying out, I think we should just not make them linkable.

Example:

• Introduction
• Unwritten thing
• Gulp

[michealbenedict]

For now, I have made a quick change to gray out unwritten content, check PR #49

I'll explore better ways of automating toc generation next weekend.

[addyosmani]

Thanks again @rowoot!

I spent the morning playing around with re-theming the current setup and trying to make it more mobile friendly. Some pain points I ran into:

• I think it would be useful for us to drop Jade in favour of pure HTML (or markdown with partial HTML) for the layout. Whilst Jade is great I feel like in the long term we'll run into issues with contributors wanting to be able to help us improve the look and feel but spending time working around the Jade syntax.
• Broken URLs: another pain point I ran into was being able to test navigating to various pages locally before pushing to gh-pages - right now, nothing is absolute . At the moment I've added a base href hack to allow the URLs on gh-pages to navigate to the correct locations but locally you have to manually navigate, which makes testing difficult.
• We currently don't have a way to easily link articles written to specific contributors, who I think deserve credit. This could be added to the layout with meta data pulled in from somewhere. Part of me wonders if many of these issues could be resolved if we moved over to using DocPad (which we use in https://github.com/webcomponents/webcomponents.github.io) and supports multiple authors, markdown source and HTML layouts quite well. It could however be overkill but I'm open to opinions.

I would love to make it super easy for anyone on the team to checkout the site, run an npm install and just be able to preview/deploy what we have in just a few minutes. Any thoughts?

[addyosmani]

cc @zenorocha who updated our webcomponents.org setup to use DocPad. Zeno, do you have a rough idea of how long that took to get setup? :)

[addyosmani]

I should add, none of this is urgent. Just a nice to have :) I appreciate hugely everything @rowoot and c/o have done with the current setup so far. We can definitely continue using it for some time.

[zenorocha]

DocPad, Jekyll, Middleman... all these static generators are really really easy to setup. You could do it in few hours.

[michealbenedict]

Those pain points seem valid. If you think existing static site generators will solve aforementioned pain, I don't have any qualms building on top of it. My only constraint is that the end result should feel like a book with the ability to export to different formats.

[sindresorhus]

So, should we decide on one?

[zenorocha]

I think I found the best solution: Gitbook.

It's incredibly easy to setup and publish with the ability to export to different formats (PDF, eBook, ...)
They also have an editor made with node webkit.

Check:

• Live demo: http://zenorocha.github.io/book-of-modern-frontend-tooling
• Development branch: https://github.com/zenorocha/book-of-modern-frontend-tooling/tree/gitbook

[zenorocha]

The only drawback that I found is not having multiple levels of chapters (only 2 are allowed).

[michealbenedict]

@zenorocha gitbook seems interesting. I am curious, does it provide a way to pull in details of the markdown author so as to provide credits for them? It also doesn't seem to mobile friendly.

[zenorocha]

Seems to be pretty responsive for me:

[zenorocha]

What do you mean by pull in details of the markdown author? Do you want to provide credits below a page or something? That could be easily achieved by adding all the information you want in the markdown file itself.

[michealbenedict]

Whoops, will take back my mobile friendly comment -> it looks good on the phone.

What do you mean by pull in details of the markdown author? Do you want to provide credits below a page or something? That could be easily achieved by adding all the information you want in the markdown file itself.

Should have been more clear about this, I was referring to something similar to frontmatter-yml in Jekyll and other static site generators that lets you add extra metadata on the *md and display it as and when required in the template.

Nonetheless, I am currently going through the gitbook project to evaluate it further, it surely seems to fit our bill at first glance.

[zenorocha]

Got it!

I'm afraid they don't have that kind of thing, we'll probably need to add those stuff manually.
It's just several markdown files, no layouts or document attributes.

[addyosmani]

@rowoot I've been recently considering if we should reboot this project using GitBook too. Did you manage to get anywhere with your research? (I understand if not as this was way earlier last year).

[michealbenedict]

Hi Addy, i haven't made progress there.
I am currently on vacation and will be back on the 8th, Let me follow up
with you then.

Happy holidays to everyone :)

On Sunday, January 4, 2015, Addy Osmani [email protected] wrote:

@rowoot https://github.com/rowoot I've been recently considering if we
should reboot this project using GitBook too. Did you manage to get
anywhere with your research? (I understand if not as this was way earlier
last year).

Reply to this email directly or view it on GitHub
#48 (comment)
.

Regards,
Micheal Benedict Arul
Software Engineer, Twitter