Take the 2-minute tour ×
WordPress Development Stack Exchange is a question and answer site for WordPress developers and administrators. It's 100% free, no registration required.

I am making readme.html file for a plugin with some detailed setup instruction that need to include screenshots.

As rest of UI I want it be consistent with WordPress style and so I looked at its own readme.html.

It includes stylesheet with relative path:

<link rel="stylesheet" href="wp-admin/css/install.css?ver=20100228" type="text/css" />

So for a plugin file I might go with:

<link rel="stylesheet" href="/wp-admin/css/install.css" type="text/css" />

But it is good way to include styling? There are really many ways to do it:

  • link to install.css;
  • bundle copy of install.css with plugin;
  • bundle own CSS file with plugin;
  • embed style in readme.html.

I am not aware of any recommendation about providing HTML documentation with plugins.

Had you included HTML documentation with plugins (or themes, whatever)? What method had you chosen to style it and what was you reasoning for it?

share|improve this question
    
For styling a single HTML page, i'd just plonk any css directly in the head of the document. –  t31os Mar 15 '11 at 13:35
    
Do you intend to include a link to the readme file somewhere in the WP backend (e.g. on your plugin's options page)? –  tnorthcutt Mar 15 '11 at 13:38
    
@t31os also a valid option, do you mind moving that to an answer with some pro/con points? :) @tnorthcutt yes, contextual help section on plugin admin page will likey contain link(s) to readme. –  Rarst Mar 15 '11 at 13:43
    
Added answer + an additional idea. –  t31os Mar 15 '11 at 14:30
add comment

3 Answers

up vote 1 down vote accepted

It would be better to include your own CSS file that way you can:

  • Use a relative path to your CSS.
  • Avoid problems getting the path right to the wp-admin directory. Not all people put WordPress in the root directory, so your example above would break for them.
  • Possibly redundancy by reusing the CSS in your HTML & admin pages for your plugin.
share|improve this answer
    
Thanks for input, getting path to wp-admin reliably is definitely an issue without PHP code to handle it. Admin pages are build purely with Settings API and require no custom styling. That's why I want to look into using existing style for readme as well and not bloat plugin with it. –  Rarst Mar 15 '11 at 13:29
    
I upvoted all answers, but this is closest to what I ended up with - copy of install.css bundled with plugin. I think it would be easiest for maintenance and saves me from wasting time on own stylesheet. –  Rarst Mar 21 '11 at 15:37
add comment

I suggest you take a look at Justin Tadlock's Get the Image plugin. He includes readme.html, readme.txt, and readme.css.

Regarding the path to your css file, what you posted wouldn't make sense (I don't think). I'd suggest something like

<link rel="stylesheet" href="readme.css" type="text/css />

and just put readme.css in the same directory as your readme.html file.

share|improve this answer
    
Yeah, Justin always provides great readmes, but I think he uses custom styling (something I'd rather not go into). btw what I posted would work under typical setup. Relative URI that starts with / means link relative to domain, rather than current directory. On other hand if WP is in sub-directory that path is toast... –  Rarst Mar 15 '11 at 13:27
    
Ok, I understand now. I didn't realize you were wanting to literally use the existing stylesheet used by WP for your plugin readme - that makes sense. However, I wouldn't worry that much about plugin bloat from a simple CSS file. –  tnorthcutt Mar 15 '11 at 13:37
add comment

I can't think why you'd bundle a stylesheet alongside a readme, it's viewed independantly from anything else, so why not just put that same CSS in the HTML file(seeing as you're going to have to maintain it anyway).

<style type="text/css">
/* 
.example { }
*/
</style>

Using inline styles:

Pros

  • One less HTTP request
  • No extra files to manage
  • No need to worry about any path problems

Cons

  • No included stylesheet(you'll have to maintain your CSS inline with the WP install.css)
  • All styling will have to be managed(and maintained) inside the readme document

- Not really a big deal, the CSS will be right near the top of the file.


What i'd actually do though is just use an external source, that will update inline with WordPress, and you'll avoid any pathing issues(because the external path should always be valid).

Maybe use WordPress.com as the source?

<link rel="stylesheet" type="text/css" href="http://s%NUM%.wp.com/wp-admin/css/install.css" />

Where %NUM% would be a numeric value(eg. 1 or 5, and so on..) to represent which server you want to pull the CSS from. I tested upto s20.wp.com, not sure how high they go.

That way you at least know a few users will have it cached already.

You could also use the WordPress.org svn or any number of other places that serve up WordPress CSS, i just figured WordPress.com blogs are popular and more likely to be cached.

share|improve this answer
    
External source will often make sense, but in this specific case I do not want to assume that user has external internet connection (and not working with intranet WP installation for example). –  Rarst Mar 15 '11 at 14:33
    
Then that limits you to including a stylesheet alongside the readme or CSS in the head. Including the WordPress install.css won't be reliable simply because the wp-content directory can be moved, and means you cannot build a reliable relative path based on the server root or the current document(ie. the readme). –  t31os Mar 15 '11 at 14:38
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.