Problem/Motivation

Default core markup (aka Stark) is messy. For example, theme_item_list() includes:

  $output = '<div class="item-list">';
  if (isset($title) && $title !== '') {
    $output .= '<h3>' . $title . '</h3>';
  }

which is arguably unnecessary and superfluous. Given that we are converting the entire core markup to Twig in the new theme system, this presents an opportunity to remove things that may not be necessary. Whether Twig makes it into D8 or not, we'd like to see a big clean-up in Stark, and improvement of Bartik.

We've been using the "theme system cleanup" tag to track things like this in general, but this issue could establish some directions and goals for the themes.

Proposed resolution

Goals for core themes: Make Stark as semantic as possible; Make Bartik a better prospective base theme

After some discussion at the 2012 BADCamp Twig Sprint we expressed a desire to have core default markup (i.e. what Stark provides) to be as barebones as possible. Thus, the target audience for using stark would be those themers who truly want to start with a clean slate, and don't wish to have to work backwards to reach that slate.

Accordingly, we'd like to see Bartik become a better prospect for a base theme so that it is easy to start with and build from.

For example, move some of the functionality from theme.inc to Bartik's template.php. Or have stark contain no regions (aside from content) by default.

An amazing inspirational video from mortendk.
http://www.youtube.com/embed/2LwMn9oHOx8

There are three major Drupal initiatives that change the markup:

Remaining tasks

Needs change notice

Patches (please review / revise)

TODO (please write patches)

Discuss (please decide what todo)

User interface changes

None, at the moment. Regions may disappear in Stark.

API changes

TBD

#1843798: [meta] Refactor Render API to be OO
#1804614: [meta] Consolidate theme functions and properly use theme suggestions in core
#1804488: [meta] Introduce a Theme Component Library
#1499460: [meta] New theme system
#1087784: Add new theme to Drupal 8.1.x or another minor version
#1854344: [meta] Goals for core themes: Make Stark as semantic as possible; Make Bartik a better prospective base theme
#1854672: remove seven_node_add_list() from core (update the markup in theme_node_add_list() instead)
#1842140: Remove title and wrapper div from item-list.html.twig
#912458: Design Initiative: Core theme selection and development process
#737136: Put together a list of must-have features for new core themes and set a final deadline for implementing them

#dreammarkup

One of the goals of the Twig initiative is to improve the markup in core. Many contributors are still involved continuing to converting templates to Twig, and now for the completed templates we can begin to improve the markup according to following principles.

Markup principles

Class names

Class name convention is based on CSS architecture (for Drupal 8) documentation. One of the pitfalls of current CSS is that we have something like .menu li a but for the new convention is should be .menu__link. This will reduce the weight of the selector and will make themes cleaner.

The id attribute

It is recommended to avoid the id attribute for styling purposes. Classes should be used instead to apply styles to an element. However, the id attribute is needed for other purposes. In general, avoid removing ids from the markup itself unless you are sure they were only used for CSS.

Markup

Keep in mind that one of our principles is to start from nothing. That means using as few HTML elements and attributes as possible in core. If Bartik needs a div around something for its own purposes, that div tag should be added in the Bartik theme, not in core.

When re-writing markup try to be aware of the repercussions on other code, but don’t let them stop you. See the action steps below for how to deal with changes that affect existing CSS, JS, etc.

Action steps

1. Find a file.

Either choose one of the completed Twig templates (from the list above) that you wish to improve. Search for existing issues tagged "dreammarkup" that pertain to the template file.

2. File an issue (if none exist).

Add your issue to Twig sandbox. In issue summary provide the path to the file, link to this meta issue and a code proposal ( optionally with a patch ) for a better markup. Add dreammarkup tag. Also update this issue summary above with your issue id.

3. Add link to your issue here under 'Issue list' section.

In addition to the tag, this is a good way for us to monitor progress via this meta issue.

4. Write and post a patch.

Mark your issue needs review if you have a patch or idea, or needs work if you need to work on it or it is in progress. Make sure to justify your changes.

5. Check for related CSS and Markup changes.

If (and probably because) markup changes can break all the CSS - check files in which this markup is used, and if possible provide patch for CSS fix specific for your changes. Do not fix spaces or tabs - that is the job of CSS cleanup initiative: #1921610: [Meta] Architect our CSS

Comments

oresh’s picture

Issue summary: View changes

links fixed.

oresh’s picture

Issue summary: View changes

Steps added

oresh’s picture

Issue summary: View changes

markup change

oresh’s picture

Issue summary: View changes

code fix.

c4rl’s picture

Issue tags: +theme system cleanup

Tagging

c4rl’s picture

Issue summary: View changes

Twig templates section added

oresh’s picture

Issue summary: View changes

twig rtbc link added.

oresh’s picture

Issue summary: View changes

Twig templates meta issue link added

oresh’s picture

Issue summary: View changes

markup changed :) it's a markup issue.

c4rl’s picture

Issue summary: View changes

Formatting

c4rl’s picture

Issue summary: View changes

Clarify

oresh’s picture

Issue summary: View changes

Issue list items added.

oresh’s picture

Issue summary: View changes

markup fix.

jenlampton’s picture

Issue summary: View changes

expand

ry5n’s picture

#id is still the fastest way to select elements either in CSS or JS, let's not remove them without good cause.

The CSS coding standards advises never using id as a CSS hook. The performance difference between id and class is basically nonexistent, and selector performance in general is near the bottom of the list of bang-for-buck performance optimisations. I’d like to stick to the new CSS standards and use single classes as much as possible.

The example given of the new selector style is not great: .menu__list-item__link. A better replacement for the original selector .menu li a would be .menu__link. I need to add some clarifications to the standards based on what I’ve learned in the sandbox, but my rule of thumb is to make a class name only as ’ugly’ as needed for clarity. Class names do not need to encode markup structure, they only need to name things unambiguously. In general, prefer .menu__link over .menu__item__link.

Don't use headers for elements that are by default hidden

I believe many of the hidden headings in use by Drupal are there for accessibility reasons, which means the heading tags supply import semantic information to screen readers. I would hesitate to change this pattern unless we get the OK from our accessibility team.

ry5n’s picture

BTW +100 to this issue. Thanks @oresh for creating it.

ry5n’s picture

Issue summary: View changes

item list

oresh’s picture

Thanks ry5n! I've changed the description.
I was thinking that the class name was kinda ugly, but decided to stick to DOM structure. Your variant is cleaner and more readable.
I'll try to post an article about this issue to Drupal planet - hope to get some more attention to it.
While 'more back-end' front-end developers are involved in Twig initiative, we should try to make the Markup in parallel asap if we want it to be in core until the release.

oresh’s picture

Issue summary: View changes

Changed class names.

ry5n’s picture

Fantastic. Thanks @oresh. I’ll be working on this again too and giving it everything I’ve got.

falcon03’s picture

Just a quick note: please, do not remove any hidden content from the markup.

Anything wrapped in a div/span/heading which the "element-invisible" class is assigned to is there to improve Drupal pages acessibility. Unfortunately I am in a hurry right now, but I'll provide more detailed feedback as soon as possible.

ry5n’s picture

What @falcon3 said, but also not changing the tag either. Basically we should not touch that screen-reader markup except with a firm understanding of the a11y implications.

About the ‘start from nothing’ principle: this is really important. However, it applies most to core markup, i.e. the markup coming out of core modules and libraries, and of course the Stark theme, since it is designed to simply present raw core output. However, base themes (if ever in core) might want/need to provide additional markup/CSS/JS to fulfill their goals as something more convenient to build on. Finally, purpose-built core themes such as Seven will need to do the most building-up from the lean base markup envisioned for core modules.

My point is that not all core markup should be stripped down to ’nothing’. The more generic and extensible the markup needs to be, the more basic and clean. The more specific, the more it should simply be well-architected for that purpose.

ry5n’s picture

Issue summary: View changes

grammatical error fix.

carwin’s picture

Issue summary: View changes

Fixed a minor typo.

oresh’s picture

Issue summary: View changes

video

oresh’s picture

Issue summary: View changes

video ifrmae

oresh’s picture

Issue summary: View changes

image instead of iframe

oresh’s picture

Issue summary: View changes

ohhh those images :(

c4rl’s picture

Issue summary: View changes

Attribution

oresh’s picture

Issue summary: View changes

new list added.

oresh’s picture

Issue summary: View changes

Added new issues.

oresh’s picture

Issue summary: View changes

steps improved.

oresh’s picture

Issue summary: View changes

link fixed.

barraponto’s picture

Upon visitting #1843774: Convert views/views_ui/templates/views-ui-display-tab-setting.tpl.php to Twig I noticed the usage of non-breaking space without any explicit reason for it. Grepping for nbsp showed up quite a few uses, including form.inc and theme.inc (not to mention js plugins and vendored PHP). Shouldn't we think about nbsp usage? What is the rationale to add it or avoid it?

barraponto’s picture

On the invisible headers topic: it builds the document layout which is quite important for accessibility and semantics. See http://www.netmagazine.com/features/truth-about-structuring-html5-page for more on it.

Also, when it comes to clashing element ids, we can always use drupal_html_id to avoid the clashes... althought I'm not sure what's the use of an id attribute if you can't rely on its value. Maybe for javascript behaviors, passing the generated id as a setting -- although I didn't see that pattern around.

barraponto’s picture

Issue summary: View changes

user name fail

oresh’s picture

@barraponto, thanks for the review. the article is just amazing.
I've removed the 'header' section, cause I don't find it necessary at all now.

About the ID's - they are used by JavaScript, and sometimes by CSS (yep, sometimes it is).
Secondly i like to keep the representation of unique elements on the page by their id attribute, so you can define - 'ok, this element should only be used once', or something like that. Anyway leaving or deleting ID is not critic for most of the time, so we provide them by default, but themers decide themselves to use or not the id :)

oresh’s picture

Issue summary: View changes

removing header section

ry5n’s picture

Issue summary: View changes

Update instruction sections for id and markup to clarify stance on ids (their purpose, when to remove, recommendation to not use in CSS). Corrected some punctuation and typos.

scor’s picture

Issue summary: View changes

add link to node markup

LewisNyman’s picture

We discussed our approach for each one of these issues. We think we can commit each patch separately, without sandboxing.

  1. Improve the theme function markup
  2. Check Seven and Bartik to see if the reduced markup breaks either theme
  3. Move the old theme functions and template into the broken themes so we don't have the change the CSS right now.
c4rl’s picture

I created #1854344: [meta] Goals for core themes: Make Stark as semantic as possible; Make Bartik a better prospective base theme before we started talking about dreammarkup; it's possible that it may be a duplicate and we should combine these. Thoughts?

c4rl’s picture

Issue summary: View changes

wrong issue # for node.html.twig

ry5n’s picture

@c4rl We should probably merge them. I think #1854344: [meta] Goals for core themes: Make Stark as semantic as possible; Make Bartik a better prospective base theme has a really good overview of the goals. This issue is more focused on the particulars of implementation. Should this one be made a sub-issue of that? Or should Dream Markup be a sub-section in 1854344?

ry5n’s picture

Issue summary: View changes

add related issues

mortendk’s picture

Issue summary: View changes

added link to page.html.twig

killtheliterate’s picture

@c4rl these issues look to like duplicates to me. I think combining them makes sense.

killtheliterate’s picture

Issue summary: View changes

Remove link to Twig sandbox now that the templates are in core :)

jenlampton’s picture

Issue summary: View changes
jenlampton’s picture

Issue summary: View changes

related issues too

jenlampton’s picture

Since there are already a bunch of people following this issue, I closed #1854344: [meta] Goals for core themes: Make Stark as semantic as possible; Make Bartik a better prospective base theme as dupe.

I did also move over the summary, so everything we need should be here now. :)

jenlampton’s picture

Issue summary: View changes

add title

jenlampton’s picture

Issue summary: View changes

comment

jenlampton’s picture

Issue summary: View changes

meter, ha

star-szr’s picture

Issue summary: View changes

Remove dupe breadcrumb issue

mortendk’s picture

Issue summary: View changes

added in links to proposed patches

mortendk’s picture

Issue summary: View changes

added more issues

jenlampton’s picture

Issue summary: View changes

up

jenlampton’s picture

Issue summary: View changes

up

jenlampton’s picture

Issue summary: View changes

up

jenlampton’s picture

Issue summary: View changes

up

jenlampton’s picture

Issue summary: View changes

update

jenlampton’s picture

Issue summary: View changes

up

jenlampton’s picture

Issue summary: View changes

more

jenlampton’s picture

Issue summary: View changes

more link

jenlampton’s picture

Issue summary: View changes

dedupe

jenlampton’s picture

Issue summary: View changes

up

joelpittet’s picture

Issue summary: View changes

Updated issue summary.

John Pitcairn’s picture

Issue summary: View changes
LewisNyman’s picture

Issue tags: +frontend
LewisNyman’s picture

This needs an issue summary update for a post-banana world. Or we could just close it.

mortendk’s picture

i think we should close it - The banana fixed all the things.
Hopefully we can also stop the silly idea's that theres a one way of doing markup

sqndr’s picture

Status: Active » Closed (duplicate)

There hasn't been any work in the last year. As mentioned by Lewis and Morten, we should close this issue. Banana fixes "all the things".

Marking as duplicate to clean up the issue queue.

lauriii’s picture

Status: Closed (duplicate) » Active

Opening this since there is still open child issues.

joelpittet’s picture

Category: Task » Plan

Version: 8.0.x-dev » 8.1.x-dev

Drupal 8.0.6 was released on April 6 and is the final bugfix release for the Drupal 8.0.x series. Drupal 8.0.x will not receive any further development aside from security fixes. Drupal 8.1.0-rc1 is now available and sites should prepare to update to 8.1.0.

Bug reports should be targeted against the 8.1.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.2.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.1.x-dev » 8.2.x-dev

Drupal 8.1.9 was released on September 7 and is the final bugfix release for the Drupal 8.1.x series. Drupal 8.1.x will not receive any further development aside from security fixes. Drupal 8.2.0-rc1 is now available and sites should prepare to upgrade to 8.2.0.

Bug reports should be targeted against the 8.2.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.3.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.2.x-dev » 8.3.x-dev

Drupal 8.2.6 was released on February 1, 2017 and is the final full bugfix release for the Drupal 8.2.x series. Drupal 8.2.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.3.0 on April 5, 2017. (Drupal 8.3.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.3.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.4.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.3.x-dev » 8.4.x-dev

Drupal 8.3.6 was released on August 2, 2017 and is the final full bugfix release for the Drupal 8.3.x series. Drupal 8.3.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.4.0 on October 4, 2017. (Drupal 8.4.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.4.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.5.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.4.x-dev » 8.5.x-dev

Drupal 8.4.4 was released on January 3, 2018 and is the final full bugfix release for the Drupal 8.4.x series. Drupal 8.4.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.5.0 on March 7, 2018. (Drupal 8.5.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.5.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.6.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.5.x-dev » 8.6.x-dev

Drupal 8.5.6 was released on August 1, 2018 and is the final bugfix release for the Drupal 8.5.x series. Drupal 8.5.x will not receive any further development aside from security fixes. Sites should prepare to update to 8.6.0 on September 5, 2018. (Drupal 8.6.0-rc1 is available for testing.)

Bug reports should be targeted against the 8.6.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.7.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.6.x-dev » 8.8.x-dev

Drupal 8.6.x will not receive any further development aside from security fixes. Bug reports should be targeted against the 8.8.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.9.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 8.8.x-dev » 8.9.x-dev

Drupal 8.8.7 was released on June 3, 2020 and is the final full bugfix release for the Drupal 8.8.x series. Drupal 8.8.x will not receive any further development aside from security fixes. Sites should prepare to update to Drupal 8.9.0 or Drupal 9.0.0 for ongoing support.

Bug reports should be targeted against the 8.9.x-dev branch from now on, and new development or disruptive changes should be targeted against the 9.1.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 8.9.x-dev » 9.2.x-dev

Drupal 8 is end-of-life as of November 17, 2021. There will not be further changes made to Drupal 8. Bugfixes are now made to the 9.3.x and higher branches only. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.2.x-dev » 9.3.x-dev

Version: 9.3.x-dev » 9.4.x-dev

Drupal 9.3.15 was released on June 1st, 2022 and is the final full bugfix release for the Drupal 9.3.x series. Drupal 9.3.x will not receive any further development aside from security fixes. Drupal 9 bug reports should be targeted for the 9.4.x-dev branch from now on, and new development or disruptive changes should be targeted for the 9.5.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.4.x-dev » 9.5.x-dev

Drupal 9.4.9 was released on December 7, 2022 and is the final full bugfix release for the Drupal 9.4.x series. Drupal 9.4.x will not receive any further development aside from security fixes. Drupal 9 bug reports should be targeted for the 9.5.x-dev branch from now on, and new development or disruptive changes should be targeted for the 10.1.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.5.x-dev » 11.x-dev

Drupal core is moving towards using a “main” branch. As an interim step, a new 11.x branch has been opened, as Drupal.org infrastructure cannot currently fully support a branch named main. New developments and disruptive changes should now be targeted for the 11.x branch. For more information, see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.