About Page

[mayamcdougall]

Work in progress for an About/Overview type page. Something users can read to learn what Pico is before moving on to the Docs (which begin with "Install" instructions).

http://smcdougall.github.io/Pico/about/

Currently, any notes I have are inline. Any bulleted items are notes. I'll remove them as I fill out the page more.

[mayamcdougall]

I've given it a place on the site's Navigation because I think it's an item that belongs there. I think I've done it properly, but let me know if I've messed up. As far as I could tell (I searched for Nav: in Atom), Nav: 3 was unused, so I bumped the Docs up to 3 and made "About" the new Nav: 2.

[PhrozenByte]

You mean picocms.org? Sure, see http://themes.iki-bir.com/webpaint/multipage/full/

[mayamcdougall]

I might just be blind, but is there any documentation anywhere about how to use Webpaint? I've seen the demo site before, but is there a guide or readme on to how to use its features? Like what elements or classes need to be used and how they are styled.

[PhrozenByte]

Unfortunately not (as far as I know). You'll need to read and adapt the HTML sourcecode manually 😒

[mayamcdougall]

Okay. I'll poke around and see what I can come up with.

[PhrozenByte]

Maybe. We should emphasize advantages, not disadvantages by e.g. highlighting Pico's extendability and small footprint (what already implies that a user needs to make his "hands dirty"). However, we shouldn't make empty promises, so a sentence like

Pico is not a turn-key solution.

is completely fine.

[mayamcdougall]

Yeah, it's a difficult line to walk: between "Pico requires a little bit of work" and "No, wait, come back, it's really not that difficult"

[mayamcdougall]

Question about YAML.

I just finished making it so that we can use Markdown inside the image descriptions (for links, but ultimately it could be used for any formatting). It screwed up the indentation a little in fancyboxtemplate.html, but it makes writing descriptions easier.

Will writing Markdown work okay in the YAML section without breaking things? From what I've seen before, it seems like everything after the colon is captured/escaped, but I've never really tested that. Are there any special characters, etc, that will break it?

A simple "yes, it should be fine" or "no, watch out for blank" is enough. 😉

I really need to properly read up on YAML sometime anyway. 😒

[PhrozenByte]

Instead of <div markdown="1"> you can use {{ image.headline|markdownify }}. Markdown in YAML shouldn't be a problem, you just need a way to let Jekyll interpret it as Markdown.

[mayamcdougall]

Instead of

you can use {{ image.headline|markdownify }}

Cool, that should fix the indentation in fancyboxtemplate.html too.

At the moment, without that quirky indentation (the markdown="1" tag and contents can't be indented), the </div> gets treated as Markdown text and the entire rest of the page goes into the Fancybox description. 😆

[PhrozenByte]

btw: The Jekyll docs say that it's {% include footer.html param="value" variable-param=page.variable %} and that the variables can be accessed using {{ include.param }} resp. {{ include.variable-param }} - see https://jekyllrb.com/docs/templates/#includes. However, this has never worked for me either 😉 Maybe it works now since GitHub Pages switched to Jekyll 3 recently...

[mayamcdougall]

That would explain some of the difficulty I'm having. I had to break the gallery variable out into it's own line to get the page to build, but then the for loop wasn't running.

I was using the syntax I found here: https://help.shopify.com/themes/liquid/tags/theme-tags#include

Didn't realize it was different.

[PhrozenByte]

Jekyll and especially Liquid's docs are a pain in the ass... I can't say anything else about it...

[PhrozenByte]

btw: I'm always online on Freenode IRC. I'm using a ZNC bouncer, so I'm not necessarily reading all messages immediately even when IRC says I'm online, but I'll answer as soon as possible. I've stumbled on many flaws and mischiefs of Jekyll and Liquid in the past, so, before you despair, please don't hesitate to ask. I was very close to this point more than once, Liquid can be really annoying... 😒

[mayamcdougall]

Here's my logic on the issue (from IRC).

First, Fancybox uses a "rel" html attribute to determine which images are in the same group. These grouped images have thumbnails and next/prev buttons, regardless of where they are on the page. As long as they're in the same "ref" group, they're connected together.

In the current implementation, its value is being determined by include.gallery, which we're also using to determine what set of images to use. In my previous implementation, you could choose not to assign the relation variable and have an ungrouped image.

So I'd like a way to have a stand-alone, ungrouped image with a blank or missing "rel" attribute.

One way to do this would be to create a new gallery for each stand-alone image. While this works, it feels like it's a lot of extra YAML, and a lot of room for error.

Another way, the way I was planning, is to have a dedicated "standalone" or "default" gallery that holds ungrouped images. This could be done in several ways, for example with a hardcoded name like "standalone" or with some other variable that causes fancyboxtemplate.html to omit the rel attribute.

At the moment, I've made that the standalone gallery, but it's subject to change as I further the implementation. (Actually, I've removed it for now, for the sake of a proper commit.) The idea would be that maybe you'd call the image with:

{% include fancyboxtemplate.html gallery='standalone' index="2" %}

I guess that would require a change to the flow of fancyboxtemplate.html and its loop though.

What do you think though? Would it be better to have a new gallery for each image? Maybe it would be easier... 😕

---

As far as the carousel goes, my plan is to see if I can wrap the carousel container code in a conditional statement so that if you're using "carousel mode" it will use that and if not it'll default to a "standard mode" for single images (trying not to say "standalone" because that's not what I mean here... since you could have a non-carousel image that is part of a group).

Ultimately, this should be the "end-all be-all" for all future images, containing different styles of "portfolio", "carousel", and standard (and/or stand-alone) images. It should be able to handle everything from a single inline image in the Docs, to a detailed portfolio of themes. 😃

[mayamcdougall]

@PhrozenByte Oh, and thanks for working on this with me today. 😄

It's coming along nicely!

[PhrozenByte]

I would like to leave this completely up to you. Personally it wouldn't bother me to create standalone1, standalone2, … "galleries", so you don't have to change your current code, but choose the solution you think is best. I don't see a reason for fancyboxtemplate.html to explicitly support a single image, a "gallery" with just a single image results in the exact same HTML code, but, as said, this is completely up to you 😃

[mayamcdougall]

Well... the way Webpaint implements most of these involves several container <div>'s, an unordered list and list items. It's great if you want to use one of their designs, but it's a lot of extra code if you've only got one inline image that you wanted to use with Fancybox.

What I've been trying to do so far is separate all this extra stuff from the images themselves. All I wanted was thumbnails! 😆

I think it's all unnecessary for this About page, but, I do like the challenge. 😉

Since you've mentioned other ideas for it in the future, I might as well write the code for it now. I'm already half-way there after all. I do like the styles the Webpaint offers, it just didn't seem necessary for our website before.

I'm going to let the code take the reigns for now. I'll finish implementing the carousel bits and see where that takes me. Once I see what the finished code looks like, it may reveal an entirely different method of handling it anyway.

I'm out of time to work on it today, but I'll probably work on it sometime tomorrow morning.

[mayamcdougall]

So some quick feedback while I'm working on it:

1. The docs layout isn't wide enough to accommodate the carousel because of the one-fourth div containing the Table of Contents. This can obviously be worked around, but it makes the carousel feel really cramped. It would only display two images and the heading box.

2. Markdownify is nice... but it's adding extra paragraph tags to everything (headers, description paragraphs, etc). This doesn't seem to happen with markdown="1" because in that case Kramdown(I think?) is aware of the surrounding HTML.

I'm a little tired this morning, so it's going a bit slow. I spent more time than I want to admit staring at the wrong file. I was comparing a static version of portfolio with a post-javascript portfolio2 wondering what kind of "black magic" the Javascript was doing to generate the carousel. 😖

(Once I figured out my mistake, implementing the carousel was easy though. 😆 )

[mayamcdougall]

sigh The carousel width is hard-coded in several places. The carousel, wrapper, etc, each have a set width value in the regular styles, as well as in the various "responsive" size styles (in another style sheet). I'm not going to have time this morning to track down all the locations and do the math to make the carousel look good on the docs pages.

I've got a temporary style set up for now. It only applies to the full-size version, and will still look broken if you resize the window below a certain resolution. I may also change it later since I didn't calculate the new width, I just lowered it until it fit. If you get a chance, go check out what the carousel looks like:

http://smcdougall.github.io/Pico/about/

Keep in mind, the carousel uses a fixed size for images, so that's why all the thumbnails look squashed.

---

Also, the "overlay" style looks completely broken in the carousel. Since your mouse typically moves faster than the carousel scrolls, you trigger all the overlays as you scroll. It just doesn't work together design-wise, so I'm not going to pursue implementing that.

It'll have its own special mode when I recreate the regular portfolio style anyway.

So there will probably be four options:

• Carousel
• Magnify (Just the magnifying lens, without the carousel)
• Portfolio
• Overlay (Just the overlay, without the portfolio)

---

Actually, looking at it, portfolio is pretty intense. There's a lot more to it than I thought. Maybe it'll be it's own file. 😕

[PhrozenByte]

1) Hmm... Actually I still like the style, even with just two images. It provides some sort of "separation" to the content and lets it look like a gallery (what IMHO wasn't the case before, the images were just "there"). I was thinking about letting the "category box" flow into the TOC-reserved space on the left, but this made it look "too important"...

2) You can combine markdownify with remove, see e.g. https://github.com/picocms/Pico/blob/gh-pages/_includes/pageHeadline.html#L4

Off Topic: However, letting the "category box" flow into the TOC-reserved space on the left made me wonder if we could adapt this as replacement for <h2> elements (<h2> only!)... What do you think?

[PhrozenByte]

You don't have to mess around with various responsive sizes, simply use calc():

@media only screen and (min-width: 960px) {
    .category-wrapper .carousel-wrapper {
        width: calc(100% - 280px) !important;
    }
}
@media only screen and (max-width: 959px) {
    .category-wrapper .carousel-wrapper {
        width: 100% !important;
    }
}
.touch-carousel {
    width: 100% !important;
}

Add to style/css/ie8.css (who the hell cares about IE8? 😄):

/* I'll edit this post, VirtualBox doesn't like to boot my windows VM right now ^^ */

Low responsive sizes make the category look like a header, thus I suggest to add the following additional rules:

@media only screen and (max-width: 959px) {
    .category-wrapper .category-info {
        background: #efefef;
        padding: 25px;
    }
}

[mayamcdougall]

I had half of this reply typed earlier but ran out of time. You left another comment though, so you get a GIANT reply. 😜

I don't know, I feel like it needs to lose the heading. It just takes up so much space and doesn't really do anything productive, at least, not in this case. Since none of the galleries have enough images that they need to be hidden, I feel like that heading box is wasting space that was better used before. I also liked how the larger galleries before served to break up the content.

I agree that they were "just there" before, but I liked their arrangement. The three images in the workflow group had a nice, <hr> like effect. Not only did it mark the end of the intro, but provided example screenshots before moving on to the next section.

It still does this, but, as I said, it feels like wasted space to have that heading there instead of just showing all three images.

I also liked the 2x2 grid I had with the themes gallery. It was big enough that you couldn't miss it, but not so big that it interrupted the article.

The only image I really don't like is the first image of Pico's default theme. It's the very definition of "just there". At the very least, I think I'll give it some more margin so it's not being eaten by the text. The bigger problem is that the image is mostly white and blends in too much. The other images have darker colors or window borders, so it's not as bad on them.

If I can't find a better solution for it, I may just retake that screenshot and capture the 1px window border as well (I'll keep the title bar cut off though, no need to waste space. 😉 ).

2. You can combine markdownify with remove

I'll check that out.

Off Topic

I like it, but I think it might cause more trouble than it's worth. I think the appearance would need to be refined a bit, and I'd worry it would cause the page content to "run together" between sections. Also, it could overlap with the Table of Contents if it was too high on the page.

I think what I imagine when I see it is a box that follows along the side of the page to remind you what section you're on. When you hit the next section, it would be pushed out of the way by the next heading.

I can't think of a good example of this, but on a quick search, I found this example. Imagine that, but with a box on the side. Not saying we should do that, just trying to describe the idea.

---

simply use calc()

O_O

I had no idea that was even a thing. I have wanted to do that so many times... how have I not heard of that?

who the hell cares about IE8?

Yeah, I haven't even looked at that file. I didn't really plan to either. 😆

I gave up trying to accommodate IE a few years ago. Modern CSS and HTML5 just have so many useful and fun tricks to try to worry about compatibility issues.

Low responsive sizes make the category look like a header

Wow, it really does. When I looked at it earlier, I actually thought it vanished altogether... 😒 It really blends in.

[mayamcdougall]

Way to merge that while I'm taking too long to write a comment. 😒

Edit: So what did you do? Merge it and then revert it? 😕

[PhrozenByte]

The merge was a mistake, accidentally did a git push instead of a git push fork. Seems like I've fucked up the PR with that and GitHub isn't able to restore the old state... 😒 Sorry for that. Can you open a new PR please?

A answer to your comments follows later.

[mayamcdougall]

Huh... that's odd, you'd think you could reopen one. Perhaps if you did a hard-reset of the Pico repo? (Maybe that's what you did, idk, "gh-pages is now 78e1f4e" isn't very specific).

Then again, I guess a PR is something GitHub specific, and probably not tied directly into Git.

Either way, this thread is getting a little long and I think most of the older comments have been addressed already. I'll open another one. 😉