Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

HTML Structure Documentation #727

Closed
9to5IT opened this issue Apr 11, 2015 · 15 comments
Closed

HTML Structure Documentation #727

9to5IT opened this issue Apr 11, 2015 · 15 comments

Comments

@9to5IT
Copy link

9to5IT commented Apr 11, 2015

Hi,

I just started using underscores.me and I really like it so far - so thanks very much.

The only thing I thought that would be useful if there was some documentation around the HTML \ CSS structure (even at a high level). I created a high-level HTML structure document for myself, so I thought I would share with you guys in case you are interested in providing it to others.

Attached is the image of the HTML structure, however I can provide you the original document so that you can edit it if you like. If you are interested, email me on [email protected].

Thanks for an awesome starter theme.
Luca

html structure - underscores
@philiparthurmoore
Copy link
Collaborator

This is really cool. I love it. The only thing I'd say is that _s changes sometimes so if we have an image that isn't maintained well it could become confusing for a lot of people. The activity on _s feels really slow so I think having an image like this is a good idea; I'm just concerned about keeping it updated.

Also, I'm not really sure where this belongs.

@9to5IT
Copy link
Author

9to5IT commented Apr 11, 2015

It could be included as another file along with readme.md. The Getting Started section of readme.md could make reference to it. To keep it up to date, you can just include it in any commit that changes the structure of the HTML. Alternatively, you could put it on the website, however I could see it not being updated as regular as it is separate to the commit process.

I created it using Diagrammix, so pretty easy to update. I could also be easily ported into Visio if required or even something like Photoshop.

Let me know if you want the Diagrammix file.

@pablopaul
Copy link

@9to5IT nice graphic, how did you make it?

@9to5IT
Copy link
Author

9to5IT commented Apr 14, 2015

Hi @pablopaul, I used Diagrammix to do it - it is a Mac OSX app. It is pretty good.

Email me on [email protected] and I can send you the file if you like

@mrwweb
Copy link
Contributor

mrwweb commented Apr 15, 2015

See also: The diagrams in @mor10's recent _s presentation: http://mor10.com/building-themes-from-scratch-using-underscores-at-wordcamp-seattle-experienced-edition-2015/

@mor10
Copy link
Contributor

mor10 commented Apr 15, 2015

I'm actually working on something quite a bit more involved and dynamic. No immediate projection on when it'll be done but I'll keep you all posted if you like.

@saulbaizman
Copy link

Hi there, this message is on a tangentially related topic. I created a series of diagrams to show the relationship between the 'official' WordPress primary template files and the constituent files (like content-*.php) included by them. I've attached a low-resolution example to this message. All of the diagrams can be seen here:

https://www.dropbox.com/s/gfzg2datqsnjlp6/underscores-diagrams.pdf?dl=0
underscores-diagrams-page-1

There's little documentation about how to use _s, and I think these diagrams would help new users. I'm happy to share them with the _s community as is or even revise them based on feedback. Thanks!

@9to5IT
Copy link
Author

9to5IT commented Apr 21, 2015

@saulbaizman This is an awesome idea! Thanks very much.

@renzosalvador
Copy link

Great work. thanks!

@saulbaizman
Copy link

Thanks, @9to5IT and @renzosalvador! I'd like to propose that these diagrams, or some kind of diagram / visual documentation, be distributed with _s. Do you know who I could contact, and how?

@obenland
Copy link
Member

This should probably rather live in a docs section on underscores.me.

@saulbaizman
Copy link

@obenland It would be wonderful to have the diagrams placed in a documention section on underscores.me. How do we make this happen?

@mtomas7
Copy link
Contributor

mtomas7 commented May 5, 2015

For readme.txt of my theme I use condensed version of real html:

Theme document structure
========================

This might help you when applying CSS rules to see the "Cascades" of Cascading Style Sheets.

Example for single.php
----------------------

<body <?php body_class(); ?>>
    <div id="page" class="hfeed site">
        <header id="masthead" class="site-header" role="banner">
            <div class="site-branding">
                <a class="site-logo-link" rel="home" href="">
                    <img class="site-logo attachment-thumbnail" data-size="thumbnail">
                <div id="site-title-wrapper">
                    <h1 class="site-title">
                    <h2 class="site-description">
            <nav id="site-navigation" class="main-navigation" role="navigation">
        <div id="content" class="site-content">
            <div id="primary" class="content-area">
                <main id="main" class="site-main" role="main">
                    <article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
                        <header class="entry-header">
                            <h1 class="entry-title">
                            <div class="entry-meta">
                        <div class="entry-content">
            <aside id="secondary" class="widget-area" role="complementary">
                <section id="recent-posts-5" class="widget widget_recent_entries">
                    <h3 class="widget-title">Recent Articles</h2>
                        <ul>
                            <li>
        <footer id="colophon" class="clear" role="contentinfo">
            <div id="footer-widgets" class="widget-area three">
                <div id="footer-widget-left">
                    <section id="recent-posts-4" class="widget widget_recent_entries">
                        <h3 class="widget-title">Recent articles</h2>
                            <ul>
                                <li>


Archive example for category.php
--------------------------------

            ...
            <section id="primary" class="content-area">
                <main id="main" class="site-main" role="main">
                    <header class="page-header">
                        <h1 class="page-title">
                    <article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
                        <header class="entry-header">
                            <h1 class="entry-title">
                            <div class="entry-meta">
                        <div class="entry-content">
            ...

@9to5IT
Copy link
Author

9to5IT commented May 6, 2015

@saulbaizman @obenland I think so too, there should be a documentation folder as part of the standard template. I am not sure how to get that in there? I thought raising an issue would help, hence this issue. Does anyone know who to talk to about this?

@karmatosed
Copy link
Contributor

This should not be in a readme.txt file. Documentation is already being planned on underscores.me:

Automattic/underscores.me#36

What I don't agree with is the diagrams and over complication. It's just not needed. The first diagram in this ticket whilst I appreciate the work it's way too complex and not something as useful as you may think. A lot of people (myself included) would not use a diagram like this. I think absolutely, we should invest our time in documentation that covers our pain points and makes things easy to understand. Complication in documentation is always dangerous.

I am closing, not because we shouldn't do documentation, but we have a ticket to work that out on underscores.me.

@olegovk olegovk mentioned this issue Jul 31, 2018
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
10 participants
@philiparthurmoore @karmatosed @pablopaul @mor10 @mrwweb @obenland @mtomas7 @renzosalvador @saulbaizman @9to5IT