2

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?

Improve this question
4
  • For styling a single HTML page, i'd just plonk any css directly in the head of the document.
    – t31os
    Mar 15, 2011 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)?
    – Travis Northcutt
    Mar 15, 2011 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, 2011 at 13:43
  • Added answer + an additional idea.
    – t31os
    Mar 15, 2011 at 14:30

3 Answers 3

Reset to default
1

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.
Improve this answer
2
  • 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, 2011 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, 2011 at 15:37
1

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.

Improve this answer
2
  • 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, 2011 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.
    – Travis Northcutt
    Mar 15, 2011 at 13:37
1

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.

Improve this answer
2
  • 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, 2011 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, 2011 at 14:38

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

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