Write understanding-themes.txt

Note: As of July 27, the "DripDocs" team is planning to work on this issue, so for anyone else, unless you have *really* strong desire to do it, if this date is not too far in the past, you might pick another topic. Thanks!

Adding checklist to summary

@kvantomme, @diana.lakatos: Is the DripDocs team still planning to work on this topic? If so, do you have a time frame? If not, please unassign the issue so someone else can work on it. Thanks!

I'm going to hold on to this one for a little longer, I've already got one done...

OK, sounds good! Thanks for the update!

Since this hasn't yet been started, I think I will go ahead and un-assign it. If you do plan to work on it soon, please feel free to reclaim it. Thanks!

Hi, here's a first pass.

edit: three 9s, not bad..

Thanks for taking this on! Great start, and I think it covers most of the topic.

A few factual/terminology things to address/consider:

a) There's an actual thing in Drupal called a "base theme", which is a theme that isn't meant to be used as a theme on a site, but is meant to be used as a basis for other themes to build on. But your usage in this topic doesn't seem to mean that. I think maybe where you said "base theme" you could just say "basic themes" or ... maybe just say "themes" (talking about that Drupal core provides some themes). (Specifically, neither Bartik nor Seven is really a "base theme".)

b) You said that a "simple theme is made up of CSS and JavaScript". I am not sure that simple themes really have JavaScript in them?

c) I don't think Drupal gives you tools to manage events "out of the box"... I probably wouldn't use the term "out of the box" anyway, since it doesn't come in a box. ;) We'd like to just use clear straightforward documentation language rather than jargon, slang, or things that people with possibly more limited English skills, or translators, wouldn't understand.

d) I'm not really sure what this means:

"Drupal provides several different base HTML structures with the base themes that ship with it the core. "

What is a "base HTML structure"?

e) We should probably say that if you want to make your own markup, you'd need to create your own theme. I know that, but it's not really clear from the proposed writing.

f) We should also mention that you can download additional contributed themes from drupal.org (give the URL for that).

g) Take a look again at the "Covers" for this topic... I think we need to stress the content vs. the theme:

What the theme has control over (layout, styles; some HTML markup; images for buttons, backgrounds, etc.) vs. what is in the database and files (HTML markup that is part of content, images that are part of content)

Totally agree. Try this?

Looking better!

The only thing I think could be improved would be to take the part you put at the end under "What isn't a theme?" and put it way up towards the beginning. To me, the most fundamental/important thing about themes is that your content is stored in the database and asset files (images, etc.), and the modules pull from the database and assets to define what should be on the page, but the theme has full control the HTML markup and CSS (aside from any HTML markup that is included in the content, as you said).

I just don't think this concept belongs as kind of an afterthought at the bottom... thoughts?

Good call, thank you! Could you help me figure out how to create links to other pages in the user guide?

I'm not 100% percent on the first paragraph, so let me know what you think. Thanks jhodgdon!

Making links to other pages in the guide:
https://userguide_new-drupal.dev.devdrupal.org/guidelines/formatting.html -- see section 1.3.4 on cross-linking [drupal/drupal to log in]

The IDs for topics are the file name without the .txt. So for example the topic "Concept: Cron", in the security-cron-concept.txt file, has ID security-cron-concept and you can make a link to it using:

<<security-cron-concept>>

To find the ID:
- check the tracking spreadsheet to find the file name of a topic
- In the in-progress guide, if you go to a topic page via the navigation, there's a line near the top saying : ID: .... that tells you the ID of the topic. So see
https://userguide_new-drupal.dev.devdrupal.org/d8guide/en/security-cron-...
and it says
ID: security-cron-concept

So... What I would like to see in this topic is just one heading "What is a theme?". I would start it out with this sentence that you wrote: "A theme is a set of files that define the visual look and feel of your site." This will define what "theme" means, before you start using it in other writing.

Next, I think in the same paragraph I would continue with something like this:

The core software and modules that run on your site and determine which _content_ (including HTML text and other data stored in the database, and uploaded images and other asset files) gets displayed on the pages of your site, and which _settings_ determine how it should be displayed; the theme, paying attention to the settings, determines the HTML markup and CSS styling that wraps the content.

Then I think I would include the other paragraphs you wrote about:
- the basic themes provided with the base download
- the base themes
- other themes you can download from drupal.org [that is currently missing]
- creating your own theme

Thoughts?

Thanks, although with these edits I don't have any links to other pages anymore. Maybe with the next one...

So yeah, I think that tightens it up a lot. This version is basically what you outlined, with a couple edits. I removed the part about "which _settings_ determine how it should be displayed". Even thought it's not a 100% feature complete explanation I feel like leaving that out makes it easier to digest.

The D8 contrib theme space is a little thin right now, so I just linked to the search page on D.O (for now).

Let me know what you think of this pass. Thanks jhodgdon..

Great! I think you're right about the settings -- just complicates things to mention it. Very clear as it is.

So. This is looking good. ... So let's think about this one more time. To summarize this version, the paragraphs are:

a) What is a theme [excellent].

b) Basic themes provided by the core distro [excellent].

c) Base themes in the core distro and subthemes [excellent].

d) Creating a custom theme [see below, I have a suggestion or two].

e) Downloading a new theme [see below, I have a suggestion or two].

So. I'm thinking about the order... In order of difficulty, you would probably want to do:
(b), then (e), then (c) and (d). So let's change that order.

Also, (c) [subtheming] is kind of a subset of (d) [creating your own theme]. Is there a way we can combine them into one paragraph? Other thoughts on (d):
- I think it can be cut down a bit and rather than explaining about Twig and all that (since this is a site builder guide and not a guide for theming) -- so we could just mention you can create your own theme and that Core has some base themes included, and link to the theming guide?
- When creating links, it is important for the link text to tell you what you're linking to. So link text like "found here" as in:

https://www.drupal.org/theme-guide/8[found here]

is not as good as making it something like:

For more information about creating your own theme, see the https://www.drupal.org/theme-guide/8[Theming guide].

And my thoughts on (e):
- We have a topic called "Finding Themes" (ID: extend-theme-find) that covers how to find, evaluate, and download themes on drupal.org. So let's link to that rather than directly to the drupal.org theme search page
- There's also topic ID extend-theme-install, which I think should be in Related Topics, which tells (once you've found a theme) how to download it, unzip, install.
- I would like to avoid talking about the current state of Drupal 8, such as "Drupal 8 is relatively new, but as it matures...". If we put that in the guide, we'll just have to update it later. We also don't really want to use the word Drupal or mention the version (8) at all (because this guide could be branched for Drupal 9, Drupal 7, Backdrop, etc. -- and the less you have to change the better!). So we can take care of it in a later copy editing phase, or now... I think it would just be better to say that if you don't like the basic themes provided in the core download, you can check <<extend-theme-find>> to learn how to download a new theme. And then maybe just mention that commercial themes may also be available for purchase, and leave it at that.

Thoughts?

I just ditched the subtheming paragraph altogether. Try this.

I like it!

So... Sorry for not noticing before but your "Attributions" information is missing. Please provide that, and then I can add this to the guide.

Thanks for all the iterations!

Is a patch acceptable? Attached.

Thank you! Hopefully the next ones will take less of your editorial time..

Sure! And no worries about editorial time. It's very satisfying the way the guide is coming together. :)

Next time for attributions, you do not even have to make a patch. You can just put it into either a comment or the issue summary. Or make a patch. Whatever you prefer.

Anyway, thanks! Added to the guide.