search

asciidoctor / asciidoctor.org

:globe_with_meridians: Asciidoctor project site. Composed in AsciiDoc. Baked with Awestruct.
https://asciidoctor.org
Other
323 stars 803 forks source link

Upgrade to Foundation 6 #564

Open ggrossetie opened 8 years ago

ggrossetie commented 8 years ago

@mojavelinux is this something you were planning to do at some point ? I was looking to improve the document control bar and Foundation 5/6 already have builtin components that would fit really well:

I gave it a try but before spending more time on this, I want to make sure that this is part of the plan :wink:

mojavelinux commented 8 years ago

Upgrading to Foundation 6 is definitely part of the plan. There are several steps I think we need to accomplish before we're ready to make that switch:

What makes this upgrade really tricky is that Foundation switched from em to rem units between Foundation 4 and Foundation 5. That meant having to comb through every styled element to check for differences and find an equivalent expression when they didn't match. That's a lot of what I did in https://github.com/asciidoctor/asciidoctor-stylesheet-factory/pull/23. It was really painstaking work. Regardless, we need to make the switch or else we're stuck on this side of the mountain.

The reason for incorporating the embeddable stylesheet is to avoid having to maintain the stylesheet in two different places. That has caused a huge maintenance overhead since they are perpetually diverging. I want the site styles to be additions to the default stylesheet, not duplicating it.

The embeddable stylesheets are also needed for all our preview tools, such as the Atom plugin and the Chrome extension.

I haven't tested whether Awestruct can accommodate Foundation 5/6. It's certainly going to add an extra step since it requires the use of Bower.

mojavelinux commented 8 years ago

I'd say that we can use all the work you did aside from the stylesheet. I say that because I really want to trim the stylesheet down to only the parts that deal with the site structure. Any styles related to the content should be imported from the embeddable stylesheet.

In other words, there should be a clean separation between styles for the content (which are imported) and styles for the framing around the content (navigation, footer, grid, etc). Otherwise, we are just losing our minds ;)

mojavelinux commented 8 years ago

One way to accomplish that before we generate the embeddable stylesheet is to simply take the default stylesheet (that is upgraded to Foundation 6), cut out the parts related to framing around the content, and drop that into the site to be included. That at least gets us out of the business of regenerating those parts. In other words, we treat it sort of like the stub of an interface.

ggrossetie commented 8 years ago

Thanks for the detailed action plan :+1:

Which is better to do first, produce an embeddable stylesheet for Asciidoctor or upgrade the default stylesheet to Foundation 6 ?

You did some work on embeddable stylesheet and on Foundation 5, what work is remaining ?

mojavelinux commented 8 years ago

Having a plan is the first step to a successful journey. (That must be a quote by someone).

Which is better to do first?

Upgrade the stylesheet factory (and hence the default stylesheet) to Foundation 5, then Foundation 6. All other parts depend on getting that infrastructure in place, so we should start there.

Let's start by getting https://github.com/asciidoctor/asciidoctor-stylesheet-factory/pull/23 finalized. I just resolved the merge conflict, so we can proceed.

I'll explain the process I'd use to validate it. Hopefully this will give you an idea of what needs to be done.

  1. I'd take the AsciiDoc User Guide (in the benchmark/sample-data directory of Asciidoctor core) and convert it using the stylesheet from 1.5.4.
  2. Then, I'd convert it using the stylesheet from the PR. (build the stylesheet using ./build-stylesheet.sh)
  3. I'd then do a side-by-side comparison.

For the comparison, perhaps we can use one of these tools to help us:

What we are trying to do is make sure we haven't inadvertently introduced any rendering bugs. If we setup a little script, this should help us for all future upgrades and style changes as well.

The trickiest part about this upgrade is the switch from ems to rems in a number of places. If we determine that rems are causing a problem, we can switch back to ems using the rem-calc-to-em function I created. That's the equivalent of the old emCalc function.

I've been using the AsciiDoc User Guide for comparisons, but it might be better if we start developing a kitchensink example that more concisely exercises each of the visual components. It could merely be a trimmed down version of the AsciiDoc User Guide and/or Asciidoctor User Manual. The key is for it to flow like a normal document, not just stack all the blocks one on top of the other.

mojavelinux commented 8 years ago

I'd say that this upgrade is top priority right now because it's holding up a lot of things. We can schedule it as part of the 1.5.5 release.

mojavelinux commented 8 years ago

@Mogztter I really appreciate your help on this. As you can see, maintaining the stylesheet is no small task. However, I think we can find ways to make it easier. Visual testing would definitely help with that, as well as some more details in the README about what we're doing (to help our future selves more than anything else).

jcayouette commented 6 years ago

Any update yet on the upgrade to foundation 6?

mojavelinux commented 6 years ago

We're going to be taking a different approach to get there. We're pulling all the docs out of asciidoctor.org into docs.asciidoctor.org, which will be built with Antora. It will have it's own UI, which is not based on a CSS framework. That leaves asciidoctor.org with just the introductory pages and ecosystem catalog. For that, we will either start over with Foundation 6 or consider using Bulma (like antora.org).

In other words, I don't want to spend time upgrading the existing site to Foundation 6 when we're likely rebuilding it anyway.