[META] Make sure Themers have sufficient docs for D8

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".

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.

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.

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

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:
https://github.com/sqndr/d8-theming-guide

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.

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 drupal.org (no book pages). Or we may want to (and given permission to) just copy the content to appropriate positions in the Drupal.org "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.

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 drupal.org, 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 drupal.org. 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 drupal.org (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.

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 https://www.drupal.org/theme-guide/8

These pages could be reviewed already:
- https://www.drupal.org/theme-guide/8/adding-javascript
- https://www.drupal.org/node/2353043
- https://www.drupal.org/node/2354645
- https://www.drupal.org/node/2349827
(and feel free to edit these pages directly)

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 ...

I created a page that lists some of the D7-D8 changes:
https://www.drupal.org/node/2356951

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?

This page https://www.drupal.org/node/2164207 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 (https://www.drupal.org/node/2186401) is basically a duplicate of the change record (https://www.drupal.org/node/2100775) 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.

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

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

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.

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.

Updated summary to reflect status of work

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 (https://www.drupal.org/node/1906780) 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.

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"

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

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

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

Note that there is also a page about css now: https://www.drupal.org/theme-guide/8/adding-stylesheets

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.

https://www.drupal.org/node/2358785
https://www.drupal.org/node/1906392
https://www.drupal.org/node/1906780

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

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

Quite a few of the issues in the summary link to pages that are marked as "Incomplete" or "Need Technical Review":
https://www.drupal.org/node/2349827 Incomplete
https://www.drupal.org/node/2349803 Needs Technical Review
https://www.drupal.org/node/2354645 Needs Technical Review
https://www.drupal.org/node/2186401 Needs Technical Review
https://www.drupal.org/node/2356951 Incomplete

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

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

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.

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"?

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

All the pages in the 'to be completed section have been updated quite a few times since the last comment here 8 years ago. I am closing this as outdated. A new issue can be opened, if needed, to coordinate any remaining work in this area.