Re-Working the CSS Almanac

CSS-Tricks Almanac has a new look!

I believe you are already familiar with this huge part of CSS-Tricks - Almanac (Yearbook). Here we publish reference documentation for CSS selectors and properties. We have only published this since ancient times…or at least since 2009 (when most of the original work was completed). In the age of web pages, that was almost the beginning of time. We can even call it the 1st year before responsive design (BR), or the 14th year after responsive design (AR).

You don't need me to tell you that writing CSS today in the 14th year after responsive design is very different from before. In short, Almanac has not kept up with the pace of CSS, which is much more than properties and selectors. In fact, we have been reluctant to modify Almanac because of how it is configured on the backend, and I'm sure I saw a ghost or two there when I touched it.

Now access to Almanac, you will find a wider range of CSS information, including the dedicated sections of pseudo-class selectors, functions and @ rules in addition to the existing properties and selector sections. We still have a lot of work to do (you should help!), but the architecture already exists and there is room to expand if needed.

This job is not easy and is as scary as I thought. Let me take you through some of the things I do.

Current status

We have proudly run WordPress since day one. There are many benefits to this, especially when it comes to templates. It may not be everyone's favorite, but I am very satisfied with it and resolutely devoted to it-Everything!

If you are familiar with WordPress, you know that content is mainly divided into two types: page and Article. The difference between the two is minimal—almost indistinguishable, as they both use the same editing interface. Of course, there are some nuances, but the main difference between pages is that they are layered, which means they are best suited to establishing parent-child page relationships, thus creating a well-structured sitemap. At the same time, articles focus more on metadata, and we can organize content by adding tags or putting them into category groups or any custom taxonomy that we can get at our fingertips.

Almanac is built on pages, not articles. Pages excel at hierarchical structures, while Almanac is a highly structured area with a typical site-map flow that just follows alphabetical order. For example, an entry for a CSS attribute, such as aspect-ratio, has the path: Almanac → Property → A → Aspect Ratio.

This sounds good, right? Not bad, but querying pages in templates is more difficult than articles, which have more metadata for filtering, etc. On the other hand, the page is not. (At least not obvious.) They are usually returned as structured objects because, you know, hierarchical structures. But that also means we have to create all these pages manually, unlike tags and categories that automatically generate archives. Creating an empty page for the letter "A", which is a subpage of the "Properties" page - itself a subpage of Almanac - feels too stupid, just to have a logical position to insert properties that start with the letter A. This must be done for both properties and selectors.

The real problem is that Almanac is inadequate. We want to post other CSS content there, such as functions and @ rules, but Almanac was originally built to display two sets of content. That's why we never posted anything else. This is also why the general selector and the pseudo selector are in the same bucket.

Expanding the space to accommodate more is the scope of my work and I know I will have the opportunity to styling along the way.

One template rule all

That's what it does. The initial approach was to use a single template to handle Almanac indexing and alphabetical pages that list selectors and properties. This is very clever. The page first checks whether the current page is an Almanac page located at the top of the page hierarchy. If it is this page, the template outputs the result of the selector and attribute in two columns on the same page.

This query is very impressive.

<?php function letterOutput($letter, $selectorID, $propertyID) {
  $selector_query = new WP_Query(array(
    'post_type' => 'page',
    'post_status' => 'publish',
    'post_parent' => $selectorID,
    'posts_per_page' => -1,
    'orderby' => 'title',
    'order' => "ASC"
  ));

  $html = '<div>';
  $html .= '<div><a>' . $letter . '</a></div>';
  $html .= '<div>';

  while ($selector_query->have_posts()) : $selector_query->the_post();

    $html .= '<details><summary>';
    $html .= '<h2><code>';
    $html .= get_the_title();
    $html .= '</code></h2>';
    $html .= '</summary>';
    $html .= get_the_excerpt();
    $html .= '<code>';
    $html .= get_post_meta(get_the_id(), 'almanac_example_code', true);
    $html .= '</code>';
    $html .= '<a href="'%20.%20get_the_permalink()%20.%20'">Continue Reading</a>';
    $html .= '</details>';
  endwhile;

  $html .= "</div>";
  $html .= "</div>";

  return $html;
}

This is really just half the code snippet. Note that it is only marked $selector_query. It will loop over $property_query again.

From there, the function needs to be called 26 times: once per letter in the alphabet. It requires three parameters, namely the letter (e.g. A) and the page ID of the "A" page (e.g. 14146, 13712), which are subpages of selectors and properties.

<?php echo letterOutput("A", 14146, 13712);
  // B, C, D, E F, G, etc.
?>

What if we are not currently on the index page? The template outputs a list of letters for the subpages of that specific part (such as properties). One template is enough.

Query subpage

I can modify the letterOutput() function to get more page IDs to display the letter pages of other parts. But honestly, I just don't want to do that. I chose to reduce the function to one page ID parameter instead of two, and then split the template: one for the main index and one for the "subpart" (if any). Yes, that means there will be more templates in my WordPress theme directory, but this is mainly for me personally and I don't mind. I can check the subpages I am on (the attribute index, selector index, @ rule index, etc.) and get the contents of these subpages separately.

What is another problem with the

function? All generated tags are sandwiched in the while() statement. Even if I want to parse the query by partial to preserve a single template schema, it's not like I want to place a if() statement anywhere in it without causing a fatal PHP error or notification. Again, I'm not interested in completely modifying the function.

Letter Archive

Posting empty subpages for all these sections of letters and then attaching them to the correct parent page is a lot of manual work. I know, because I did. Of course there are better, even programming ways, but converting content from pages to articles and starting from that perspective didn’t attract me, and I was in a hurry at the time. We are not always able to find a “ideal” way to do things.

According to WordPress, calling any of these letter pages “archives” is a misnomer, but that’s exactly how I look at subpages of different sections – if the content was built as articles rather than pages, that would be. If I have a pseudo selector section, then I will need the individual pages from A to Z, which in turn act as the parent pages of each pseudo selector. Three new sections, each with 26 letters, which means I created 78 new pages. marvelous.

You can access the letter page by using the breadcrumbs of the Almanac page (for example, this page of the aspect-ratio property) or by clicking the uppercase letters in any section (for example, this page of the property).

We never took these pages seriously. They exist for structure, but not many people will visit them. They are essentially placeholders. Useful, yes, but still placeholders. We are so unscrupulous about these pages that we never formally styled them. This is a CSS inheritance model that tells you what.

This is where I took the opportunity to polish it visually. I've been dealing with the huge and rough things in design since I returned to this job a few months ago. For example, the oversized title and thick shadows you see.

This is not my natural aesthetic, but I think it matches CSS-Tricks well… Maybe, just maybe, tears of joy will shed on Chris Coyier’s face. Maybe.

Navigation

Another enhancement has been added to the navigation displayed on the main index page. I replaced the letter navigation at the top with a navigation that takes you to each section and now we can edit the page directly in WordPress without bypassing development.

The only thing bothers me is that I hardcoded it instead of making it into a proper WordPress menu that I can manage from the admin interface. [Add a TODO to his to-do list. ]

Since I freed the Almanac index from the fully displayed selector and attribute list, I can really use it as an index for the large number of parts we are adding.

We may need to make the main page content less redundant with navigation at some point, but I think this is a good start from which we can build. Also, in terms of title, it is now more consistent with other "top" pages linked in the website's main menu, which won't be bad.

Oh, by the way, when we talk about navigation, the new section has been added to the existing left sidebar of the individual Almanac pages to help jump to other entries in any section without returning to the index.

Quick Reference

The last enhancement I'm going to mention is small, but I think it has a positive impact. If you go to any subpage of the index—i.e. selectors, properties, pseudo-classes, functions, @ rules—you can get snippets of code and advanced definitions for each entry at any time without jumping to the full page.

We have always placed great emphasis on the "quick access example" and I think this has helped this to a large extent.

"You can do [x]..."

Yes, there are still many opportunities to improve. My only goal is to change things enough so that what Almanac covers is more than just selectors and properties, and maybe some styling here and there. I also want to do a lot of things, maybe we will do it, albeit step by step.

What kind of thing? Well, first of all, that hard-coded index navigation. But more importantly, I want to continue pushing the main page. It used to play a huge role and I almost wiped it off. It would be nice to find a way to list all entries—for all sections—what we did when we had only two sections. This is what I plan to study.

Yes, we want to cover more CSS content there, such as common terms, media and user preference queries, probably specifications…you get it. Almanac is a resource for our team and just like for you, we refer to it every day. We hope it is full of useful information.

That's it.

You can now stop reading and go straight to Almanac for a virtual walk.

The above is the detailed content of Re-Working the CSS Almanac. For more information, please follow other related articles on the PHP Chinese website!