Proposal to rebuild as static site with modern tools

[sgoumaz]

I would like to give the website a thorough update to reflect and serve better today's browser capabilities and tools. What I have in mind at the moment is:

• Mainly, to replace the use of PHP for site structure with a Node.js-based static site generator (such as Metalsmith). HTML templates (such as Handlebars) and CSS preprocessing (such as Stylus) would be used for maintainability and reuse
• As a side task, to give the presentation a facelift, aiming to get closer to that of the book's fourth edition which I find delightful
• Then, to proceed with adding and/or updating the actual contents.

Does anyone have similar ideas? Would that be welcome as an update to webtypography.net or should I do it as a separate thing?

Any advice/feedback will be appreciated. I plan to do that as a little side project over the next few weeks and months.

[bchavezgd]

I like this idea, i don't know much about Metalsmith or Handlebars but now I have to look into them more in depth.

However I would suggest SASS over Stylus.

Stylus has almost too much flexibility in its syntax and core functions (like defining variables). If this does happen to get traction and moves forward there would need to be some sort of coding standards. whereas SASS can work like Stylus in its syntax, but separated by having 2 different extensions (.scss or .sass) this inherently limits the possible confusion, making for a better collaborative experience. I won't speak performace wise since i haven't enough experience with stylus to know if it's better or worse than sass as far as compiling and whatnot, but using libsas kind of eliminates the worry about slow ruby compiling.

that's my opinion though. if you do start this as your own side project, i'll probably watch what you do with it.

[allanlasser]

+1 for SASS

I'll raise my hand in support for Jekyll as a static-site generator. It has built-in SASS support and you can use the GitHub repo to host the static webpage.

[Rhincodon]

👍 for idea
Hi all. Just about week ago I finished a russian translation of this site. However he is still in the initial state and I have all articles in markdown format in russian. If you will create a new project or update existing, just add support for localization, and I easy close my separate domain and share my russian translate. (its already shared in repo) :)

[sgoumaz]

Thanks for the feedback.

I don't want to start an endless debate about the "right" tools but I'll try to briefly explain my proposal of Stylus and Metalsmith.

1. A simple and coherent stack. Regardless of their inherent merits, to me the popularity of Sass and Jekyll seems in big part due to their status of pioneers and the (then-?)popularity of Ruby which they're based on (ignoring libsass here). But today I think a web designer or dev can hardly get by without Javascript and Node-based tools, and I only see those becoming more present in the future. Taking JS and Node for granted, I want to avoid what I see as unnecessary heterogeneity.
2. Stylus over Sass. AFAIK Stylus does most of what Sass does and adds a few interesting features (like property lookup), with a more flexible syntax. I understand the latter can be considered both a pro and a con, but find that with sensible and consistent coding it's a non-issue (e.g. I do use colons and prefix variables with $ because I find it more readable). That Stylus' most often cited disadvantage vs Sass seems to be that flexibility, combined with it being based on JS, makes the choice quite clear to me.
3. Metalsmith. I'm not at all sure that Metalsmith is the best JS-based generator I could choose today, but it's got a very simple unix-y, plugin-based design, allows defining the build process in code logic (simpler to reason about IMO), and mostly relies on seemingly established conventions (like YAML front-matter). Altogether I think it's pretty simple to grasp and tweak, and easy to swap for another generator.

I hope the above makes sense. If @clagnut doesn't think so, unless I missed something major I'm inclined to go with a separate project on those bases anyway.

[clagnut]

I'm not completely up to date on the merits of Metalsmith, Stylus, etc. Despite their running on JavaScript, I presume the site itself would not require browsers to have JavaScript enabled to view content and style? That would be a no-go for me.

Personally I'm far more familiar with SASS and plain old CSS, but that may be just me.

My main hope in open sourcing the project was less a rengineering of the site, and more opening it up to the world to keep the content up to date, and finish the remaining applicable guidelines. Secondarily to that, to improve the design particularly with a view to making it responsive, and potential work offline too.

If improving the design means using a CSS pre-processor then that's fine, although my general feeling is that they are used by default rather than out of actual necessity. (There's not too much wrong with regular CSS for a simple site in my opinion.)

[sgoumaz]

No the site itself wouldn't require JS, the JS stack is purely for generating the site files. Those files being static also means the site can be easily downloaded and viewed offline too (if that's what you mean with "offline").

I propose to start with the reengineering because in my perception it will make maintaining and adding content (and updating the design) easier. The CSS preprocessor question is not primary for me; I could start with Stylus, then based on the code we can decide whether it really adds value (and easily revert to plain CSS if not).

Anyway, if the general idea is accepted I'll probably proceed with a fork and we can discuss more and adjust stuff later.

[yatil]

I’d prefer having a jekyll solution for the simple reason that the page can be edited directly on GitHub by everyone that can write basic markdown. That should lower the barrier to add content. It is also directly compiled by GitHub an can run on their servers which means there would be no compile & upload step involved.

[sgoumaz]

@yatil Thank for that... I hadn't realized Jekyll was so tightly integrated with GitHub pages, and now I'm reconsidering what I said above. Even if plain Markdown didn't suffice for the content (I hope it does), being able to just work directly on the gh-pages branch and skip the compilation step is a big advantage. Hmm... I think I'll let a few days go by but I'm probably convinced.

[sgoumaz]

In case someone wants to move on with this: please go ahead and accept my apologies.
My personal schedule turns out to be much tighter than initially envisioned; I first thought I'd still just do the switch to Jekyll but it's obvious now that I won't do anything before months (part of the reason is that I'm moving to another hemisphere).

[nevanscott]

@clagnut I don't know if you'll agree, but I see a potentially large upside to reengineering the site, so I went ahead and took a stab at it myself.

Here's my code and here's a hosted version of the site, running off my gh-pages branch (which is only altered by having a CNAME file so that Github will serve it to that URL).

My goal was to move the site from PHP-based to Jekyll with a minimal amount of impact on the site itself.

Some pros to this approach:

• As @yatil mentions above, the site could be hosted on Github Pages in such a way that folks can suggest updates to the content using only the Github website, without necessarily having to know how to get a local PHP version of the site running on their machines.
• I think it's better to make this under-the-hood move first, before tackling any other engineering-related issues, such as making the site responsive (see Scaling and responsivity #10) or using Sass, which I think are separate concerns. Since @bchavezgd Proposal to rebuild as static site with modern tools #18 (comment) seems to like the idea of using Sass and as @allanlasser Proposal to rebuild as static site with modern tools #18 (comment) points out, Jekyll and Github Pages have built-in support for processing it, this would at least allow for the possibility of making the move.
• There would also be flexibility to start migrating the posts themselves into a format like Markdown, which might be more inviting for folks to edit.
• Since the site is served as static HTML, it's basically as fast as one could hope for.

Downsides right now:

• Github Pages doesn't allow for plugins to be used with Jekyll. The only functionality I haven't been able to recreate without a plugin is the PHP function to prevent orphans. Given the nature of the content, this seems a shame to lose. It would be possible to get the site set up in such a way that a plugin could be used, but I think there would then be diminishing returns given the complexities involved. Hosting on Github Pages is very straightforward by comparison. If anyone else has any ideas on this, I'm all ears.
• It might be trickier for folks to set up access to the web fonts from Fontdeck when developing locally.

Since the goal with having this thing be open-sourced is to invite content-based contribution, I really think this is worth taking a shot on to see if it makes contributing more accessible.

[nevanscott]

Another advantage that I forgot to mention: parsing for code blocks, which could allow for color-coding, if that's an interesting possibility to anyone besides me.

[clagnut]

Not a CMS because I'd rather keep the content separate from any instance of
a website.

On 2 July 2015 at 17:07, Allyson Alves de Souza notifications@github.com
wrote:

Why not a CMS?

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

Travel back to the future of design at http://dconstruct.org/
Back my web typography book at http://kck.st/1Ru0BlA