Theme developers require sufficient documentation to create new themes for Drupal 8 or porting their Drupal 7 themes to Drupal 8.

This documentation will form part of

This documentation should cover:

(Theming experts: Anything else that's essential?)

Still to Be Completed:

While much of the documentation now exists some is either 'Incomplete' or 'Requires Technical Review'.

Once these documents are marked as 'No Known Problems' this issue should be marked as fixed.

#22 Working with Twig Templates.txt3.38 KBbatigolix


batigolix’s picture

Issue tags: +sprint
LoMo’s picture

Wouldn't it make sense to split this up into tickets that several different people could work on during the sprints?

e.g. the first step could be to create "stub" pages for each proposed topic
- .info.yml file structure
- directory structure of themes
- basics of Twig (or link to good documentation of this)
- how to get CSS and JS included in the pages of a site
- how to update a theme from Drupal 7 to 8
- Other topics (?)

Then each of those could have a ticket for the documentation of that part.

I think the current ticket scope is a bit larger than ideal for division of labor and some of the sub-tasks might be relatively "novice", whereas others are certainly quite advanced, so division would help prevent, e.g., someone who knows about the YML structure from being daunted by the idea of having to tackle all of this.

Looking at what is already there, it's not insignificant (the documentation of D8 theming). It looks like the book structure could already use a bit of TLC (e.g. better grouping of the Twig-related sub-topics), then "stub" pages could be created for each of the other sub-topics indicated in this "parent ticket".

jhodgdon’s picture

Definitely! This is more of a "figure out what needs to be done" issue. When definite items are identified, they can be made into sub-issues.

LoMo’s picture

Title: Make sure Themers have sufficient docs for D8 » [META] Make sure Themers have sufficient docs for D8
Assigned: Unassigned » LoMo

I will just work on the structure, creating stub pages and some docs issues to let people know these are an area they can get involved. I am not an experienced themed, so will not do a lot more than prepare a space for the perceived needs.

LoMo’s picture

Issue summary: View changes
LoMo’s picture

I will continue this tomorrow and have a plan to sit down with mortendk to get feedback about what other pages we need, what content is now "stale", etc.

jhodgdon’s picture

Excellent, thanks!

batigolix’s picture

@LoMo: did you create issues for these? Can you link them here under issues?

LoMo’s picture

Having spoken with members of the frontend team, I think it makes most sense to temporarily put this on hold since they are working on a separate documentation effort, which is more current and more actively maintained by the experts. This includes example code, etc, and can be found on GitHub:

I suggest we simply link to that, for now, while I wait for a response to an issue I've raised with the maintainer of that project.

LoMo’s picture

Assigned: LoMo » Unassigned

For now, I will not do more on this. I'll tag each page with the notice and link pointing visitors to the Github repository the core frontend team are maintaining. Until I have heard back from the repository owner, I think this is most appropriate. We may wish to include this somehow, e.g. the way the API is maintained on (no book pages). Or we may want to (and given permission to) just copy the content to appropriate positions in the "book" and pay attention to commits since this is in active development. I've offered to help with grammar, sentence structure, typos, etc. Right now I doesn't make much sense to have a duplicated effort, especially since these guys are the experts.

batigolix’s picture

Interesting initiative.

I wonder if more Drupal documentation would move to github and what the consequences are. We see a similar trend with contrib modules moving to github. Maintainers of those projects announce that as soon as they have a production version the code will move back to, but will they really?

It could be an interesting experience to contribute to this theming guide on github to see what it feels like to write docs in a version controlled environment, with moderation, as opposed to our direct editing on It would be kind of the curated documentation approach we have been talking about for a while.

But, having considered all that, my first reaction is: let us continue building a theme guide on (copy pasting the interesting bits). That is where the users expect it to be and that is where everybody can contribute (without the need of github account and knowledge of git).

@LoMo: yes, please add a reference to the sqndr's github page (where is actual document for the end users to look at?), but not everywhere throughout the guide.

jhodgdon’s picture

Maintaining this documentation on Github going forward is NOT going to be OK.

The documentation definitely needs to be regular nodes on so that ordinary people can edit it on without needing to understand patches or have a separate outside account.

We recently tried to do something similar with the module API documentation that is currently on -- you can read all about the sorry outcome on the issue:
#2106873: [meta][policy, no patch] Make Drupal 8 developer docs more discoverable
Developers -- and we're talking about **module** developers here, not themers -- were highly resistant to this type of change. Themers would be even more so, I would think.

So... it's fine if the developers of the Twig system want to, for the moment, develop documentation on some outside repository on Github or wherever, but it's pretty clear that the Drupal community would, as a whole, rather use our current system for editing nodes on than an outside system using an easy-to-learn markdown syntax, and using revision control. To me, Github and some type of "markdown" has a lot of advantage, but the community has definitely spoken out loudly on this other issue. To me personally this is very sad, but the community has definitely spoken and they win. :(

So, the documentation does need to be moved to eventually and become the Drupal 8 theme guide, so that everyone can edit it in the manner they apparently prefer.

batigolix’s picture

Issue summary: View changes
batigolix’s picture

I spent quite some time last week working on the D8 theming guide and some pages are more or less done.

See the (updated) issue summary and

These pages could be reviewed already:
(and feel free to edit these pages directly)

batigolix’s picture

Issue summary: View changes
batigolix’s picture

I think we should list the differences between D7 & D8 on a dedicated page instead of mentioning the difference per topic. In 1 year time information about D7 within D8 docs will become quite useless ...

batigolix’s picture

I created a page that lists some of the D7-D8 changes:

eojthebrave’s picture

Making some good progress here. Nice t see.

I would also add:

  • Security - What do I need to know?
  • How do I filter my data with Twig?
  • How do I determine which variables are available for a given template file?
  • How do I create new variables for my theme?
  • Tips for debugging
  • How to add regions to my theme?

To the list of critical topics.

And if we're going to be making an entirely new theming guide for D8 as per #2066017, which was closed in favor of this issue. Then I would also recommend we cover some of the higher-level conceptual things in addition to all the task based things we've got on the list so far.

  • What is a theme?
  • How does Drupal decide when to load which templates? i.e. template naming conventions for the twig files
  • How is a page rendered by Drupal, and at what points can we affect the display of the site?
  • What are regions?
eojthebrave’s picture

This page as a lot of good information, but it assumes knowledge of Drupal 7. I think it would be best if it was updated so that it's useful for someone without Drupal 7 / PHPTemplate knowledge.

This page on template suggestions ( is basically a duplicate of the change record ( and should be updated to explain the process for adding template suggestions for D8 and then simply link to the change record for anyone who wants to know the difference between D7 and D8 methods.

eojthebrave’s picture

Continuing to review the existing D8 theming content. I'm just going to keep adding my notes/thoughts here so they don't get lost.

Right now we have this one Working with Twig Templates, which talks about naming conventions and where to find templates.

This one Working with theme suggestions, that talks a little about template discovery, and compares the d7 and d8 way of doing theme hook suggestions.

And this one Overriding templates with theme hook suggestions, which covers all of the above plus some. But appears to be mostly copy/paste from the D7 version of the same page. I fixed the links and issues that were easy to see, but I don't know D8 well enough to do a thorough technical review of the page but I suspect there are other things as well.

These three pages could probably be combined either into one, or into a better outline with multiple pages that covers:

- How templates are discovered
- How to override a template
- Template naming conventions
- Adding additional template suggestions

batigolix’s picture

I started updating Overriding templates with theme hook suggestions to Drupal 8. I based it on the Drupal 7 version of that page. I think we should keep that as the main page that explain template overriding.

It would be great to merge it with Working with Twig Templates and Working with theme suggestions , if they do not contain any additional info.

From the title I would expect to find template code examples in Working with Twig Templates

batigolix’s picture

I'm deleting the Working with Twig Templates page because it is a potpourri of theming topics that are covered elsewhere better. For future reference I attach the body content to this issue.

batigolix’s picture

So I restructured the pages regarding theme suggestions

Resulting in:
Overriding templates with child page
Template naming coonventions and

As mentioned, I removed Working with Twig Templates

Please have a look.

batigolix’s picture

Issue summary: View changes

Updated summary to reflect status of work

eojthebrave’s picture

Nice work batigolix. Thanks!

I went through both and tried to fix anything that I could find that needed fixing. I also renamed the "Overriding templates" page to "Working With Twig Templates" as I feel that better explains what this page, and it's children are about. I know we just removed a page with that same name, but I think the name of that page was good, it's content was just duplication of these two pages you just worked on. Feel free to change it back if you think this is a bad idea.

I moved the page that was formerly titled "Debugging twig variables" under the working with twig templates page. I did this because the debugging page ( is all about using the dump() function to inspect and discover the contents of variables within the context of a twig template. A task that seems more like "Working with templates" than debugging. I also renamed it to "Discovering and Inspecting Variables in Twig Templates".

This helps with the comment about "How do I determine which variables are available for a given template file?" I made in comment 18.

batigolix’s picture

Maybe we could start changing some of the page statuses to "No known problems"? That could be a start to finalize this effort to give themers a D8 guide to start with.

See the list in the summary under "This documentation should cover"

batigolix’s picture

We haven't talked about CSS yet. We should also explain how to add CSS files to a theme

Cottser’s picture

I want to give a big thanks to @batigolix and @eojthebrave for all the work here, it's looking very nice IMO :)

jhodgdon’s picture

@Cottser: Second the thanks!

Do you think the docs are sufficient and we should close this issue then?

Cottser’s picture

I haven't yet reviewed it thoroughly enough to give an answer to that. But my gut feeling is we are pretty close :)

batigolix’s picture

Issue summary: View changes

Note that there is also a page about css now:

Cottser’s picture

I'm starting to go through this in more detail and make some small corrections/clarifications along the way :)

One thing I noticed is there are three closely related pages for debugging/locating template files, two of which explain usage of dump(). The dump() parts I think should be consolidated/crosslinked. Also, the second link below has some useful information about firebug but the main page about twig_debug HTML comments doesn't have that, so it should be moved/consolidated IMO.

jhodgdon’s picture

Sounds great @Cottser, thanks!

jhodgdon’s picture

I made some changes to today -- please review! These changes were in conjunction with #2298551: Documentation updates adding/adjusting inline/external JS in themes.

lauriii’s picture

We should work on this at least in the post 8.0.0-rc1 state.

joelpittet’s picture

joelpittet’s picture

Status: Active » Fixed
Issue tags: -rc target triage

Second thought all the things in the issue summary say DONE. This is fixed.

serg2’s picture

Quite a few of the issues in the summary link to pages that are marked as "Incomplete" or "Need Technical Review": Incomplete Needs Technical Review Needs Technical Review Needs Technical Review Incomplete

Would it be best to leave this open until they are reviewed and finished?

joelpittet’s picture

Status: Fixed » Needs work
Issue tags: +Needs issue summary update

Yes good call, @Lostandfound can you put those in the issue summary?

serg2’s picture

Issue summary: View changes
serg2’s picture

Issue summary: View changes
serg2’s picture

Issue summary: View changes

I have updated the issue summary to reflect the current status of the documentation pages.

There is still a lot of movement wrt the base themes, Stable/Classy. Currently there is no mention of Stable in the documentation so maybe, once the issues are closed, something should be added and possibly an overview of how the themes inherit from the bases.
Some of the open Stable / Classy issues are: #2581443: Make Classy extend from the new Stable base theme, #2575737: Copy templates, CSS, and related assets to Stable and override core libraries' CSS and #2588303: Stable base theme in core.

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.

rootwork’s picture

Is this still current? There's obviously been a lot more documentation added since the last update, but there are certainly still some gaps.

How do we know when this issue is "done"?

joelpittet’s picture

This would be complete when all the things in Still to Be Completed: are complete.